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