The parser used to parse Ruby source. More...

#include "prism/compiler/nodiscard.h"
#include "prism/compiler/nonnull.h"
#include "prism/ast.h"
#include "prism/comments.h"
#include "prism/diagnostic.h"
#include "prism/line_offset_list.h"
#include "prism/magic_comments.h"
#include "prism/options.h"

Include dependency graph for parser.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct pm_parser_t	pm_parser_t
	The parser used to parse Ruby source.

typedef void(*	pm_encoding_changed_callback_t) (pm_parser_t *parser)
	When the encoding that is being used to parse the source is changed by prism, we provide the ability here to call out to a user-defined function.

typedef void(*	pm_lex_callback_t) (pm_parser_t parser, pm_token_t token, void *data)
	This is the callback that is called when a token is lexed.

typedef void(*	pm_comment_callback_t) (const pm_comment_t comment, void data)
	A callback function that can be used to process comments found while parsing.

typedef void(*	pm_magic_comment_callback_t) (const pm_magic_comment_t magic_comment, void data)
	A callback function that can be used to process magic comments found while parsing.

typedef void(*	pm_diagnostic_callback_t) (const pm_diagnostic_t diagnostic, void data)
	A callback function that can be used to process diagnostics found while parsing.

typedef void(*	pm_constant_callback_t) (const pm_constant_t constant, void data)
	A callback function that can be used to process constants found while parsing.

Functions
PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_parser_t *	pm_parser_new (pm_arena_t arena, const uint8_t source, size_t size, const pm_options_t *options) PRISM_NONNULL(1)
	Allocate and initialize a parser with the given start and end pointers.

PRISM_EXPORTED_FUNCTION void	pm_parser_free (pm_parser_t *parser) PRISM_NONNULL(1)
	Free both the memory held by the given parser and the parser itself.

PRISM_EXPORTED_FUNCTION void	pm_parser_encoding_changed_callback_set (pm_parser_t *parser, pm_encoding_changed_callback_t callback) PRISM_NONNULL(1)
	Register a callback that will be called whenever prism changes the encoding it is using to parse based on the magic comment.

PRISM_EXPORTED_FUNCTION void	pm_parser_lex_callback_set (pm_parser_t parser, pm_lex_callback_t callback, void data) PRISM_NONNULL(1)
	Register a callback that will be called whenever a token is lexed.

PRISM_EXPORTED_FUNCTION void *	pm_parser_lex_callback_data (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the opaque data that is passed to the lex callback when it is called.

PRISM_EXPORTED_FUNCTION const uint8_t *	pm_parser_start (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the raw pointer to the start of the source that is being parsed.

PRISM_EXPORTED_FUNCTION const uint8_t *	pm_parser_end (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the raw pointer to the end of the source that is being parsed.

PRISM_EXPORTED_FUNCTION int32_t	pm_parser_start_line (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the line that the parser was considered to have started on.

PRISM_EXPORTED_FUNCTION const char *	pm_parser_encoding_name (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the name of the encoding that is being used to parse the source.

PRISM_EXPORTED_FUNCTION size_t	pm_parser_encoding_char_width (const pm_parser_t parser, const uint8_t start, ptrdiff_t remaining) PRISM_NONNULL(1
	Returns the width of the character at the given pointer in the encoding that is being used to parse the source.

PRISM_EXPORTED_FUNCTION size_t PRISM_EXPORTED_FUNCTION bool	pm_parser_encoding_us_ascii (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns whether or not the parser is using the US-ASCII encoding.

PRISM_EXPORTED_FUNCTION const pm_string_t *	pm_parser_filepath (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the filepath that is being used to parse the source.

PRISM_EXPORTED_FUNCTION pm_constant_id_t	pm_parser_constant_find (const pm_parser_t parser, const uint8_t start, size_t length) PRISM_NONNULL(1
	Find a constant in the parser's constant pool.

PRISM_EXPORTED_FUNCTION pm_constant_id_t PRISM_EXPORTED_FUNCTION int8_t	pm_parser_frozen_string_literal (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the frozen string literal value of the parser, as determined by the frozen_string_literal magic comment or the option set on the parser.

PRISM_EXPORTED_FUNCTION const pm_line_offset_list_t *	pm_parser_line_offsets (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the line offsets that are associated with the given parser.

PRISM_EXPORTED_FUNCTION const pm_location_t *	pm_parser_data_loc (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the location of the DATA section that is associated with the given parser.

PRISM_EXPORTED_FUNCTION bool	pm_parser_continuable (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns whether the given parser is continuable, meaning that it could become valid if more input were appended, as opposed to being definitively invalid.

PRISM_EXPORTED_FUNCTION int	pm_parser_lex_state (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the lex state of the parser.

PRISM_EXPORTED_FUNCTION size_t	pm_parser_comments_size (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the number of comments associated with the given parser.

PRISM_EXPORTED_FUNCTION void	pm_parser_comments_each (const pm_parser_t parser, pm_comment_callback_t callback, void data) PRISM_NONNULL(1)
	Iterates over the comments associated with the given parser and calls the given callback for each comment.

PRISM_EXPORTED_FUNCTION size_t	pm_parser_magic_comments_size (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the number of magic comments associated with the given parser.

PRISM_EXPORTED_FUNCTION void	pm_parser_magic_comments_each (const pm_parser_t parser, pm_magic_comment_callback_t callback, void data) PRISM_NONNULL(1)
	Iterates over the magic comments associated with the given parser and calls the given callback for each magic comment.

PRISM_EXPORTED_FUNCTION size_t	pm_parser_errors_size (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the number of errors associated with the given parser.

PRISM_EXPORTED_FUNCTION size_t	pm_parser_warnings_size (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the number of warnings associated with the given parser.

PRISM_EXPORTED_FUNCTION void	pm_parser_errors_each (const pm_parser_t parser, pm_diagnostic_callback_t callback, void data) PRISM_NONNULL(1)
	Iterates over the errors associated with the given parser and calls the given callback for each error.

PRISM_EXPORTED_FUNCTION void	pm_parser_warnings_each (const pm_parser_t parser, pm_diagnostic_callback_t callback, void data) PRISM_NONNULL(1)
	Iterates over the warnings associated with the given parser and calls the given callback for each warning.

PRISM_EXPORTED_FUNCTION size_t	pm_parser_constants_size (const pm_parser_t *parser) PRISM_NONNULL(1)
	Returns the number of constants in the constant pool associated with the given parser.

PRISM_EXPORTED_FUNCTION void	pm_parser_constants_each (const pm_parser_t parser, pm_constant_callback_t callback, void data) PRISM_NONNULL(1)
	Iterates over the constants in the constant pool associated with the given parser and calls the given callback for each constant.

PRISM_EXPORTED_FUNCTION const pm_constant_t *	pm_parser_constant (const pm_parser_t *parser, pm_constant_id_t constant_id) PRISM_NONNULL(1)
	Returns a pointer to the constant at the given id in the constant pool associated with the given parser.

PRISM_EXPORTED_FUNCTION pm_node_t *	pm_parse (pm_parser_t *parser) PRISM_NONNULL(1)
	Initiate the parser with the given parser.

Detailed Description

The parser used to parse Ruby source.

Typedef Documentation

◆ pm_lex_callback_t

typedef void(* pm_lex_callback_t) (pm_parser_t *parser, pm_token_t *token, void *data)

This is the callback that is called when a token is lexed.

It is passed the opaque data pointer, the parser, and the token that was lexed.

Function Documentation

◆ pm_parser_new()

PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_parser_t * pm_parser_new	(	pm_arena_t *	arena,
		const uint8_t *	source,
		size_t	size,
		const pm_options_t *	options
	)

Allocate and initialize a parser with the given start and end pointers.

Parameters

arena	The arena to use for all AST-lifetime allocations. It is caller- owned and must outlive the parser.
source	The source to parse.
size	The size of the source.
options	The optional options to use when parsing. These options must live for the whole lifetime of this parser.

Returns: The initialized parser. It is the responsibility of the caller to free the parser with pm_parser_free().

◆ pm_parser_free()

PRISM_EXPORTED_FUNCTION void pm_parser_free ( pm_parser_t * parser )

Free both the memory held by the given parser and the parser itself.

Parameters

parser The parser to free.

◆ pm_parser_encoding_changed_callback_set()

PRISM_EXPORTED_FUNCTION void pm_parser_encoding_changed_callback_set	(	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

parser	The parser to register the callback with.
callback	The callback to register.

◆ pm_parser_lex_callback_set()

PRISM_EXPORTED_FUNCTION void pm_parser_lex_callback_set	(	pm_parser_t *	parser,
		pm_lex_callback_t	callback,
		void *	data
	)

Register a callback that will be called whenever a token is lexed.

Parameters

parser	The parser to register the callback with.
data	The opaque data to pass to the callback when it is called.
callback	The callback to register.

◆ pm_parser_lex_callback_data()

PRISM_EXPORTED_FUNCTION void * pm_parser_lex_callback_data ( const pm_parser_t * parser )

Returns the opaque data that is passed to the lex callback when it is called.

Parameters

parser The parser whose lex callback data we want to get.

Returns: The opaque data that is passed to the lex callback when it is called.

◆ pm_parser_start()

PRISM_EXPORTED_FUNCTION const uint8_t * pm_parser_start ( const pm_parser_t * parser )

Returns the raw pointer to the start of the source that is being parsed.

Parameters

parser the parser whose start pointer we want to get

Returns: the raw pointer to the start of the source that is being parsed

◆ pm_parser_end()

PRISM_EXPORTED_FUNCTION const uint8_t * pm_parser_end ( const pm_parser_t * parser )

Returns the raw pointer to the end of the source that is being parsed.

Parameters

parser the parser whose end pointer we want to get

Returns: the raw pointer to the end of the source that is being parsed

◆ pm_parser_start_line()

PRISM_EXPORTED_FUNCTION int32_t pm_parser_start_line ( const pm_parser_t * parser )

Returns the line that the parser was considered to have started on.

Parameters

parser the parser whose start line we want to get

Returns: the line that the parser was considered to have started on

◆ pm_parser_encoding_name()

PRISM_EXPORTED_FUNCTION const char * pm_parser_encoding_name ( const pm_parser_t * parser )

Returns the name of the encoding that is being used to parse the source.

Parameters

parser the parser whose encoding name we want to get

Returns: the name of the encoding that is being used to parse the source

◆ pm_parser_encoding_char_width()

PRISM_EXPORTED_FUNCTION size_t pm_parser_encoding_char_width	(	const pm_parser_t *	parser,
		const uint8_t *	start,
		ptrdiff_t	remaining
	)

Returns the width of the character at the given pointer in the encoding that is being used to parse the source.

Parameters

parser	the parser whose encoding we want to use
start	a pointer to the start of the character
remaining	the number of bytes remaining in the source

Returns: the width of the character in bytes

◆ pm_parser_encoding_us_ascii()

PRISM_EXPORTED_FUNCTION size_t PRISM_EXPORTED_FUNCTION bool pm_parser_encoding_us_ascii ( const pm_parser_t * parser )

Returns whether or not the parser is using the US-ASCII encoding.

Parameters

parser the parser to check

Returns: true if the parser is using US-ASCII encoding, false otherwise

◆ pm_parser_filepath()

PRISM_EXPORTED_FUNCTION const pm_string_t * pm_parser_filepath ( const pm_parser_t * parser )

Returns the filepath that is being used to parse the source.

Parameters

parser the parser whose filepath we want to get

Returns: a pointer to the filepath string

◆ pm_parser_constant_find()

PRISM_EXPORTED_FUNCTION pm_constant_id_t pm_parser_constant_find	(	const pm_parser_t *	parser,
		const uint8_t *	start,
		size_t	length
	)

Find a constant in the parser's constant pool.

Returns the id of the constant, or 0 if the constant is not found.

Parameters

parser	the parser whose constant pool we want to search
start	a pointer to the start of the string to search for
length	the length of the string to search for

Returns: the id of the constant, or 0 if the constant is not found

◆ pm_parser_frozen_string_literal()

PRISM_EXPORTED_FUNCTION pm_constant_id_t PRISM_EXPORTED_FUNCTION int8_t pm_parser_frozen_string_literal ( const pm_parser_t * parser )

Returns the frozen string literal value of the parser, as determined by the frozen_string_literal magic comment or the option set on the parser.

Parameters

parser the parser whose frozen string literal value we want to get

Returns: -1 if disabled, 0 if unset, 1 if enabled

◆ pm_parser_line_offsets()

PRISM_EXPORTED_FUNCTION const pm_line_offset_list_t * pm_parser_line_offsets ( const pm_parser_t * parser )

Returns the line offsets that are associated with the given parser.

Parameters

parser the parser whose line offsets we want to get

Returns: the line offsets that are associated with the given parser

◆ pm_parser_data_loc()

PRISM_EXPORTED_FUNCTION const pm_location_t * pm_parser_data_loc ( const pm_parser_t * parser )

Returns the location of the DATA section that is associated with the given parser.

Parameters

parser the parser whose data location we want to get

Returns: the location of the DATA section that is associated with the given parser. If it is unset, then the length will be set to 0.

◆ pm_parser_continuable()

PRISM_EXPORTED_FUNCTION bool pm_parser_continuable ( const pm_parser_t * parser )

Returns whether the given parser is continuable, meaning that it could become valid if more input were appended, as opposed to being definitively invalid.

Parameters

parser the parser whose continuable status we want to get

Returns: whether the given parser is continuable

◆ pm_parser_lex_state()

PRISM_EXPORTED_FUNCTION int pm_parser_lex_state ( const pm_parser_t * parser )

Returns the lex state of the parser.

Note that this is an internal detail, and we are purposefully not returning an instance of the internal enum that we use to track this. This is only exposed because we need it for some very niche use cases. Most consumers should avoid this function.

Parameters

parser the parser whose lex state we want to get

Returns: the lex state of the parser

◆ pm_parser_comments_size()

PRISM_EXPORTED_FUNCTION size_t pm_parser_comments_size ( const pm_parser_t * parser )

Returns the number of comments associated with the given parser.

Parameters

parser the parser whose comments we want to get the size of

Returns: the number of comments associated with the given parser

◆ pm_parser_comments_each()

PRISM_EXPORTED_FUNCTION void pm_parser_comments_each	(	const pm_parser_t *	parser,
		pm_comment_callback_t	callback,
		void *	data
	)

Iterates over the comments associated with the given parser and calls the given callback for each comment.

Parameters

parser	the parser whose comments we want to iterate over
callback	the callback function to call for each comment. This function will be passed a pointer to the comment and the data parameter passed to this function.
data	the data to pass to the callback function for each comment. This can be NULL if no data needs to be passed to the callback function.

◆ pm_parser_magic_comments_size()

PRISM_EXPORTED_FUNCTION size_t pm_parser_magic_comments_size ( const pm_parser_t * parser )

Returns the number of magic comments associated with the given parser.

Parameters

parser the parser whose magic comments we want to get the size of

Returns: the number of magic comments associated with the given parser

◆ pm_parser_magic_comments_each()

PRISM_EXPORTED_FUNCTION void pm_parser_magic_comments_each	(	const pm_parser_t *	parser,
		pm_magic_comment_callback_t	callback,
		void *	data
	)

Iterates over the magic comments associated with the given parser and calls the given callback for each magic comment.

Parameters

parser	the parser whose magic comments we want to iterate over
callback	the callback function to call for each magic comment. This function will be passed a pointer to the magic comment and the data parameter passed to this function.
data	the data to pass to the callback function for each magic comment. This can be NULL if no data needs to be passed to the callback function.

◆ pm_parser_errors_size()

PRISM_EXPORTED_FUNCTION size_t pm_parser_errors_size ( const pm_parser_t * parser )

Returns the number of errors associated with the given parser.

Parameters

parser the parser whose errors we want to get the size of

Returns: the number of errors associated with the given parser

◆ pm_parser_warnings_size()

PRISM_EXPORTED_FUNCTION size_t pm_parser_warnings_size ( const pm_parser_t * parser )

Returns the number of warnings associated with the given parser.

Parameters

parser the parser whose warnings we want to get the size of

Returns: the number of warnings associated with the given parser

◆ pm_parser_errors_each()

PRISM_EXPORTED_FUNCTION void pm_parser_errors_each	(	const pm_parser_t *	parser,
		pm_diagnostic_callback_t	callback,
		void *	data
	)

Iterates over the errors associated with the given parser and calls the given callback for each error.

Parameters

parser	the parser whose errors we want to iterate over
callback	the callback function to call for each error. This function will be passed a pointer to the error and the data parameter passed to this function.
data	the data to pass to the callback function for each error. This can be NULL if no data needs to be passed to the callback function.

◆ pm_parser_warnings_each()

PRISM_EXPORTED_FUNCTION void pm_parser_warnings_each	(	const pm_parser_t *	parser,
		pm_diagnostic_callback_t	callback,
		void *	data
	)

Iterates over the warnings associated with the given parser and calls the given callback for each warning.

Parameters

parser	the parser whose warnings we want to iterate over
callback	the callback function to call for each warning. This function will be passed a pointer to the warning and the data parameter passed to this function.
data	the data to pass to the callback function for each warning. This can be NULL if no data needs to be passed to the callback function.

◆ pm_parser_constants_size()

PRISM_EXPORTED_FUNCTION size_t pm_parser_constants_size ( const pm_parser_t * parser )

Returns the number of constants in the constant pool associated with the given parser.

Parameters

parser the parser whose constant pool constants we want to get the size of

Returns: the number of constants in the constant pool associated with the given parser

◆ pm_parser_constants_each()

PRISM_EXPORTED_FUNCTION void pm_parser_constants_each	(	const pm_parser_t *	parser,
		pm_constant_callback_t	callback,
		void *	data
	)

Iterates over the constants in the constant pool associated with the given parser and calls the given callback for each constant.

Parameters

parser	the parser whose constants we want to iterate over
callback	the callback function to call for each constant. This function will be passed a pointer to the constant and the data parameter passed to this function.
data	the data to pass to the callback function for each constant. This can be NULL if no data needs to be passed to the callback function.

◆ pm_parser_constant()

PRISM_EXPORTED_FUNCTION const pm_constant_t * pm_parser_constant	(	const pm_parser_t *	parser,
		pm_constant_id_t	constant_id
	)

Returns a pointer to the constant at the given id in the constant pool associated with the given parser.

Parameters

parser	the parser whose constant pool we want to look up from
constant_id	the id of the constant to look up (1-based)

Returns: a pointer to the constant at the given id

◆ pm_parse()

PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse ( pm_parser_t * parser )

Initiate the parser with the given parser.

Parameters

parser The parser to use.

Returns: The AST representing the source.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ pm_lex_callback_t

Function Documentation

◆ pm_parser_new()

◆ pm_parser_free()

◆ pm_parser_encoding_changed_callback_set()

◆ pm_parser_lex_callback_set()

◆ pm_parser_lex_callback_data()

◆ pm_parser_start()

◆ pm_parser_end()

◆ pm_parser_start_line()

◆ pm_parser_encoding_name()

◆ pm_parser_encoding_char_width()

◆ pm_parser_encoding_us_ascii()

◆ pm_parser_filepath()

◆ pm_parser_constant_find()

◆ pm_parser_frozen_string_literal()

◆ pm_parser_line_offsets()

◆ pm_parser_data_loc()

◆ pm_parser_continuable()

◆ pm_parser_lex_state()

◆ pm_parser_comments_size()

◆ pm_parser_comments_each()

◆ pm_parser_magic_comments_size()

◆ pm_parser_magic_comments_each()

◆ pm_parser_errors_size()

◆ pm_parser_warnings_size()

◆ pm_parser_errors_each()

◆ pm_parser_warnings_each()

◆ pm_parser_constants_size()

◆ pm_parser_constants_each()

◆ pm_parser_constant()

◆ pm_parse()