Ruby: prism/options.h File Reference

Ruby 3.3.4p94 (2024-07-09 revision be1089c8ec5ba40e09b1553e36b3174bf4014d9d)

Data Structures | Typedefs | Functions
options.h File Reference

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

`#include "prism/defines.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_t
| The options that can be passed to the parser. More...

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

## Functions
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_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_suppress_warnings_set (pm_options_t *options, bool suppress_warnings)
| Set the suppress warnings option on the given options struct.
PRISM_EXPORTED_FUNCTION void | 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 void | 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_free (pm_options_t *options)
| Free the internal memory associated with the options.
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.

Definition in file options.h.

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

## Function Documentation

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

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

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

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

Definition at line 84 of file options.c.

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

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

Definition at line 23 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` | suppress warnings
`4` | the number of scopes
... | the scopes

Each scope is layed out as follows:

# bytes | field
--- | ---
`4` | the number of locals
... | the locals

Each local is layed 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 and suppress warnings 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 141 of file options.c.

## ◆ 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 57 of file options.c.

## ◆ pm_options_scope_init()

PRISM_EXPORTED_FUNCTION void 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.

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

Definition at line 66 of file options.c.

## ◆ 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 76 of file options.c.

## ◆ pm_options_scopes_init()

PRISM_EXPORTED_FUNCTION void 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.

Definition at line 47 of file options.c.

## ◆ pm_options_suppress_warnings_set()

PRISM_EXPORTED_FUNCTION void pm_options_suppress_warnings_set | ( | pm_options_t * | options,
|  | bool | suppress_warnings )

Set the suppress warnings option on the given options struct.

Parameters

  options | The options struct to set the suppress warnings value on.
  suppress_warnings | The suppress warnings value to set.

Definition at line 39 of file options.c.