Ruby: pm_options Struct Reference

Ruby 3.4.6p54 (2025-09-16 revision dbd83256b1cec76c69756ecb8758b9e1079833de)

Public Member Functions | Data Fields
pm_options Struct Reference

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

`#include <options.h>`

## Public Member 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.
PRISM_EXPORTED_FUNCTION void | pm_options_filepath_set (pm_options_t *options, const char *filepath)
| Set the filepath option on the given options struct.
PRISM_EXPORTED_FUNCTION void | pm_options_line_set (pm_options_t *options, int32_t line)
| Set the line option on the given options struct.
PRISM_EXPORTED_FUNCTION void | pm_options_encoding_set (pm_options_t *options, const char *encoding)
| Set the encoding option on the given options struct.
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.
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.
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.
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.
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.
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.
PRISM_EXPORTED_FUNCTION void | pm_options_freeze_set (pm_options_t *options, bool freeze)
| Set the freeze option on the given options struct.
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.
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.
PRISM_EXPORTED_FUNCTION bool | pm_options_scope_init (pm_options_scope_t *scope, size_t locals_count)
| Create a new options scope struct.
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.
PRISM_EXPORTED_FUNCTION void | pm_options_scope_forwarding_set (pm_options_scope_t *scope, uint8_t forwarding)
| Set the forwarding option on the given scope struct.
PRISM_EXPORTED_FUNCTION void | pm_options_free (pm_options_t *options)
| Free the internal memory associated with the options.

## Data Fields
pm_options_shebang_callback_t | shebang_callback
| The callback to call when additional switches are found in a shebang comment.
void * | shebang_callback_data
| Any additional data that should be passed along to the shebang callback if one was set.
pm_string_t | filepath
| The name of the file that is currently being parsed.
int32_t | line
| The line within the file that the parse starts on.
pm_string_t | encoding
| The name of the encoding that the source file is in.
size_t | scopes_count
| The number of scopes surrounding the code that is being parsed.
pm_options_scope_t * | scopes
| The scopes surrounding the code that is being parsed.
pm_options_version_t | version
| The version of prism that we should be parsing with.
uint8_t | command_line
| A bitset of the various options that were set on the command line.
int8_t | frozen_string_literal
| Whether or not the frozen string literal option has been set.
bool | encoding_locked
| Whether or not the encoding magic comments should be respected.
bool | main_script
| When the file being parsed is the main script, the shebang will be considered for command-line flags (or for implicit -x).
bool | partial_script
| When the file being parsed is considered a "partial" script, jumps will not be marked as errors if they are not contained within loops/blocks.
bool | freeze
| Whether or not the parser should freeze the nodes that it creates.

## Detailed Description

The options that can be passed to the parser.

Definition at line 104 of file options.h.

## Member 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

  options | The options struct to set the command line option on.
  command_line | The command_line value to set.

Definition at line 56 of file options.c.

Referenced by pm_options_command_line_set().

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

  options | The options struct to set the encoding_locked value on.
  encoding_locked | The encoding_locked value to set.

Definition at line 32 of file options.c.

Referenced by pm_options_encoding_locked_set().

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

  options | The options struct to set the encoding on.
  encoding | The encoding to set.

Definition at line 24 of file options.c.

Referenced by pm_options_encoding_set().

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

  options | The options struct to set the filepath on.
  filepath | The filepath to set.

Definition at line 16 of file options.c.

Referenced by pm_options_filepath_set().

## ◆ pm_options_free()

PRISM_EXPORTED_FUNCTION void pm_options_free | ( | pm_options_t * | options | ) |

Free the internal memory associated with the options.

Parameters

  options | The options struct whose internal memory should be freed.

Definition at line 208 of file options.c.

Referenced by pm_options_free().

## ◆ pm_options_freeze_set()

PRISM_EXPORTED_FUNCTION void pm_options_freeze_set | ( | pm_options_t * | options,
|  | bool | freeze )

Set the freeze option on the given options struct.

Parameters

  options | The options struct to set the freeze value on.
  freeze | The freeze value to set.

Definition at line 146 of file options.c.

Referenced by pm_options_freeze_set().

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

  options | The options struct to set the frozen string literal value on.
  frozen_string_literal | The frozen string literal value to set.

Definition at line 48 of file options.c.

Referenced by pm_options_frozen_string_literal_set().

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

  options | The options struct to set the line on.
  line | The line to set.

Definition at line 40 of file options.c.

Referenced by pm_options_line_set().

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

  options | The options struct to set the main script value on.
  main_script | The main script value to set.

Definition at line 130 of file options.c.

Referenced by pm_options_main_script_set().

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

  options | The options struct to set the partial script value on.
  partial_script | The partial script value to set.

Definition at line 138 of file options.c.

Referenced by pm_options_partial_script_set().

## ◆ pm_options_scope_forwarding_set()

PRISM_EXPORTED_FUNCTION void pm_options_scope_forwarding_set | ( | pm_options_scope_t * | scope,
|  | uint8_t | forwarding )

Set the forwarding option on the given scope struct.

Parameters

  scope | The scope struct to set the forwarding on.
  forwarding | The forwarding value to set.

Definition at line 200 of file options.c.

Referenced by pm_options_scope_forwarding_set().

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

  options | The options struct to get the scope from.
  index | The index of the scope to get.

Returns
  A pointer to the scope at the given index.

Definition at line 172 of file options.c.

Referenced by pm_options_scope_get().

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

  scope | The scope struct to initialize.
  locals_count | The number of locals to allocate.

Returns
  Whether or not the scope was initialized successfully.

Definition at line 181 of file options.c.

Referenced by pm_options_scope_init().

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

  scope | The scope struct to get the local from.
  index | The index of the local to get.

Returns
  A pointer to the local at the given index.

Definition at line 192 of file options.c.

Referenced by pm_options_scope_local_get().

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

  options | The options struct to initialize the scopes array on.
  scopes_count | The number of scopes to allocate.

Returns
  Whether or not the scopes array was initialized successfully.

Definition at line 162 of file options.c.

Referenced by pm_options_scopes_init().

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

  options | The options struct to set the shebang callback on.
  shebang_callback | The shebang callback to set.
  shebang_callback_data | Any additional data that should be passed along to the callback.

Definition at line 7 of file options.c.

Referenced by pm_options_shebang_callback_set().

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

  options | The options struct to set the version on.
  version | The version to set.
  length | The length of the version string.

Returns
  Whether or not the version was parsed successfully.

Definition at line 74 of file options.c.

Referenced by pm_options_version_set().

## Field Documentation

## ◆ command_line

uint8_t pm_options::command_line

A bitset of the various options that were set on the command line.

Definition at line 153 of file options.h.

Referenced by pm_options_command_line_set(), pm_options_read(), and pm_parser::pm_parser_init().

## ◆ encoding

pm_string_t pm_options::encoding

The name of the encoding that the source file is in.

Note that this must correspond to a name that can be found with Encoding.find in Ruby.

Definition at line 130 of file options.h.

Referenced by pm_options_encoding_set(), pm_options_free(), pm_options_read(), and pm_parser::pm_parser_init().

## ◆ encoding_locked

bool pm_options::encoding_locked

Whether or not the encoding magic comments should be respected.

This is a niche use-case where you want to parse a file with a specific encoding but ignore any encoding magic comments at the top of the file.

Definition at line 169 of file options.h.

Referenced by pm_options_encoding_locked_set(), pm_options_read(), and pm_parser::pm_parser_init().

## ◆ filepath

pm_string_t pm_options::filepath

The name of the file that is currently being parsed.

Definition at line 118 of file options.h.

Referenced by pm_options_filepath_set(), pm_options_free(), pm_options_read(), and pm_parser::pm_parser_init().

## ◆ freeze

bool pm_options::freeze

Whether or not the parser should freeze the nodes that it creates.

This makes it possible to have a deeply frozen AST that is safe to share between concurrency primitives.

Definition at line 193 of file options.h.

Referenced by pm_options_freeze_set(), and pm_options_read().

## ◆ frozen_string_literal

int8_t pm_options::frozen_string_literal

Whether or not the frozen string literal option has been set.

May be:

- PM_OPTIONS_FROZEN_STRING_LITERAL_DISABLED
- PM_OPTIONS_FROZEN_STRING_LITERAL_ENABLED
- PM_OPTIONS_FROZEN_STRING_LITERAL_UNSET

Definition at line 162 of file options.h.

Referenced by pm_options_frozen_string_literal_set(), pm_options_read(), and pm_parser::pm_parser_init().

## ◆ line

int32_t pm_options::line

The line within the file that the parse starts on.

This value is 1-indexed.

Definition at line 124 of file options.h.

Referenced by pm_options_line_set(), pm_options_read(), and pm_parser::pm_parser_init().

## ◆ main_script

bool pm_options::main_script

When the file being parsed is the main script, the shebang will be considered for command-line flags (or for implicit -x).

The caller needs to pass this information to the parser so that it can behave correctly.

Definition at line 176 of file options.h.

Referenced by pm_options_main_script_set(), pm_options_read(), and pm_parser::pm_parser_init().

## ◆ partial_script

bool pm_options::partial_script

When the file being parsed is considered a "partial" script, jumps will not be marked as errors if they are not contained within loops/blocks.

This is used in the case that you're parsing a script that you know will be embedded inside another script later, but you do not have that context yet. For example, when parsing an ERB template that will be evaluated inside another script.

Definition at line 186 of file options.h.

Referenced by pm_options_partial_script_set(), pm_options_read(), and pm_parser::pm_parser_init().

## ◆ scopes

pm_options_scope_t* pm_options::scopes

The scopes surrounding the code that is being parsed.

For most parses this will be NULL, but for evals it will be the locals that are in scope surrounding the eval. Scopes are ordered from the outermost scope to the innermost one.

Definition at line 143 of file options.h.

Referenced by pm_options_free(), pm_options_read(), pm_options_scope_get(), and pm_options_scopes_init().

## ◆ scopes_count

size_t pm_options::scopes_count

The number of scopes surrounding the code that is being parsed.

Definition at line 135 of file options.h.

Referenced by pm_options_free(), pm_options_scopes_init(), and pm_parser::pm_parser_init().

## ◆ shebang_callback

pm_options_shebang_callback_t pm_options::shebang_callback

The callback to call when additional switches are found in a shebang comment.

Definition at line 109 of file options.h.

Referenced by pm_options_shebang_callback_set(), and pm_parser::pm_parser_init().

## ◆ shebang_callback_data

void* pm_options::shebang_callback_data

Any additional data that should be passed along to the shebang callback if one was set.

Definition at line 115 of file options.h.

Referenced by pm_options_shebang_callback_set().

## ◆ version

pm_options_version_t pm_options::version

The version of prism that we should be parsing with.

This is used to allow consumers to specify which behavior they want in case they need to parse exactly as a specific version of CRuby.

Definition at line 150 of file options.h.

Referenced by pm_options_read(), pm_options_version_set(), and pm_parser::pm_parser_init().

The documentation for this struct was generated from the following file:

- prism/options.h