Ruby 4.1.0dev (2026-11-12 revision acc624e47b178e3514d848a949f8e25d4e49e175)
options.h
1#ifndef PRISM_INTERNAL_OPTIONS_H
2#define PRISM_INTERNAL_OPTIONS_H
3
4#include "prism/options.h"
5
6/* A scope of locals surrounding the code that is being parsed. */
7struct pm_options_scope_t {
8 /* The number of locals in the scope. */
9 size_t locals_count;
10
11 /* The names of the locals in the scope. */
12 pm_string_t *locals;
13
14 /* Flags for the set of forwarding parameters in this scope. */
15 uint8_t forwarding;
16};
17
18/*
19 * The version of Ruby syntax that we should be parsing with. This is used to
20 * allow consumers to specify which behavior they want in case they need to
21 * parse in the same way as a specific version of CRuby would have.
22 */
23typedef enum {
24 /*
25 * If an explicit version is not provided, the current version of prism will
26 * be used.
27 */
28 PM_OPTIONS_VERSION_UNSET = 0,
29
30 /* The vendored version of prism in CRuby 3.3.x. */
31 PM_OPTIONS_VERSION_CRUBY_3_3 = 1,
32
33 /* The vendored version of prism in CRuby 3.4.x. */
34 PM_OPTIONS_VERSION_CRUBY_3_4 = 2,
35
36 /* The vendored version of prism in CRuby 4.0.x. */
37 PM_OPTIONS_VERSION_CRUBY_3_5 = 3,
38
39 /* The vendored version of prism in CRuby 4.0.x. */
40 PM_OPTIONS_VERSION_CRUBY_4_0 = 3,
41
42 /* The vendored version of prism in CRuby 4.1.x. */
43 PM_OPTIONS_VERSION_CRUBY_4_1 = 4,
44
45 /* The current version of prism. */
46 PM_OPTIONS_VERSION_LATEST = PM_OPTIONS_VERSION_CRUBY_4_1
47} pm_options_version_t;
48
49/* The options that can be passed to the parser. */
50struct pm_options_t {
51 /*
52 * The callback to call when additional switches are found in a shebang
53 * comment.
54 */
55 pm_options_shebang_callback_t shebang_callback;
56
57 /*
58 * Any additional data that should be passed along to the shebang callback
59 * if one was set.
60 */
61 void *shebang_callback_data;
62
63 /* The name of the file that is currently being parsed. */
64 pm_string_t filepath;
65
66 /*
67 * The line within the file that the parse starts on. This value is
68 * 1-indexed.
69 */
70 int32_t line;
71
72 /*
73 * The name of the encoding that the source file is in. Note that this must
74 * correspond to a name that can be found with Encoding.find in Ruby.
75 */
76 pm_string_t encoding;
77
78 /*
79 * The number of bytes of C stack that the parser may use, measured from
80 * where pm_parse is called. When the recursive descent goes past it, the
81 * parser reports that the stack is exhausted instead of overflowing it.
82 * SIZE_MAX means no budget was given, in which case only
83 * PRISM_DEPTH_MAXIMUM bounds the recursion.
84 */
85 size_t stack_budget;
86
87 /* The number of scopes surrounding the code that is being parsed. */
88 size_t scopes_count;
89
90 /*
91 * The scopes surrounding the code that is being parsed. For most parses
92 * this will be NULL, but for evals it will be the locals that are in scope
93 * surrounding the eval. Scopes are ordered from the outermost scope to the
94 * innermost one.
95 */
96 pm_options_scope_t *scopes;
97
98 /*
99 * The version of prism that we should be parsing with. This is used to
100 * allow consumers to specify which behavior they want in case they need to
101 * parse exactly as a specific version of CRuby.
102 */
103 pm_options_version_t version;
104
105 /* A bitset of the various options that were set on the command line. */
106 uint8_t command_line;
107
108 /*
109 * Whether or not the frozen string literal option has been set.
110 * May be:
111 * - PM_OPTIONS_FROZEN_STRING_LITERAL_DISABLED
112 * - PM_OPTIONS_FROZEN_STRING_LITERAL_ENABLED
113 * - PM_OPTIONS_FROZEN_STRING_LITERAL_UNSET
114 */
115 int8_t frozen_string_literal;
116
117 /*
118 * Whether or not the parser should raise an error when it encounters an
119 * error. By default this is off, but can be turned on in the case that you
120 * want nicely formatted syntax errors. The values that this can be set to
121 * are:
122 * - 0 - do not raise an error, just return the errors in the result
123 * - PM_ERRORS_FORMAT_PLAIN - raise a plain error with no formatting
124 * - PM_ERRORS_FORMAT_STYLE - raise an error with bold formatting
125 * - PM_ERRORS_FORMAT_COLOR - raise an error with color formatting
126 */
127 uint8_t raise_error;
128
129 /*
130 * Whether or not the encoding magic comments should be respected. This is a
131 * niche use-case where you want to parse a file with a specific encoding
132 * but ignore any encoding magic comments at the top of the file.
133 */
134 bool encoding_locked;
135
136 /*
137 * When the file being parsed is the main script, the shebang will be
138 * considered for command-line flags (or for implicit -x). The caller needs
139 * to pass this information to the parser so that it can behave correctly.
140 */
141 bool main_script;
142
143 /*
144 * When the file being parsed is considered a "partial" script, jumps will
145 * not be marked as errors if they are not contained within loops/blocks.
146 * This is used in the case that you're parsing a script that you know will
147 * be embedded inside another script later, but you do not have that context
148 * yet. For example, when parsing an ERB template that will be evaluated
149 * inside another script.
150 */
151 bool partial_script;
152
153 /*
154 * Whether or not the parser should freeze the nodes that it creates. This
155 * makes it possible to have a deeply frozen AST that is safe to share
156 * between concurrency primitives.
157 */
158 bool freeze;
159
160 /*
161 * Whether or not the parser should attach comments to the nodes that own
162 * them after parsing. When this is set, the parser's comment list is
163 * sorted by start offset and every comment is assigned an owning node.
164 */
165 bool attach_comments;
166};
167
168/* Free the internal memory associated with the options. */
169void pm_options_cleanup(pm_options_t *options);
170
171/*
172 * Deserialize an options struct from the given binary string. This is used to
173 * pass options to the parser from an FFI call so that consumers of the library
174 * from an FFI perspective don't have to worry about the structure of our
175 * options structs. Since the source of these calls will be from Ruby
176 * implementation internals we assume it is from a trusted source.
177 *
178 * `data` is assumed to be a valid pointer pointing to well-formed data. The
179 * layout of this data should be the same every time, and is described below:
180 *
181 * | # bytes | field |
182 * | ------- | -------------------------- |
183 * | `4` | the length of the filepath |
184 * | ... | the filepath bytes |
185 * | `4` | the line number |
186 * | `4` | the length the encoding |
187 * | ... | the encoding bytes |
188 * | `1` | frozen string literal |
189 * | `1` | -p command line option |
190 * | `1` | -n command line option |
191 * | `1` | -l command line option |
192 * | `1` | -a command line option |
193 * | `1` | the version |
194 * | `1` | encoding locked |
195 * | `1` | main script |
196 * | `1` | partial script |
197 * | `1` | freeze |
198 * | `1` | attach comments |
199 * | `4` | the number of scopes |
200 * | ... | the scopes |
201 *
202 * The version field is an enum, so it should be one of the following values:
203 *
204 * | value | version |
205 * | ----- | ------------------------- |
206 * | `0` | use the latest version of prism |
207 * | `1` | use the version of prism that is vendored in CRuby 3.3.0 |
208 * | `2` | use the version of prism that is vendored in CRuby 3.4.0 |
209 * | `3` | use the version of prism that is vendored in CRuby 4.0.0 |
210 * | `4` | use the version of prism that is vendored in CRuby 4.1.0 |
211 *
212 * Each scope is laid out as follows:
213 *
214 * | # bytes | field |
215 * | ------- | -------------------------- |
216 * | `4` | the number of locals |
217 * | `1` | the forwarding flags |
218 * | ... | the locals |
219 *
220 * Each local is laid out as follows:
221 *
222 * | # bytes | field |
223 * | ------- | -------------------------- |
224 * | `4` | the length of the local |
225 * | ... | the local bytes |
226 *
227 * Some additional things to note about this layout:
228 *
229 * * The filepath can have a length of 0, in which case we'll consider it an
230 * empty string.
231 * * The line number should be 0-indexed.
232 * * The encoding can have a length of 0, in which case we'll use the default
233 * encoding (UTF-8). If it's not 0, it should correspond to a name of an
234 * encoding that can be passed to `Encoding.find` in Ruby.
235 * * The frozen string literal, encoding locked, main script, and partial script
236 * fields are booleans, so their values should be either 0 or 1.
237 * * The number of scopes can be 0.
238 */
239void pm_options_read(pm_options_t *options, const char *data);
240
241#endif
options.h
The options that can be passed to parsing.
pm_options_shebang_callback_t
void(* pm_options_shebang_callback_t)(pm_options_t *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...
Definition options.h:75
pm_options_scope_t
Definition options.h:7
pm_options_t
Definition options.h:50
pm_string_t
A view of a sequence of bytes.
Definition stringy.h:23
Generated by doxygen 1.9.8