herb 0.7.2-x86-linux-gnu → 0.7.3-x86-linux-gnu

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. checksums.yaml +4 -4
  2. data/Makefile +2 -0
  3. data/README.md +1 -1
  4. data/Rakefile +46 -1
  5. data/config.yml +714 -0
  6. data/ext/herb/extconf.rb +2 -1
  7. data/ext/herb/nodes.c +1 -1
  8. data/herb.gemspec +3 -0
  9. data/lib/herb/3.0/herb.so +0 -0
  10. data/lib/herb/3.1/herb.so +0 -0
  11. data/lib/herb/3.2/herb.so +0 -0
  12. data/lib/herb/3.3/herb.so +0 -0
  13. data/lib/herb/3.4/herb.so +0 -0
  14. data/lib/herb/version.rb +1 -1
  15. data/src/analyze.c +5 -9
  16. data/src/analyze_helpers.c +17 -6
  17. data/src/include/pretty_print.h +1 -1
  18. data/src/include/version.h +1 -1
  19. data/src/parser.c +1 -0
  20. data/src/pretty_print.c +1 -1
  21. data/templates/ext/herb/error_helpers.c.erb +85 -0
  22. data/templates/ext/herb/error_helpers.h.erb +12 -0
  23. data/templates/ext/herb/nodes.c.erb +90 -0
  24. data/templates/ext/herb/nodes.h.erb +9 -0
  25. data/templates/javascript/packages/core/src/errors.ts.erb +193 -0
  26. data/templates/javascript/packages/core/src/node-type-guards.ts.erb +325 -0
  27. data/templates/javascript/packages/core/src/nodes.ts.erb +414 -0
  28. data/templates/javascript/packages/core/src/visitor.ts.erb +29 -0
  29. data/templates/javascript/packages/node/extension/error_helpers.cpp.erb +113 -0
  30. data/templates/javascript/packages/node/extension/error_helpers.h.erb +17 -0
  31. data/templates/javascript/packages/node/extension/nodes.cpp.erb +111 -0
  32. data/templates/javascript/packages/node/extension/nodes.h.erb +17 -0
  33. data/templates/lib/herb/ast/nodes.rb.erb +117 -0
  34. data/templates/lib/herb/errors.rb.erb +106 -0
  35. data/templates/lib/herb/visitor.rb.erb +28 -0
  36. data/templates/sig/serialized_ast_errors.rbs.erb +10 -0
  37. data/templates/sig/serialized_ast_nodes.rbs.erb +10 -0
  38. data/templates/src/ast_nodes.c.erb +145 -0
  39. data/templates/src/ast_pretty_print.c.erb +97 -0
  40. data/templates/src/errors.c.erb +245 -0
  41. data/templates/src/include/ast_nodes.h.erb +46 -0
  42. data/templates/src/include/ast_pretty_print.h.erb +14 -0
  43. data/templates/src/include/errors.h.erb +58 -0
  44. data/templates/src/visitor.c.erb +47 -0
  45. data/templates/template.rb +406 -0
  46. data/templates/wasm/error_helpers.cpp.erb +93 -0
  47. data/templates/wasm/error_helpers.h.erb +15 -0
  48. data/templates/wasm/nodes.cpp.erb +79 -0
  49. data/templates/wasm/nodes.h.erb +15 -0
  50. data/vendor/prism/Rakefile +75 -0
  51. data/vendor/prism/config.yml +4713 -0
  52. data/vendor/prism/include/prism/ast.h +8190 -0
  53. data/vendor/prism/include/prism/defines.h +260 -0
  54. data/vendor/prism/include/prism/diagnostic.h +455 -0
  55. data/vendor/prism/include/prism/encoding.h +283 -0
  56. data/vendor/prism/include/prism/node.h +129 -0
  57. data/vendor/prism/include/prism/options.h +482 -0
  58. data/vendor/prism/include/prism/pack.h +163 -0
  59. data/vendor/prism/include/prism/parser.h +933 -0
  60. data/vendor/prism/include/prism/prettyprint.h +34 -0
  61. data/vendor/prism/include/prism/regexp.h +43 -0
  62. data/vendor/prism/include/prism/static_literals.h +121 -0
  63. data/vendor/prism/include/prism/util/pm_buffer.h +236 -0
  64. data/vendor/prism/include/prism/util/pm_char.h +204 -0
  65. data/vendor/prism/include/prism/util/pm_constant_pool.h +218 -0
  66. data/vendor/prism/include/prism/util/pm_integer.h +130 -0
  67. data/vendor/prism/include/prism/util/pm_list.h +103 -0
  68. data/vendor/prism/include/prism/util/pm_memchr.h +29 -0
  69. data/vendor/prism/include/prism/util/pm_newline_list.h +113 -0
  70. data/vendor/prism/include/prism/util/pm_string.h +200 -0
  71. data/vendor/prism/include/prism/util/pm_strncasecmp.h +32 -0
  72. data/vendor/prism/include/prism/util/pm_strpbrk.h +46 -0
  73. data/vendor/prism/include/prism/version.h +29 -0
  74. data/vendor/prism/include/prism.h +408 -0
  75. data/vendor/prism/src/diagnostic.c +848 -0
  76. data/vendor/prism/src/encoding.c +5235 -0
  77. data/vendor/prism/src/node.c +8676 -0
  78. data/vendor/prism/src/options.c +328 -0
  79. data/vendor/prism/src/pack.c +509 -0
  80. data/vendor/prism/src/prettyprint.c +8941 -0
  81. data/vendor/prism/src/prism.c +23302 -0
  82. data/vendor/prism/src/regexp.c +790 -0
  83. data/vendor/prism/src/serialize.c +2268 -0
  84. data/vendor/prism/src/static_literals.c +617 -0
  85. data/vendor/prism/src/token_type.c +703 -0
  86. data/vendor/prism/src/util/pm_buffer.c +357 -0
  87. data/vendor/prism/src/util/pm_char.c +318 -0
  88. data/vendor/prism/src/util/pm_constant_pool.c +342 -0
  89. data/vendor/prism/src/util/pm_integer.c +670 -0
  90. data/vendor/prism/src/util/pm_list.c +49 -0
  91. data/vendor/prism/src/util/pm_memchr.c +35 -0
  92. data/vendor/prism/src/util/pm_newline_list.c +125 -0
  93. data/vendor/prism/src/util/pm_string.c +383 -0
  94. data/vendor/prism/src/util/pm_strncasecmp.c +36 -0
  95. data/vendor/prism/src/util/pm_strpbrk.c +206 -0
  96. data/vendor/prism/templates/ext/prism/api_node.c.erb +282 -0
  97. data/vendor/prism/templates/include/prism/ast.h.erb +226 -0
  98. data/vendor/prism/templates/include/prism/diagnostic.h.erb +130 -0
  99. data/vendor/prism/templates/java/org/prism/AbstractNodeVisitor.java.erb +22 -0
  100. data/vendor/prism/templates/java/org/prism/Loader.java.erb +434 -0
  101. data/vendor/prism/templates/java/org/prism/Nodes.java.erb +403 -0
  102. data/vendor/prism/templates/javascript/src/deserialize.js.erb +448 -0
  103. data/vendor/prism/templates/javascript/src/nodes.js.erb +197 -0
  104. data/vendor/prism/templates/javascript/src/visitor.js.erb +78 -0
  105. data/vendor/prism/templates/lib/prism/compiler.rb.erb +43 -0
  106. data/vendor/prism/templates/lib/prism/dispatcher.rb.erb +103 -0
  107. data/vendor/prism/templates/lib/prism/dot_visitor.rb.erb +189 -0
  108. data/vendor/prism/templates/lib/prism/dsl.rb.erb +133 -0
  109. data/vendor/prism/templates/lib/prism/inspect_visitor.rb.erb +131 -0
  110. data/vendor/prism/templates/lib/prism/mutation_compiler.rb.erb +19 -0
  111. data/vendor/prism/templates/lib/prism/node.rb.erb +515 -0
  112. data/vendor/prism/templates/lib/prism/reflection.rb.erb +136 -0
  113. data/vendor/prism/templates/lib/prism/serialize.rb.erb +602 -0
  114. data/vendor/prism/templates/lib/prism/visitor.rb.erb +55 -0
  115. data/vendor/prism/templates/rbi/prism/dsl.rbi.erb +68 -0
  116. data/vendor/prism/templates/rbi/prism/node.rbi.erb +164 -0
  117. data/vendor/prism/templates/rbi/prism/visitor.rbi.erb +18 -0
  118. data/vendor/prism/templates/sig/prism/_private/dot_visitor.rbs.erb +45 -0
  119. data/vendor/prism/templates/sig/prism/dsl.rbs.erb +31 -0
  120. data/vendor/prism/templates/sig/prism/mutation_compiler.rbs.erb +7 -0
  121. data/vendor/prism/templates/sig/prism/node.rbs.erb +132 -0
  122. data/vendor/prism/templates/sig/prism/visitor.rbs.erb +17 -0
  123. data/vendor/prism/templates/sig/prism.rbs.erb +89 -0
  124. data/vendor/prism/templates/src/diagnostic.c.erb +523 -0
  125. data/vendor/prism/templates/src/node.c.erb +333 -0
  126. data/vendor/prism/templates/src/prettyprint.c.erb +166 -0
  127. data/vendor/prism/templates/src/serialize.c.erb +406 -0
  128. data/vendor/prism/templates/src/token_type.c.erb +369 -0
  129. data/vendor/prism/templates/template.rb +689 -0
  130. metadata +112 -2
@@ -0,0 +1,408 @@
1
+ /**
2
+ * @file prism.h
3
+ *
4
+ * The main header file for the prism parser.
5
+ */
6
+ #ifndef PRISM_H
7
+ #define PRISM_H
8
+
9
+ #include "prism/defines.h"
10
+ #include "prism/util/pm_buffer.h"
11
+ #include "prism/util/pm_char.h"
12
+ #include "prism/util/pm_integer.h"
13
+ #include "prism/util/pm_memchr.h"
14
+ #include "prism/util/pm_strncasecmp.h"
15
+ #include "prism/util/pm_strpbrk.h"
16
+ #include "prism/ast.h"
17
+ #include "prism/diagnostic.h"
18
+ #include "prism/node.h"
19
+ #include "prism/options.h"
20
+ #include "prism/pack.h"
21
+ #include "prism/parser.h"
22
+ #include "prism/prettyprint.h"
23
+ #include "prism/regexp.h"
24
+ #include "prism/static_literals.h"
25
+ #include "prism/version.h"
26
+
27
+ #include <assert.h>
28
+ #include <errno.h>
29
+ #include <locale.h>
30
+ #include <math.h>
31
+ #include <stdarg.h>
32
+ #include <stdbool.h>
33
+ #include <stdint.h>
34
+ #include <stdio.h>
35
+ #include <stdlib.h>
36
+ #include <string.h>
37
+
38
+ #ifndef _WIN32
39
+ #include <strings.h>
40
+ #endif
41
+
42
+ /**
43
+ * The prism version and the serialization format.
44
+ *
45
+ * @returns The prism version as a constant string.
46
+ */
47
+ PRISM_EXPORTED_FUNCTION const char * pm_version(void);
48
+
49
+ /**
50
+ * Initialize a parser with the given start and end pointers.
51
+ *
52
+ * The resulting parser must eventually be freed with `pm_parser_free()`.
53
+ *
54
+ * @param parser The parser to initialize.
55
+ * @param source The source to parse.
56
+ * @param size The size of the source.
57
+ * @param options The optional options to use when parsing. These options must
58
+ * live for the whole lifetime of this parser.
59
+ *
60
+ * \public \memberof pm_parser
61
+ */
62
+ PRISM_EXPORTED_FUNCTION void pm_parser_init(pm_parser_t *parser, const uint8_t *source, size_t size, const pm_options_t *options);
63
+
64
+ /**
65
+ * Register a callback that will be called whenever prism changes the encoding
66
+ * it is using to parse based on the magic comment.
67
+ *
68
+ * @param parser The parser to register the callback with.
69
+ * @param callback The callback to register.
70
+ *
71
+ * \public \memberof pm_parser
72
+ */
73
+ PRISM_EXPORTED_FUNCTION void pm_parser_register_encoding_changed_callback(pm_parser_t *parser, pm_encoding_changed_callback_t callback);
74
+
75
+ /**
76
+ * Free any memory associated with the given parser.
77
+ *
78
+ * This does not free the `pm_options_t` object that was used to initialize the
79
+ * parser.
80
+ *
81
+ * @param parser The parser to free.
82
+ *
83
+ * \public \memberof pm_parser
84
+ */
85
+ PRISM_EXPORTED_FUNCTION void pm_parser_free(pm_parser_t *parser);
86
+
87
+ /**
88
+ * Initiate the parser with the given parser.
89
+ *
90
+ * @param parser The parser to use.
91
+ * @return The AST representing the source.
92
+ *
93
+ * \public \memberof pm_parser
94
+ */
95
+ PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse(pm_parser_t *parser);
96
+
97
+ /**
98
+ * This function is used in pm_parse_stream() to retrieve a line of input from a
99
+ * stream. It closely mirrors that of fgets so that fgets can be used as the
100
+ * default implementation.
101
+ */
102
+ typedef char * (pm_parse_stream_fgets_t)(char *string, int size, void *stream);
103
+
104
+ /**
105
+ * This function is used in pm_parse_stream to check whether a stream is EOF.
106
+ * It closely mirrors that of feof so that feof can be used as the
107
+ * default implementation.
108
+ */
109
+ typedef int (pm_parse_stream_feof_t)(void *stream);
110
+
111
+ /**
112
+ * Parse a stream of Ruby source and return the tree.
113
+ *
114
+ * @param parser The parser to use.
115
+ * @param buffer The buffer to use.
116
+ * @param stream The stream to parse.
117
+ * @param stream_fgets The function to use to read from the stream.
118
+ * @param stream_feof The function to use to determine if the stream has hit eof.
119
+ * @param options The optional options to use when parsing.
120
+ * @return The AST representing the source.
121
+ *
122
+ * \public \memberof pm_parser
123
+ */
124
+ PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse_stream(pm_parser_t *parser, pm_buffer_t *buffer, void *stream, pm_parse_stream_fgets_t *stream_fgets, pm_parse_stream_feof_t *stream_feof, const pm_options_t *options);
125
+
126
+ // We optionally support serializing to a binary string. For systems that don't
127
+ // want or need this functionality, it can be turned off with the
128
+ // PRISM_EXCLUDE_SERIALIZATION define.
129
+ #ifndef PRISM_EXCLUDE_SERIALIZATION
130
+
131
+ /**
132
+ * Parse and serialize the AST represented by the source that is read out of the
133
+ * given stream into to the given buffer.
134
+ *
135
+ * @param buffer The buffer to serialize to.
136
+ * @param stream The stream to parse.
137
+ * @param stream_fgets The function to use to read from the stream.
138
+ * @param stream_feof The function to use to tell if the stream has hit eof.
139
+ * @param data The optional data to pass to the parser.
140
+ */
141
+ PRISM_EXPORTED_FUNCTION void pm_serialize_parse_stream(pm_buffer_t *buffer, void *stream, pm_parse_stream_fgets_t *stream_fgets, pm_parse_stream_feof_t *stream_feof, const char *data);
142
+
143
+ /**
144
+ * Serialize the given list of comments to the given buffer.
145
+ *
146
+ * @param parser The parser to serialize.
147
+ * @param list The list of comments to serialize.
148
+ * @param buffer The buffer to serialize to.
149
+ */
150
+ void pm_serialize_comment_list(pm_parser_t *parser, pm_list_t *list, pm_buffer_t *buffer);
151
+
152
+ /**
153
+ * Serialize the name of the encoding to the buffer.
154
+ *
155
+ * @param encoding The encoding to serialize.
156
+ * @param buffer The buffer to serialize to.
157
+ */
158
+ void pm_serialize_encoding(const pm_encoding_t *encoding, pm_buffer_t *buffer);
159
+
160
+ /**
161
+ * Serialize the encoding, metadata, nodes, and constant pool.
162
+ *
163
+ * @param parser The parser to serialize.
164
+ * @param node The node to serialize.
165
+ * @param buffer The buffer to serialize to.
166
+ */
167
+ void pm_serialize_content(pm_parser_t *parser, pm_node_t *node, pm_buffer_t *buffer);
168
+
169
+ /**
170
+ * Serialize the AST represented by the given node to the given buffer.
171
+ *
172
+ * @param parser The parser to serialize.
173
+ * @param node The node to serialize.
174
+ * @param buffer The buffer to serialize to.
175
+ */
176
+ PRISM_EXPORTED_FUNCTION void pm_serialize(pm_parser_t *parser, pm_node_t *node, pm_buffer_t *buffer);
177
+
178
+ /**
179
+ * Parse the given source to the AST and dump the AST to the given buffer.
180
+ *
181
+ * @param buffer The buffer to serialize to.
182
+ * @param source The source to parse.
183
+ * @param size The size of the source.
184
+ * @param data The optional data to pass to the parser.
185
+ */
186
+ PRISM_EXPORTED_FUNCTION void pm_serialize_parse(pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data);
187
+
188
+ /**
189
+ * Parse and serialize the comments in the given source to the given buffer.
190
+ *
191
+ * @param buffer The buffer to serialize to.
192
+ * @param source The source to parse.
193
+ * @param size The size of the source.
194
+ * @param data The optional data to pass to the parser.
195
+ */
196
+ PRISM_EXPORTED_FUNCTION void pm_serialize_parse_comments(pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data);
197
+
198
+ /**
199
+ * Lex the given source and serialize to the given buffer.
200
+ *
201
+ * @param source The source to lex.
202
+ * @param size The size of the source.
203
+ * @param buffer The buffer to serialize to.
204
+ * @param data The optional data to pass to the lexer.
205
+ */
206
+ PRISM_EXPORTED_FUNCTION void pm_serialize_lex(pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data);
207
+
208
+ /**
209
+ * Parse and serialize both the AST and the tokens represented by the given
210
+ * source to the given buffer.
211
+ *
212
+ * @param buffer The buffer to serialize to.
213
+ * @param source The source to parse.
214
+ * @param size The size of the source.
215
+ * @param data The optional data to pass to the parser.
216
+ */
217
+ PRISM_EXPORTED_FUNCTION void pm_serialize_parse_lex(pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data);
218
+
219
+ #endif
220
+
221
+ /**
222
+ * Parse the source and return true if it parses without errors or warnings.
223
+ *
224
+ * @param source The source to parse.
225
+ * @param size The size of the source.
226
+ * @param data The optional data to pass to the parser.
227
+ * @return True if the source parses without errors or warnings.
228
+ */
229
+ PRISM_EXPORTED_FUNCTION bool pm_parse_success_p(const uint8_t *source, size_t size, const char *data);
230
+
231
+ /**
232
+ * Returns a string representation of the given token type.
233
+ *
234
+ * @param token_type The token type to convert to a string.
235
+ * @return A string representation of the given token type.
236
+ */
237
+ PRISM_EXPORTED_FUNCTION const char * pm_token_type_name(pm_token_type_t token_type);
238
+
239
+ /**
240
+ * Returns the human name of the given token type.
241
+ *
242
+ * @param token_type The token type to convert to a human name.
243
+ * @return The human name of the given token type.
244
+ */
245
+ const char * pm_token_type_human(pm_token_type_t token_type);
246
+
247
+ // We optionally support dumping to JSON. For systems that don't want or need
248
+ // this functionality, it can be turned off with the PRISM_EXCLUDE_JSON define.
249
+ #ifndef PRISM_EXCLUDE_JSON
250
+
251
+ /**
252
+ * Dump JSON to the given buffer.
253
+ *
254
+ * @param buffer The buffer to serialize to.
255
+ * @param parser The parser that parsed the node.
256
+ * @param node The node to serialize.
257
+ */
258
+ PRISM_EXPORTED_FUNCTION void pm_dump_json(pm_buffer_t *buffer, const pm_parser_t *parser, const pm_node_t *node);
259
+
260
+ #endif
261
+
262
+ /**
263
+ * Represents the results of a slice query.
264
+ */
265
+ typedef enum {
266
+ /** Returned if the encoding given to a slice query was invalid. */
267
+ PM_STRING_QUERY_ERROR = -1,
268
+
269
+ /** Returned if the result of the slice query is false. */
270
+ PM_STRING_QUERY_FALSE,
271
+
272
+ /** Returned if the result of the slice query is true. */
273
+ PM_STRING_QUERY_TRUE
274
+ } pm_string_query_t;
275
+
276
+ /**
277
+ * Check that the slice is a valid local variable name.
278
+ *
279
+ * @param source The source to check.
280
+ * @param length The length of the source.
281
+ * @param encoding_name The name of the encoding of the source.
282
+ * @return PM_STRING_QUERY_TRUE if the query is true, PM_STRING_QUERY_FALSE if
283
+ * the query is false, and PM_STRING_QUERY_ERROR if the encoding was invalid.
284
+ */
285
+ PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_local(const uint8_t *source, size_t length, const char *encoding_name);
286
+
287
+ /**
288
+ * Check that the slice is a valid constant name.
289
+ *
290
+ * @param source The source to check.
291
+ * @param length The length of the source.
292
+ * @param encoding_name The name of the encoding of the source.
293
+ * @return PM_STRING_QUERY_TRUE if the query is true, PM_STRING_QUERY_FALSE if
294
+ * the query is false, and PM_STRING_QUERY_ERROR if the encoding was invalid.
295
+ */
296
+ PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_constant(const uint8_t *source, size_t length, const char *encoding_name);
297
+
298
+ /**
299
+ * Check that the slice is a valid method name.
300
+ *
301
+ * @param source The source to check.
302
+ * @param length The length of the source.
303
+ * @param encoding_name The name of the encoding of the source.
304
+ * @return PM_STRING_QUERY_TRUE if the query is true, PM_STRING_QUERY_FALSE if
305
+ * the query is false, and PM_STRING_QUERY_ERROR if the encoding was invalid.
306
+ */
307
+ PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_method_name(const uint8_t *source, size_t length, const char *encoding_name);
308
+
309
+ /**
310
+ * @mainpage
311
+ *
312
+ * Prism is a parser for the Ruby programming language. It is designed to be
313
+ * portable, error tolerant, and maintainable. It is written in C99 and has no
314
+ * dependencies. It is currently being integrated into
315
+ * [CRuby](https://github.com/ruby/ruby),
316
+ * [JRuby](https://github.com/jruby/jruby),
317
+ * [TruffleRuby](https://github.com/oracle/truffleruby),
318
+ * [Sorbet](https://github.com/sorbet/sorbet), and
319
+ * [Syntax Tree](https://github.com/ruby-syntax-tree/syntax_tree).
320
+ *
321
+ * @section getting-started Getting started
322
+ *
323
+ * If you're vendoring this project and compiling it statically then as long as
324
+ * you have a C99 compiler you will be fine. If you're linking against it as
325
+ * shared library, then you should compile with `-fvisibility=hidden` and
326
+ * `-DPRISM_EXPORT_SYMBOLS` to tell prism to make only its public interface
327
+ * visible.
328
+ *
329
+ * @section parsing Parsing
330
+ *
331
+ * In order to parse Ruby code, the structures and functions that you're going
332
+ * to want to use and be aware of are:
333
+ *
334
+ * * `pm_parser_t` - the main parser structure
335
+ * * `pm_parser_init()` - initialize a parser
336
+ * * `pm_parse()` - parse and return the root node
337
+ * * `pm_node_destroy()` - deallocate the root node returned by `pm_parse()`
338
+ * * `pm_parser_free()` - free the internal memory of the parser
339
+ *
340
+ * Putting all of this together would look something like:
341
+ *
342
+ * ```c
343
+ * void parse(const uint8_t *source, size_t length) {
344
+ * pm_parser_t parser;
345
+ * pm_parser_init(&parser, source, length, NULL);
346
+ *
347
+ * pm_node_t *root = pm_parse(&parser);
348
+ * printf("PARSED!\n");
349
+ *
350
+ * pm_node_destroy(&parser, root);
351
+ * pm_parser_free(&parser);
352
+ * }
353
+ * ```
354
+ *
355
+ * All of the nodes "inherit" from `pm_node_t` by embedding those structures
356
+ * as their first member. This means you can downcast and upcast any node in the
357
+ * tree to a `pm_node_t`.
358
+ *
359
+ * @section serializing Serializing
360
+ *
361
+ * Prism provides the ability to serialize the AST and its related metadata into
362
+ * a binary format. This format is designed to be portable to different
363
+ * languages and runtimes so that you only need to make one FFI call in order to
364
+ * parse Ruby code. The structures and functions that you're going to want to
365
+ * use and be aware of are:
366
+ *
367
+ * * `pm_buffer_t` - a small buffer object that will hold the serialized AST
368
+ * * `pm_buffer_free()` - free the memory associated with the buffer
369
+ * * `pm_serialize()` - serialize the AST into a buffer
370
+ * * `pm_serialize_parse()` - parse and serialize the AST into a buffer
371
+ *
372
+ * Putting all of this together would look something like:
373
+ *
374
+ * ```c
375
+ * void serialize(const uint8_t *source, size_t length) {
376
+ * pm_buffer_t buffer = { 0 };
377
+ *
378
+ * pm_serialize_parse(&buffer, source, length, NULL);
379
+ * printf("SERIALIZED!\n");
380
+ *
381
+ * pm_buffer_free(&buffer);
382
+ * }
383
+ * ```
384
+ *
385
+ * @section inspecting Inspecting
386
+ *
387
+ * Prism provides the ability to inspect the AST by pretty-printing nodes. You
388
+ * can do this with the `pm_prettyprint()` function, which you would use like:
389
+ *
390
+ * ```c
391
+ * void prettyprint(const uint8_t *source, size_t length) {
392
+ * pm_parser_t parser;
393
+ * pm_parser_init(&parser, source, length, NULL);
394
+ *
395
+ * pm_node_t *root = pm_parse(&parser);
396
+ * pm_buffer_t buffer = { 0 };
397
+ *
398
+ * pm_prettyprint(&buffer, &parser, root);
399
+ * printf("%*.s\n", (int) buffer.length, buffer.value);
400
+ *
401
+ * pm_buffer_free(&buffer);
402
+ * pm_node_destroy(&parser, root);
403
+ * pm_parser_free(&parser);
404
+ * }
405
+ * ```
406
+ */
407
+
408
+ #endif