Ruby  3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
options.h File Reference

(348a53415339076afc4a02fcd09f3ae36e9c4c61)

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. More...
 
#define PM_OPTIONS_FROZEN_STRING_LITERAL_UNSET   ((int8_t) 0)
 String literals may be frozen or mutable depending on the implementation default. More...
 
#define PM_OPTIONS_FROZEN_STRING_LITERAL_ENABLED   ((int8_t) 1)
 String literals should be made mutable. More...
 

Typedefs

typedef struct pm_options_scope pm_options_scope_t
 A scope of locals surrounding the code that is being parsed. More...
 
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. More...
 
typedef struct pm_options pm_options_t
 The options that can be passed to the parser. More...
 

Enumerations

enum  pm_options_version_t { PM_OPTIONS_VERSION_LATEST = 0 , PM_OPTIONS_VERSION_CRUBY_3_3 = 1 }
 The version of Ruby syntax that we should be parsing with. More...
 

Functions

PRISM_EXPORTED_FUNCTION void pm_options_shebang_callback_set (pm_options_t *options, pm_options_shebang_callback_t shebang_callback, void *shebang_callback_data)
 Set the shebang callback option on the given options struct. More...
 
PRISM_EXPORTED_FUNCTION void pm_options_filepath_set (pm_options_t *options, const char *filepath)
 Set the filepath option on the given options struct. More...
 
PRISM_EXPORTED_FUNCTION void pm_options_line_set (pm_options_t *options, int32_t line)
 Set the line option on the given options struct. More...
 
PRISM_EXPORTED_FUNCTION void pm_options_encoding_set (pm_options_t *options, const char *encoding)
 Set the encoding option on the given options struct. More...
 
PRISM_EXPORTED_FUNCTION void pm_options_encoding_locked_set (pm_options_t *options, bool encoding_locked)
 Set the encoding_locked option on the given options struct. More...
 
PRISM_EXPORTED_FUNCTION void pm_options_frozen_string_literal_set (pm_options_t *options, bool frozen_string_literal)
 Set the frozen string literal option on the given options struct. More...
 
PRISM_EXPORTED_FUNCTION void pm_options_command_line_set (pm_options_t *options, uint8_t command_line)
 Sets the command line option on the given options struct. More...
 
PRISM_EXPORTED_FUNCTION bool pm_options_version_set (pm_options_t *options, const char *version, size_t length)
 Set the version option on the given options struct by parsing the given string. More...
 
PRISM_EXPORTED_FUNCTION void pm_options_main_script_set (pm_options_t *options, bool main_script)
 Set the main script option on the given options struct. More...
 
PRISM_EXPORTED_FUNCTION void pm_options_partial_script_set (pm_options_t *options, bool partial_script)
 Set the partial script option on the given options struct. More...
 
PRISM_EXPORTED_FUNCTION bool pm_options_scopes_init (pm_options_t *options, size_t scopes_count)
 Allocate and zero out the scopes array on the given options struct. More...
 
PRISM_EXPORTED_FUNCTION const pm_options_scope_tpm_options_scope_get (const pm_options_t *options, size_t index)
 Return a pointer to the scope at the given index within the given options. More...
 
PRISM_EXPORTED_FUNCTION bool pm_options_scope_init (pm_options_scope_t *scope, size_t locals_count)
 Create a new options scope struct. More...
 
PRISM_EXPORTED_FUNCTION const pm_string_tpm_options_scope_local_get (const pm_options_scope_t *scope, size_t index)
 Return a pointer to the local at the given index within the given scope. More...
 
PRISM_EXPORTED_FUNCTION void pm_options_free (pm_options_t *options)
 Free the internal memory associated with the options. More...
 
void pm_options_read (pm_options_t *options, const char *data)
 Deserialize an options struct from the given binary string. More...
 

Variables

static const uint8_t PM_OPTIONS_COMMAND_LINE_A = 0x1
 A bit representing whether or not the command line -a option was set. More...
 
static const uint8_t PM_OPTIONS_COMMAND_LINE_E = 0x2
 A bit representing whether or not the command line -e option was set. More...
 
static const uint8_t PM_OPTIONS_COMMAND_LINE_L = 0x4
 A bit representing whether or not the command line -l option was set. More...
 
static const uint8_t PM_OPTIONS_COMMAND_LINE_N = 0x8
 A bit representing whether or not the command line -n option was set. More...
 
static const uint8_t PM_OPTIONS_COMMAND_LINE_P = 0x10
 A bit representing whether or not the command line -p option was set. More...
 
static const uint8_t PM_OPTIONS_COMMAND_LINE_X = 0x20
 A bit representing whether or not the command line -x option was set. More...
 

Detailed Description

The options that can be passed to parsing.

Definition in file options.h.

Macro Definition Documentation

◆ PM_OPTIONS_FROZEN_STRING_LITERAL_DISABLED

#define PM_OPTIONS_FROZEN_STRING_LITERAL_DISABLED   ((int8_t) -1)

String literals should be made frozen.

Definition at line 20 of file options.h.

◆ PM_OPTIONS_FROZEN_STRING_LITERAL_ENABLED

#define PM_OPTIONS_FROZEN_STRING_LITERAL_ENABLED   ((int8_t) 1)

String literals should be made mutable.

Definition at line 31 of file options.h.

◆ PM_OPTIONS_FROZEN_STRING_LITERAL_UNSET

#define PM_OPTIONS_FROZEN_STRING_LITERAL_UNSET   ((int8_t) 0)

String literals may be frozen or mutable depending on the implementation default.

Definition at line 26 of file options.h.

Typedef Documentation

◆ pm_options_scope_t

A scope of locals surrounding the code that is being parsed.

◆ 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
optionsThe options struct that may be updated by this callback. Certain fields will be checked for changes, specifically encoding, command_line, and frozen_string_literal.
sourceThe source of the shebang comment.
lengthThe length of the source.
shebang_callback_dataAny additional data that should be passed along to the callback.

Definition at line 59 of file options.h.

◆ pm_options_t

typedef struct pm_options pm_options_t

The options that can be passed to the parser.

Enumeration Type Documentation

◆ 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_LATEST 

The current version of prism.

PM_OPTIONS_VERSION_CRUBY_3_3 

The vendored version of prism in CRuby 3.3.x.

Definition at line 66 of file options.h.

Function Documentation

◆ pm_options_command_line_set()

PRISM_EXPORTED_FUNCTION void pm_options_command_line_set ( pm_options_t options,
uint8_t  command_line 
)

Sets the command line option on the given options struct.

Parameters
optionsThe options struct to set the command line option on.
command_lineThe command_line value to set.

Definition at line 56 of file options.c.

◆ pm_options_encoding_locked_set()

PRISM_EXPORTED_FUNCTION void pm_options_encoding_locked_set ( pm_options_t options,
bool  encoding_locked 
)

Set the encoding_locked option on the given options struct.

Parameters
optionsThe options struct to set the encoding_locked value on.
encoding_lockedThe encoding_locked value to set.

Definition at line 32 of file options.c.

◆ pm_options_encoding_set()

PRISM_EXPORTED_FUNCTION void pm_options_encoding_set ( pm_options_t options,
const char *  encoding 
)

Set the encoding option on the given options struct.

Parameters
optionsThe options struct to set the encoding on.
encodingThe encoding to set.

Definition at line 24 of file options.c.

◆ pm_options_filepath_set()

PRISM_EXPORTED_FUNCTION void pm_options_filepath_set ( pm_options_t options,
const char *  filepath 
)

Set the filepath option on the given options struct.

Parameters
optionsThe options struct to set the filepath on.
filepathThe filepath to set.

Definition at line 16 of file options.c.

◆ pm_options_free()

PRISM_EXPORTED_FUNCTION void pm_options_free ( pm_options_t options)

Free the internal memory associated with the options.

Parameters
optionsThe options struct whose internal memory should be freed.

Definition at line 181 of file options.c.

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

◆ pm_options_frozen_string_literal_set()

PRISM_EXPORTED_FUNCTION void pm_options_frozen_string_literal_set ( pm_options_t options,
bool  frozen_string_literal 
)

Set the frozen string literal option on the given options struct.

Parameters
optionsThe options struct to set the frozen string literal value on.
frozen_string_literalThe frozen string literal value to set.

Definition at line 48 of file options.c.

◆ pm_options_line_set()

PRISM_EXPORTED_FUNCTION void pm_options_line_set ( pm_options_t options,
int32_t  line 
)

Set the line option on the given options struct.

Parameters
optionsThe options struct to set the line on.
lineThe line to set.

Definition at line 40 of file options.c.

◆ pm_options_main_script_set()

PRISM_EXPORTED_FUNCTION void pm_options_main_script_set ( pm_options_t options,
bool  main_script 
)

Set the main script option on the given options struct.

Parameters
optionsThe options struct to set the main script value on.
main_scriptThe main script value to set.

Definition at line 120 of file options.c.

◆ pm_options_partial_script_set()

PRISM_EXPORTED_FUNCTION void pm_options_partial_script_set ( pm_options_t options,
bool  partial_script 
)

Set the partial script option on the given options struct.

Parameters
optionsThe options struct to set the partial script value on.
partial_scriptThe partial script value to set.

Definition at line 128 of file options.c.

◆ 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
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
... 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
optionsThe options struct to deserialize into.
dataThe 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.

Definition at line 238 of file options.c.

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

◆ pm_options_scope_get()

PRISM_EXPORTED_FUNCTION const pm_options_scope_t* pm_options_scope_get ( const pm_options_t options,
size_t  index 
)

Return a pointer to the scope at the given index within the given options.

Parameters
optionsThe options struct to get the scope from.
indexThe index of the scope to get.
Returns
A pointer to the scope at the given index.

Definition at line 154 of file options.c.

◆ pm_options_scope_init()

PRISM_EXPORTED_FUNCTION bool pm_options_scope_init ( pm_options_scope_t scope,
size_t  locals_count 
)

Create a new options scope struct.

This will hold a set of locals that are in scope surrounding the code that is being parsed.

Parameters
scopeThe scope struct to initialize.
locals_countThe number of locals to allocate.
Returns
Whether or not the scope was initialized successfully.

This will hold a set of locals that are in scope surrounding the code that is being parsed.

Definition at line 163 of file options.c.

Referenced by pm_options_read().

◆ pm_options_scope_local_get()

PRISM_EXPORTED_FUNCTION const pm_string_t* pm_options_scope_local_get ( const pm_options_scope_t scope,
size_t  index 
)

Return a pointer to the local at the given index within the given scope.

Parameters
scopeThe scope struct to get the local from.
indexThe index of the local to get.
Returns
A pointer to the local at the given index.

Definition at line 173 of file options.c.

◆ pm_options_scopes_init()

PRISM_EXPORTED_FUNCTION bool pm_options_scopes_init ( pm_options_t options,
size_t  scopes_count 
)

Allocate and zero out the scopes array on the given options struct.

Parameters
optionsThe options struct to initialize the scopes array on.
scopes_countThe number of scopes to allocate.
Returns
Whether or not the scopes array was initialized successfully.

Definition at line 144 of file options.c.

Referenced by pm_options_read().

◆ pm_options_shebang_callback_set()

PRISM_EXPORTED_FUNCTION void pm_options_shebang_callback_set ( pm_options_t options,
pm_options_shebang_callback_t  shebang_callback,
void *  shebang_callback_data 
)

Set the shebang callback option on the given options struct.

Parameters
optionsThe options struct to set the shebang callback on.
shebang_callbackThe shebang callback to set.
shebang_callback_dataAny additional data that should be passed along to the callback.

Definition at line 7 of file options.c.

◆ pm_options_version_set()

PRISM_EXPORTED_FUNCTION bool pm_options_version_set ( pm_options_t options,
const char *  version,
size_t  length 
)

Set the version option on the given options struct by parsing the given string.

If the string contains an invalid option, this returns false. Otherwise, it returns true.

Parameters
optionsThe options struct to set the version on.
versionThe version to set.
lengthThe length of the version string.
Returns
Whether or not the version was parsed successfully.

If the string contains an invalid option, this returns false. Otherwise, it returns true.

Definition at line 74 of file options.c.

Variable Documentation

◆ PM_OPTIONS_COMMAND_LINE_A

const uint8_t PM_OPTIONS_COMMAND_LINE_A = 0x1
static

A bit representing whether or not the command line -a option was set.

-a splits the input line $_ into $F.

Definition at line 166 of file options.h.

◆ PM_OPTIONS_COMMAND_LINE_E

const uint8_t PM_OPTIONS_COMMAND_LINE_E = 0x2
static

A bit representing whether or not the command line -e option was set.

-e allow the user to specify a script to be executed. This is necessary for prism to know because certain warnings are not generated when -e is used.

Definition at line 173 of file options.h.

◆ PM_OPTIONS_COMMAND_LINE_L

const uint8_t PM_OPTIONS_COMMAND_LINE_L = 0x4
static

A bit representing whether or not the command line -l option was set.

-l chomps the input line by default.

Definition at line 179 of file options.h.

◆ PM_OPTIONS_COMMAND_LINE_N

const uint8_t PM_OPTIONS_COMMAND_LINE_N = 0x8
static

A bit representing whether or not the command line -n option was set.

-n wraps the script in a while gets loop.

Definition at line 185 of file options.h.

◆ PM_OPTIONS_COMMAND_LINE_P

const uint8_t PM_OPTIONS_COMMAND_LINE_P = 0x10
static

A bit representing whether or not the command line -p option was set.

-p prints the value of $_ at the end of each loop.

Definition at line 191 of file options.h.

◆ PM_OPTIONS_COMMAND_LINE_X

const uint8_t PM_OPTIONS_COMMAND_LINE_X = 0x20
static

A bit representing whether or not the command line -x option was set.

-x searches the input file for a shebang that matches the current Ruby engine.

Definition at line 197 of file options.h.