options.h File Reference

(c4ac3e987bf05a743ef9dcfb653bbb7e5b8637df)

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.

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.

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

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.