Ruby  3.4.0dev (2024-11-22 revision 0989400a925cd201defdca9eb28eb87200b30785)
Typedefs | Enumerations | Functions
prism.h File Reference

(0989400a925cd201defdca9eb28eb87200b30785)

The main header file for the prism parser. More...

#include "prism/defines.h"
#include "prism/util/pm_buffer.h"
#include "prism/util/pm_char.h"
#include "prism/util/pm_integer.h"
#include "prism/util/pm_memchr.h"
#include "prism/util/pm_strncasecmp.h"
#include "prism/util/pm_strpbrk.h"
#include "prism/ast.h"
#include "prism/diagnostic.h"
#include "prism/node.h"
#include "prism/options.h"
#include "prism/pack.h"
#include "prism/parser.h"
#include "prism/prettyprint.h"
#include "prism/regexp.h"
#include "prism/static_literals.h"
#include "prism/version.h"
#include <assert.h>
#include <errno.h>
#include <locale.h>
#include <math.h>
#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <strings.h>
Include dependency graph for prism.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef char *() pm_parse_stream_fgets_t(char *string, int size, void *stream)
 This function is used in pm_parse_stream to retrieve a line of input from a stream. More...
 

Enumerations

enum  pm_string_query_t { PM_STRING_QUERY_ERROR = -1 , PM_STRING_QUERY_FALSE , PM_STRING_QUERY_TRUE }
 Represents the results of a slice query. More...
 

Functions

PRISM_EXPORTED_FUNCTION const char * pm_version (void)
 The prism version and the serialization format. More...
 
PRISM_EXPORTED_FUNCTION void pm_parser_init (pm_parser_t *parser, const uint8_t *source, size_t size, const pm_options_t *options)
 Initialize a parser with the given start and end pointers. More...
 
PRISM_EXPORTED_FUNCTION void pm_parser_register_encoding_changed_callback (pm_parser_t *parser, pm_encoding_changed_callback_t callback)
 Register a callback that will be called whenever prism changes the encoding it is using to parse based on the magic comment. More...
 
PRISM_EXPORTED_FUNCTION void pm_parser_free (pm_parser_t *parser)
 Free any memory associated with the given parser. More...
 
PRISM_EXPORTED_FUNCTION pm_node_tpm_parse (pm_parser_t *parser)
 Initiate the parser with the given parser. More...
 
PRISM_EXPORTED_FUNCTION pm_node_tpm_parse_stream (pm_parser_t *parser, pm_buffer_t *buffer, void *stream, pm_parse_stream_fgets_t *fgets, const pm_options_t *options)
 Parse a stream of Ruby source and return the tree. More...
 
PRISM_EXPORTED_FUNCTION void pm_serialize_parse_stream (pm_buffer_t *buffer, void *stream, pm_parse_stream_fgets_t *fgets, const char *data)
 Parse and serialize the AST represented by the source that is read out of the given stream into to the given buffer. More...
 
void pm_serialize_comment_list (pm_parser_t *parser, pm_list_t *list, pm_buffer_t *buffer)
 Serialize the given list of comments to the given buffer. More...
 
void pm_serialize_encoding (const pm_encoding_t *encoding, pm_buffer_t *buffer)
 Serialize the name of the encoding to the buffer. More...
 
void pm_serialize_content (pm_parser_t *parser, pm_node_t *node, pm_buffer_t *buffer)
 Serialize the encoding, metadata, nodes, and constant pool. More...
 
PRISM_EXPORTED_FUNCTION void pm_serialize (pm_parser_t *parser, pm_node_t *node, pm_buffer_t *buffer)
 Serialize the AST represented by the given node to the given buffer. More...
 
PRISM_EXPORTED_FUNCTION void pm_serialize_parse (pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data)
 Parse the given source to the AST and dump the AST to the given buffer. More...
 
PRISM_EXPORTED_FUNCTION void pm_serialize_parse_comments (pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data)
 Parse and serialize the comments in the given source to the given buffer. More...
 
PRISM_EXPORTED_FUNCTION void pm_serialize_lex (pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data)
 Lex the given source and serialize to the given buffer. More...
 
PRISM_EXPORTED_FUNCTION void pm_serialize_parse_lex (pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data)
 Parse and serialize both the AST and the tokens represented by the given source to the given buffer. More...
 
PRISM_EXPORTED_FUNCTION bool pm_parse_success_p (const uint8_t *source, size_t size, const char *data)
 Parse the source and return true if it parses without errors or warnings. More...
 
PRISM_EXPORTED_FUNCTION const char * pm_token_type_name (pm_token_type_t token_type)
 Returns a string representation of the given token type. More...
 
const char * pm_token_type_human (pm_token_type_t token_type)
 Returns the human name of the given token type. More...
 
PRISM_EXPORTED_FUNCTION void pm_dump_json (pm_buffer_t *buffer, const pm_parser_t *parser, const pm_node_t *node)
 Dump JSON to the given buffer. More...
 
PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_local (const uint8_t *source, size_t length, const char *encoding_name)
 Check that the slice is a valid local variable name. More...
 
PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_constant (const uint8_t *source, size_t length, const char *encoding_name)
 Check that the slice is a valid constant name. More...
 
PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_method_name (const uint8_t *source, size_t length, const char *encoding_name)
 Check that the slice is a valid method name. More...
 

Detailed Description

The main header file for the prism parser.

Definition in file prism.h.

Typedef Documentation

◆ pm_parse_stream_fgets_t

typedef char*() pm_parse_stream_fgets_t(char *string, int size, void *stream)

This function is used in pm_parse_stream to retrieve a line of input from a stream.

It closely mirrors that of fgets so that fgets can be used as the default implementation.

Definition at line 88 of file prism.h.

Enumeration Type Documentation

◆ pm_string_query_t

Represents the results of a slice query.

Enumerator
PM_STRING_QUERY_ERROR 

Returned if the encoding given to a slice query was invalid.

PM_STRING_QUERY_FALSE 

Returned if the result of the slice query is false.

PM_STRING_QUERY_TRUE 

Returned if the result of the slice query is true.

Definition at line 240 of file prism.h.

Function Documentation

◆ pm_dump_json()

PRISM_EXPORTED_FUNCTION void pm_dump_json ( pm_buffer_t buffer,
const pm_parser_t parser,
const pm_node_t node 
)

Dump JSON to the given buffer.

Parameters
bufferThe buffer to serialize to.
parserThe parser that parsed the node.
nodeThe node to serialize.

Definition at line 3019 of file node.c.

◆ pm_parse()

Initiate the parser with the given parser.

Parameters
parserThe parser to use.
Returns
The AST representing the source.

Initiate the parser with the given parser.

Definition at line 22436 of file prism.c.

Referenced by pm_parse_stream(), pm_parse_success_p(), pm_serialize_lex(), pm_serialize_parse(), pm_serialize_parse_comments(), and pm_serialize_parse_lex().

◆ pm_parse_stream()

PRISM_EXPORTED_FUNCTION pm_node_t* pm_parse_stream ( pm_parser_t parser,
pm_buffer_t buffer,
void *  stream,
pm_parse_stream_fgets_t fgets,
const pm_options_t options 
)

Parse a stream of Ruby source and return the tree.

Parameters
parserThe parser to use.
bufferThe buffer to use.
streamThe stream to parse.
fgetsThe function to use to read from the stream.
optionsThe optional options to use when parsing.
Returns
The AST representing the source.

Prism is designed around having the entire source in memory at once, but you can stream stdin in to Ruby so we need to support a streaming API.

Definition at line 22517 of file prism.c.

Referenced by pm_serialize_parse_stream().

◆ pm_parse_success_p()

PRISM_EXPORTED_FUNCTION bool pm_parse_success_p ( const uint8_t *  source,
size_t  size,
const char *  data 
)

Parse the source and return true if it parses without errors or warnings.

Parameters
sourceThe source to parse.
sizeThe size of the source.
dataThe optional data to pass to the parser.
Returns
True if the source parses without errors or warnings.

Definition at line 22540 of file prism.c.

◆ pm_parser_free()

PRISM_EXPORTED_FUNCTION void pm_parser_free ( pm_parser_t parser)

Free any memory associated with the given parser.

Parameters
parserThe parser to free.

Definition at line 22410 of file prism.c.

Referenced by pm_parse_stream(), pm_parse_success_p(), pm_serialize_lex(), pm_serialize_parse(), pm_serialize_parse_comments(), pm_serialize_parse_lex(), and pm_serialize_parse_stream().

◆ pm_parser_init()

PRISM_EXPORTED_FUNCTION void pm_parser_init ( pm_parser_t parser,
const uint8_t *  source,
size_t  size,
const pm_options_t options 
)

Initialize a parser with the given start and end pointers.

Parameters
parserThe parser to initialize.
sourceThe source to parse.
sizeThe size of the source.
optionsThe optional options to use when parsing.

Definition at line 22117 of file prism.c.

Referenced by pm_parse_stream(), pm_parse_success_p(), pm_serialize_lex(), pm_serialize_parse(), pm_serialize_parse_comments(), and pm_serialize_parse_lex().

◆ pm_parser_register_encoding_changed_callback()

PRISM_EXPORTED_FUNCTION void pm_parser_register_encoding_changed_callback ( pm_parser_t parser,
pm_encoding_changed_callback_t  callback 
)

Register a callback that will be called whenever prism changes the encoding it is using to parse based on the magic comment.

Parameters
parserThe parser to register the callback with.
callbackThe callback to register.

Definition at line 22372 of file prism.c.

◆ pm_serialize()

PRISM_EXPORTED_FUNCTION void pm_serialize ( pm_parser_t parser,
pm_node_t node,
pm_buffer_t buffer 
)

Serialize the AST represented by the given node to the given buffer.

Parameters
parserThe parser to serialize.
nodeThe node to serialize.
bufferThe buffer to serialize to.

Definition at line 22584 of file prism.c.

Referenced by pm_serialize_parse_lex().

◆ pm_serialize_comment_list()

void pm_serialize_comment_list ( pm_parser_t parser,
pm_list_t list,
pm_buffer_t buffer 
)

Serialize the given list of comments to the given buffer.

Parameters
parserThe parser to serialize.
listThe list of comments to serialize.
bufferThe buffer to serialize to.

Definition at line 2028 of file serialize.c.

Referenced by pm_serialize_parse_comments().

◆ pm_serialize_content()

void pm_serialize_content ( pm_parser_t parser,
pm_node_t node,
pm_buffer_t buffer 
)

Serialize the encoding, metadata, nodes, and constant pool.

Parameters
parserThe parser to serialize.
nodeThe node to serialize.
bufferThe buffer to serialize to.

Serialize the encoding, metadata, nodes, and constant pool.

Definition at line 2121 of file serialize.c.

Referenced by pm_serialize(), pm_serialize_parse(), and pm_serialize_parse_stream().

◆ pm_serialize_encoding()

void pm_serialize_encoding ( const pm_encoding_t encoding,
pm_buffer_t buffer 
)

Serialize the name of the encoding to the buffer.

Parameters
encodingThe encoding to serialize.
bufferThe buffer to serialize to.

Definition at line 2098 of file serialize.c.

Referenced by pm_serialize_parse_comments().

◆ pm_serialize_lex()

PRISM_EXPORTED_FUNCTION void pm_serialize_lex ( pm_buffer_t buffer,
const uint8_t *  source,
size_t  size,
const char *  data 
)

Lex the given source and serialize to the given buffer.

Parameters
sourceThe source to lex.
sizeThe size of the source.
bufferThe buffer to serialize to.
dataThe optional data to pass to the lexer.

Definition at line 2195 of file serialize.c.

◆ pm_serialize_parse()

PRISM_EXPORTED_FUNCTION void pm_serialize_parse ( pm_buffer_t buffer,
const uint8_t *  source,
size_t  size,
const char *  data 
)

Parse the given source to the AST and dump the AST to the given buffer.

Parameters
bufferThe buffer to serialize to.
sourceThe source to parse.
sizeThe size of the source.
dataThe optional data to pass to the parser.

Parse the given source to the AST and dump the AST to the given buffer.

Definition at line 22595 of file prism.c.

◆ pm_serialize_parse_comments()

PRISM_EXPORTED_FUNCTION void pm_serialize_parse_comments ( pm_buffer_t buffer,
const uint8_t *  source,
size_t  size,
const char *  data 
)

Parse and serialize the comments in the given source to the given buffer.

Parameters
bufferThe buffer to serialize to.
sourceThe source to parse.
sizeThe size of the source.
dataThe optional data to pass to the parser.

Definition at line 22639 of file prism.c.

◆ pm_serialize_parse_lex()

PRISM_EXPORTED_FUNCTION void pm_serialize_parse_lex ( pm_buffer_t buffer,
const uint8_t *  source,
size_t  size,
const char *  data 
)

Parse and serialize both the AST and the tokens represented by the given source to the given buffer.

Parameters
bufferThe buffer to serialize to.
sourceThe source to parse.
sizeThe size of the source.
dataThe optional data to pass to the parser.

Definition at line 2225 of file serialize.c.

◆ pm_serialize_parse_stream()

PRISM_EXPORTED_FUNCTION void pm_serialize_parse_stream ( pm_buffer_t buffer,
void *  stream,
pm_parse_stream_fgets_t fgets,
const char *  data 
)

Parse and serialize the AST represented by the source that is read out of the given stream into to the given buffer.

Parameters
bufferThe buffer to serialize to.
streamThe stream to parse.
fgetsThe function to use to read from the stream.
dataThe optional data to pass to the parser.

Definition at line 22618 of file prism.c.

◆ pm_string_query_constant()

PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_constant ( const uint8_t *  source,
size_t  length,
const char *  encoding_name 
)

Check that the slice is a valid constant name.

Parameters
sourceThe source to check.
lengthThe length of the source.
encoding_nameThe name of the encoding of the source.
Returns
PM_STRING_QUERY_TRUE if the query is true, PM_STRING_QUERY_FALSE if the query is false, and PM_STRING_QUERY_ERROR if the encoding was invalid.

Definition at line 22764 of file prism.c.

◆ pm_string_query_local()

PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_local ( const uint8_t *  source,
size_t  length,
const char *  encoding_name 
)

Check that the slice is a valid local variable name.

Parameters
sourceThe source to check.
lengthThe length of the source.
encoding_nameThe name of the encoding of the source.
Returns
PM_STRING_QUERY_TRUE if the query is true, PM_STRING_QUERY_FALSE if the query is false, and PM_STRING_QUERY_ERROR if the encoding was invalid.

Definition at line 22744 of file prism.c.

◆ pm_string_query_method_name()

PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_method_name ( const uint8_t *  source,
size_t  length,
const char *  encoding_name 
)

Check that the slice is a valid method name.

Parameters
sourceThe source to check.
lengthThe length of the source.
encoding_nameThe name of the encoding of the source.
Returns
PM_STRING_QUERY_TRUE if the query is true, PM_STRING_QUERY_FALSE if the query is false, and PM_STRING_QUERY_ERROR if the encoding was invalid.

Definition at line 22784 of file prism.c.

◆ pm_token_type_human()

const char* pm_token_type_human ( pm_token_type_t  token_type)

Returns the human name of the given token type.

Parameters
token_typeThe token type to convert to a human name.
Returns
The human name of the given token type.

Definition at line 362 of file token_type.c.

◆ pm_token_type_name()

PRISM_EXPORTED_FUNCTION const char* pm_token_type_name ( pm_token_type_t  token_type)

Returns a string representation of the given token type.

Parameters
token_typeThe token type to convert to a string.
Returns
A string representation of the given token type.

Definition at line 17 of file token_type.c.

◆ pm_version()

PRISM_EXPORTED_FUNCTION const char* pm_version ( void  )

The prism version and the serialization format.

Returns
The prism version as a constant string.

Definition at line 7 of file prism.c.