Ruby: prism/options.h File Reference

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

Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
options.h File Reference

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>`

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.

## Variables
static const uint8_t | PM_OPTIONS_SCOPE_FORWARDING_NONE = 0x0
| The default value for parameters.
static const uint8_t | PM_OPTIONS_SCOPE_FORWARDING_POSITIONALS = 0x1
| When the scope is fowarding with the * parameter.
static const uint8_t | PM_OPTIONS_SCOPE_FORWARDING_KEYWORDS = 0x2
| When the scope is fowarding with the ** parameter.
static const uint8_t | PM_OPTIONS_SCOPE_FORWARDING_BLOCK = 0x4
| When the scope is fowarding with the & parameter.
static const uint8_t | PM_OPTIONS_SCOPE_FORWARDING_ALL = 0x8
| When the scope is fowarding with the ... parameter.
static const uint8_t | PM_OPTIONS_COMMAND_LINE_A = 0x1
| A bit representing whether or not the command line -a option was set.
static const uint8_t | PM_OPTIONS_COMMAND_LINE_E = 0x2
| A bit representing whether or not the command line -e option was set.
static const uint8_t | PM_OPTIONS_COMMAND_LINE_L = 0x4
| A bit representing whether or not the command line -l option was set.
static const uint8_t | PM_OPTIONS_COMMAND_LINE_N = 0x8
| A bit representing whether or not the command line -n option was set.
static const uint8_t | PM_OPTIONS_COMMAND_LINE_P = 0x10
| A bit representing whether or not the command line -p option was set.
static const uint8_t | PM_OPTIONS_COMMAND_LINE_X = 0x20
| A bit representing whether or not the command line -x option was set.

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

Referenced by pm_options::pm_options_frozen_string_literal_set().

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

Referenced by pm_options::pm_options_frozen_string_literal_set().

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

Referenced by pm_parser::pm_parser_init().

## Typedef Documentation

## ◆ pm_options_scope_t

typedef struct pm_options_scope 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

  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.

Definition at line 77 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

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.

Definition at line 84 of file options.h.

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

Definition at line 265 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 200 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 207 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 213 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 219 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 225 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 231 of file options.h.

## ◆ PM_OPTIONS_SCOPE_FORWARDING_ALL

const uint8_t PM_OPTIONS_SCOPE_FORWARDING_ALL = 0x8
| static

When the scope is fowarding with the ... parameter.

Definition at line 60 of file options.h.

## ◆ PM_OPTIONS_SCOPE_FORWARDING_BLOCK

const uint8_t PM_OPTIONS_SCOPE_FORWARDING_BLOCK = 0x4
| static

When the scope is fowarding with the & parameter.

Definition at line 57 of file options.h.

## ◆ PM_OPTIONS_SCOPE_FORWARDING_KEYWORDS

const uint8_t PM_OPTIONS_SCOPE_FORWARDING_KEYWORDS = 0x2
| static

When the scope is fowarding with the ** parameter.

Definition at line 54 of file options.h.

## ◆ PM_OPTIONS_SCOPE_FORWARDING_NONE

const uint8_t PM_OPTIONS_SCOPE_FORWARDING_NONE = 0x0
| static

The default value for parameters.

Definition at line 48 of file options.h.

Referenced by pm_options::pm_options_scope_init().

## ◆ PM_OPTIONS_SCOPE_FORWARDING_POSITIONALS

const uint8_t PM_OPTIONS_SCOPE_FORWARDING_POSITIONALS = 0x1
| static

When the scope is fowarding with the * parameter.

Definition at line 51 of file options.h.