The options that can be passed to parsing. More...

#include "prism/defines.h"
#include "prism/util/pm_char.h"
#include "prism/util/pm_string.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for options.h:

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

Go to the source code of this file.

Data Structures
struct	pm_options_scope
	A scope of locals surrounding the code that is being parsed. More...

struct	pm_options
	The options that can be passed to the parser. More...

Macros
#define	PM_OPTIONS_FROZEN_STRING_LITERAL_DISABLED ((int8_t) -1)
	String literals should be made frozen.

#define	PM_OPTIONS_FROZEN_STRING_LITERAL_UNSET ((int8_t) 0)
	String literals may be frozen or mutable depending on the implementation default.

#define	PM_OPTIONS_FROZEN_STRING_LITERAL_ENABLED ((int8_t) 1)
	String literals should be made mutable.

Typedefs
typedef struct pm_options_scope	pm_options_scope_t
	A scope of locals surrounding the code that is being parsed.

typedef void(*	pm_options_shebang_callback_t) (struct pm_options options, const uint8_t source, size_t length, void *shebang_callback_data)
	The callback called when additional switches are found in a shebang comment that need to be processed by the runtime.

typedef struct pm_options	pm_options_t
	The options that can be passed to the parser.

Enumerations
enum	pm_options_version_t { PM_OPTIONS_VERSION_UNSET = 0 , PM_OPTIONS_VERSION_CRUBY_3_3 = 1 , PM_OPTIONS_VERSION_CRUBY_3_4 = 2 , PM_OPTIONS_VERSION_CRUBY_3_5 = 3 , PM_OPTIONS_VERSION_LATEST = PM_OPTIONS_VERSION_CRUBY_3_5 }
	The version of Ruby syntax that we should be parsing with. More...

Functions
void	pm_options_read (pm_options_t options, const char data)
	Deserialize an options struct from the given binary string.

Detailed Description

The options that can be passed to parsing.

Typedef Documentation

◆ pm_options_shebang_callback_t

typedef void(* pm_options_shebang_callback_t) (struct pm_options *options, const uint8_t *source, size_t length, void *shebang_callback_data)

The callback called when additional switches are found in a shebang comment that need to be processed by the runtime.

Parameters

options	The options struct that may be updated by this callback. Certain fields will be checked for changes, specifically encoding, command_line, and frozen_string_literal.
source	The source of the shebang comment.
length	The length of the source.
shebang_callback_data	Any additional data that should be passed along to the callback.

Enumeration Type Documentation

◆ pm_options_version_t

enum pm_options_version_t

The version of Ruby syntax that we should be parsing with.

This is used to allow consumers to specify which behavior they want in case they need to parse in the same way as a specific version of CRuby would have.

Enumerator
PM_OPTIONS_VERSION_UNSET	If an explicit version is not provided, the current version of prism will be used.
PM_OPTIONS_VERSION_CRUBY_3_3	The vendored version of prism in CRuby 3.3.x.
PM_OPTIONS_VERSION_CRUBY_3_4	The vendored version of prism in CRuby 3.4.x.
PM_OPTIONS_VERSION_CRUBY_3_5	The vendored version of prism in CRuby 3.5.x.
PM_OPTIONS_VERSION_LATEST	The current version of prism.

Function Documentation

◆ pm_options_read()

void pm_options_read	(	pm_options_t *	options,
		const char *	data
	)

Deserialize an options struct from the given binary string.

This is used to pass options to the parser from an FFI call so that consumers of the library from an FFI perspective don't have to worry about the structure of our options structs. Since the source of these calls will be from Ruby implementation internals we assume it is from a trusted source.

data is assumed to be a valid pointer pointing to well-formed data. The layout of this data should be the same every time, and is described below:

# bytes	field
`4`	the length of the filepath
...	the filepath bytes
`4`	the line number
`4`	the length the encoding
...	the encoding bytes
`1`	frozen string literal
`1`	-p command line option
`1`	-n command line option
`1`	-l command line option
`1`	-a command line option
`1`	the version
`1`	encoding locked
`1`	main script
`1`	partial script
`1`	freeze
`4`	the number of scopes
...	the scopes

The version field is an enum, so it should be one of the following values:

value	version
`0`	use the latest version of prism
`1`	use the version of prism that is vendored in CRuby 3.3.0

Each scope is laid out as follows:

# bytes	field
`4`	the number of locals
`1`	the forwarding flags
...	the locals

Each local is laid out as follows:

# bytes	field
`4`	the length of the local
...	the local bytes

Some additional things to note about this layout:

The filepath can have a length of 0, in which case we'll consider it an empty string.
The line number should be 0-indexed.
The encoding can have a length of 0, in which case we'll use the default encoding (UTF-8). If it's not 0, it should correspond to a name of an encoding that can be passed to Encoding.find in Ruby.
The frozen string literal, encoding locked, main script, and partial script fields are booleans, so their values should be either 0 or 1.
The number of scopes can be 0.

Parameters

options	The options struct to deserialize into.
data	The binary string to deserialize from.

This is used to pass options to the parser from an FFI call so that consumers of the library from an FFI perspective don't have to worry about the structure of our options structs. Since the source of these calls will be from Ruby implementation internals we assume it is from a trusted source.

Data Structures

Macros

Typedefs

Enumerations