prism 0.24.0 → 0.26.0

data/include/prism/diagnostic.h

@@ -1,3 +1,11 @@
+/******************************************************************************/
+/* This file is generated by the templates/template.rb script and should not  */
+/* be modified manually. See                                                  */
+/* templates/include/prism/diagnostic.h.erb                                   */
+/* if you are looking to modify the                                           */
+/* template                                                                   */
+/******************************************************************************/
+
 /**
  * @file diagnostic.h
  *
@@ -14,68 +22,14 @@
 #include <stdlib.h>
 #include <assert.h>
 
-/**
- * The levels of errors generated during parsing.
- */
-typedef enum {
-    /** For errors that cannot be recovered from. */
-    PM_ERROR_LEVEL_FATAL = 0,
-
-    /** For errors that should raise an argument error. */
-    PM_ERROR_LEVEL_ARGUMENT = 1
-} pm_error_level_t;
-
-/**
- * The levels of warnings generated during parsing.
- */
-typedef enum {
-    /** For warnings which should be emitted if $VERBOSE != nil. */
-    PM_WARNING_LEVEL_DEFAULT = 0,
-
-    /** For warnings which should be emitted if $VERBOSE == true. */
-    PM_WARNING_LEVEL_VERBOSE = 1
-} pm_warning_level_t;
-
-/**
- * This struct represents a diagnostic generated during parsing.
- *
- * @extends pm_list_node_t
- */
-typedef struct {
-    /** The embedded base node. */
-    pm_list_node_t node;
-
-    /** The location of the diagnostic in the source. */
-    pm_location_t location;
-
-    /** The message associated with the diagnostic. */
-    const char *message;
-
-    /**
-     * Whether or not the memory related to the message of this diagnostic is
-     * owned by this diagnostic. If it is, it needs to be freed when the
-     * diagnostic is freed.
-     */
-    bool owned;
-
-    /**
-     * The level of the diagnostic, see `pm_error_level_t` and
-     * `pm_warning_level_t` for possible values.
-     */
-    uint8_t level;
-} pm_diagnostic_t;
-
 /**
  * The diagnostic IDs of all of the diagnostics, used to communicate the types
  * of errors between the parser and the user.
  */
 typedef enum {
-    // This is a special error that we can potentially replace by others. For
-    // an example of how this is used, see parse_expression_prefix.
-    PM_ERR_CANNOT_PARSE_EXPRESSION,
-
-    // These are the error codes.
+    // These are the error diagnostics.
     PM_ERR_ALIAS_ARGUMENT,
+    PM_ERR_ALIAS_ARGUMENT_NUMBERED_REFERENCE,
     PM_ERR_AMPAMPEQ_MULTI_ASSIGN,
     PM_ERR_ARGUMENT_AFTER_BLOCK,
     PM_ERR_ARGUMENT_AFTER_FORWARDING_ELLIPSES,
@@ -91,6 +45,7 @@ typedef enum {
     PM_ERR_ARGUMENT_NO_FORWARDING_AMP,
     PM_ERR_ARGUMENT_NO_FORWARDING_ELLIPSES,
     PM_ERR_ARGUMENT_NO_FORWARDING_STAR,
+    PM_ERR_ARGUMENT_NO_FORWARDING_STAR_STAR,
     PM_ERR_ARGUMENT_SPLAT_AFTER_ASSOC_SPLAT,
     PM_ERR_ARGUMENT_SPLAT_AFTER_SPLAT,
     PM_ERR_ARGUMENT_TERM_PAREN,
@@ -109,6 +64,7 @@ typedef enum {
     PM_ERR_BLOCK_PARAM_PIPE_TERM,
     PM_ERR_BLOCK_TERM_BRACE,
     PM_ERR_BLOCK_TERM_END,
+    PM_ERR_CANNOT_PARSE_EXPRESSION,
     PM_ERR_CANNOT_PARSE_STRING_PART,
     PM_ERR_CASE_EXPRESSION_AFTER_CASE,
     PM_ERR_CASE_EXPRESSION_AFTER_WHEN,
@@ -120,6 +76,7 @@ typedef enum {
     PM_ERR_CLASS_SUPERCLASS,
     PM_ERR_CLASS_TERM,
     PM_ERR_CLASS_UNEXPECTED_END,
+    PM_ERR_CLASS_VARIABLE_BARE,
     PM_ERR_CONDITIONAL_ELSIF_PREDICATE,
     PM_ERR_CONDITIONAL_IF_PREDICATE,
     PM_ERR_CONDITIONAL_PREDICATE_TERM,
@@ -132,7 +89,6 @@ typedef enum {
     PM_ERR_DEF_ENDLESS,
     PM_ERR_DEF_ENDLESS_SETTER,
     PM_ERR_DEF_NAME,
-    PM_ERR_DEF_NAME_AFTER_RECEIVER,
     PM_ERR_DEF_PARAMS_TERM,
     PM_ERR_DEF_PARAMS_TERM_PAREN,
     PM_ERR_DEF_RECEIVER,
@@ -157,18 +113,19 @@ typedef enum {
     PM_ERR_EXPECT_ARGUMENT,
     PM_ERR_EXPECT_EOL_AFTER_STATEMENT,
     PM_ERR_EXPECT_EXPRESSION_AFTER_AMPAMPEQ,
-    PM_ERR_EXPECT_EXPRESSION_AFTER_PIPEPIPEEQ,
     PM_ERR_EXPECT_EXPRESSION_AFTER_COMMA,
     PM_ERR_EXPECT_EXPRESSION_AFTER_EQUAL,
     PM_ERR_EXPECT_EXPRESSION_AFTER_LESS_LESS,
     PM_ERR_EXPECT_EXPRESSION_AFTER_LPAREN,
-    PM_ERR_EXPECT_EXPRESSION_AFTER_QUESTION,
     PM_ERR_EXPECT_EXPRESSION_AFTER_OPERATOR,
+    PM_ERR_EXPECT_EXPRESSION_AFTER_PIPEPIPEEQ,
+    PM_ERR_EXPECT_EXPRESSION_AFTER_QUESTION,
     PM_ERR_EXPECT_EXPRESSION_AFTER_SPLAT,
     PM_ERR_EXPECT_EXPRESSION_AFTER_SPLAT_HASH,
     PM_ERR_EXPECT_EXPRESSION_AFTER_STAR,
     PM_ERR_EXPECT_IDENT_REQ_PARAMETER,
     PM_ERR_EXPECT_LPAREN_REQ_PARAMETER,
+    PM_ERR_EXPECT_MESSAGE,
     PM_ERR_EXPECT_RBRACKET,
     PM_ERR_EXPECT_RPAREN,
     PM_ERR_EXPECT_RPAREN_AFTER_MULTI,
@@ -176,10 +133,20 @@ typedef enum {
     PM_ERR_EXPECT_STRING_CONTENT,
     PM_ERR_EXPECT_WHEN_DELIMITER,
     PM_ERR_EXPRESSION_BARE_HASH,
+    PM_ERR_EXPRESSION_NOT_WRITABLE,
+    PM_ERR_EXPRESSION_NOT_WRITABLE_ENCODING,
+    PM_ERR_EXPRESSION_NOT_WRITABLE_FALSE,
+    PM_ERR_EXPRESSION_NOT_WRITABLE_FILE,
+    PM_ERR_EXPRESSION_NOT_WRITABLE_LINE,
+    PM_ERR_EXPRESSION_NOT_WRITABLE_NIL,
+    PM_ERR_EXPRESSION_NOT_WRITABLE_SELF,
+    PM_ERR_EXPRESSION_NOT_WRITABLE_TRUE,
+    PM_ERR_FLOAT_PARSE,
     PM_ERR_FOR_COLLECTION,
     PM_ERR_FOR_IN,
     PM_ERR_FOR_INDEX,
     PM_ERR_FOR_TERM,
+    PM_ERR_GLOBAL_VARIABLE_BARE,
     PM_ERR_HASH_EXPRESSION_AFTER_LABEL,
     PM_ERR_HASH_KEY,
     PM_ERR_HASH_ROCKET,
@@ -188,20 +155,32 @@ typedef enum {
     PM_ERR_HEREDOC_TERM,
     PM_ERR_INCOMPLETE_QUESTION_MARK,
     PM_ERR_INCOMPLETE_VARIABLE_CLASS,
+    PM_ERR_INCOMPLETE_VARIABLE_CLASS_3_3_0,
     PM_ERR_INCOMPLETE_VARIABLE_INSTANCE,
+    PM_ERR_INCOMPLETE_VARIABLE_INSTANCE_3_3_0,
+    PM_ERR_INSTANCE_VARIABLE_BARE,
+    PM_ERR_INVALID_BLOCK_EXIT,
+    PM_ERR_INVALID_CHARACTER,
     PM_ERR_INVALID_ENCODING_MAGIC_COMMENT,
     PM_ERR_INVALID_FLOAT_EXPONENT,
+    PM_ERR_INVALID_MULTIBYTE_CHAR,
+    PM_ERR_INVALID_MULTIBYTE_CHARACTER,
+    PM_ERR_INVALID_MULTIBYTE_ESCAPE,
     PM_ERR_INVALID_NUMBER_BINARY,
     PM_ERR_INVALID_NUMBER_DECIMAL,
     PM_ERR_INVALID_NUMBER_HEXADECIMAL,
     PM_ERR_INVALID_NUMBER_OCTAL,
     PM_ERR_INVALID_NUMBER_UNDERSCORE,
-    PM_ERR_INVALID_CHARACTER,
-    PM_ERR_INVALID_MULTIBYTE_CHARACTER,
-    PM_ERR_INVALID_PRINTABLE_CHARACTER,
     PM_ERR_INVALID_PERCENT,
+    PM_ERR_INVALID_PRINTABLE_CHARACTER,
+    PM_ERR_INVALID_RETRY_AFTER_ELSE,
+    PM_ERR_INVALID_RETRY_AFTER_ENSURE,
+    PM_ERR_INVALID_RETRY_WITHOUT_RESCUE,
     PM_ERR_INVALID_VARIABLE_GLOBAL,
-    PM_ERR_IT_NOT_ALLOWED,
+    PM_ERR_INVALID_VARIABLE_GLOBAL_3_3_0,
+    PM_ERR_INVALID_YIELD,
+    PM_ERR_IT_NOT_ALLOWED_NUMBERED,
+    PM_ERR_IT_NOT_ALLOWED_ORDINARY,
     PM_ERR_LAMBDA_OPEN,
     PM_ERR_LAMBDA_TERM_BRACE,
     PM_ERR_LAMBDA_TERM_END,
@@ -220,10 +199,11 @@ typedef enum {
     PM_ERR_MODULE_TERM,
     PM_ERR_MULTI_ASSIGN_MULTI_SPLATS,
     PM_ERR_MULTI_ASSIGN_UNEXPECTED_REST,
-    PM_ERR_NOT_EXPRESSION,
     PM_ERR_NO_LOCAL_VARIABLE,
+    PM_ERR_NOT_EXPRESSION,
     PM_ERR_NUMBER_LITERAL_UNDERSCORE,
-    PM_ERR_NUMBERED_PARAMETER_NOT_ALLOWED,
+    PM_ERR_NUMBERED_PARAMETER_IT,
+    PM_ERR_NUMBERED_PARAMETER_ORDINARY,
     PM_ERR_NUMBERED_PARAMETER_OUTER_SCOPE,
     PM_ERR_OPERATOR_MULTI_ASSIGN,
     PM_ERR_OPERATOR_WRITE_ARGUMENTS,
@@ -232,7 +212,7 @@ typedef enum {
     PM_ERR_PARAMETER_BLOCK_MULTI,
     PM_ERR_PARAMETER_CIRCULAR,
     PM_ERR_PARAMETER_METHOD_NAME,
-    PM_ERR_PARAMETER_NAME_REPEAT,
+    PM_ERR_PARAMETER_NAME_DUPLICATED,
     PM_ERR_PARAMETER_NO_DEFAULT,
     PM_ERR_PARAMETER_NO_DEFAULT_KW,
     PM_ERR_PARAMETER_NUMBERED_RESERVED,
@@ -241,9 +221,10 @@ typedef enum {
     PM_ERR_PARAMETER_STAR,
     PM_ERR_PARAMETER_UNEXPECTED_FWD,
     PM_ERR_PARAMETER_WILD_LOOSE_COMMA,
+    PM_ERR_PATTERN_CAPTURE_DUPLICATE,
     PM_ERR_PATTERN_EXPRESSION_AFTER_BRACKET,
-    PM_ERR_PATTERN_EXPRESSION_AFTER_HROCKET,
     PM_ERR_PATTERN_EXPRESSION_AFTER_COMMA,
+    PM_ERR_PATTERN_EXPRESSION_AFTER_HROCKET,
     PM_ERR_PATTERN_EXPRESSION_AFTER_IN,
     PM_ERR_PATTERN_EXPRESSION_AFTER_KEY,
     PM_ERR_PATTERN_EXPRESSION_AFTER_PAREN,
@@ -252,6 +233,7 @@ typedef enum {
     PM_ERR_PATTERN_EXPRESSION_AFTER_RANGE,
     PM_ERR_PATTERN_EXPRESSION_AFTER_REST,
     PM_ERR_PATTERN_HASH_KEY,
+    PM_ERR_PATTERN_HASH_KEY_DUPLICATE,
     PM_ERR_PATTERN_HASH_KEY_LABEL,
     PM_ERR_PATTERN_IDENT_AFTER_HROCKET,
     PM_ERR_PATTERN_LABEL_AFTER_COMMA,
@@ -260,12 +242,19 @@ typedef enum {
     PM_ERR_PATTERN_TERM_BRACKET,
     PM_ERR_PATTERN_TERM_PAREN,
     PM_ERR_PIPEPIPEEQ_MULTI_ASSIGN,
+    PM_ERR_REGEXP_ENCODING_OPTION_MISMATCH,
+    PM_ERR_REGEXP_INCOMPAT_CHAR_ENCODING,
+    PM_ERR_REGEXP_INVALID_UNICODE_RANGE,
+    PM_ERR_REGEXP_NON_ESCAPED_MBC,
     PM_ERR_REGEXP_TERM,
+    PM_ERR_REGEXP_UNKNOWN_OPTIONS,
+    PM_ERR_REGEXP_UTF8_CHAR_NON_UTF8_REGEXP,
     PM_ERR_RESCUE_EXPRESSION,
     PM_ERR_RESCUE_MODIFIER_VALUE,
     PM_ERR_RESCUE_TERM,
     PM_ERR_RESCUE_VARIABLE,
     PM_ERR_RETURN_INVALID,
+    PM_ERR_SCRIPT_NOT_FOUND,
     PM_ERR_SINGLETON_FOR_LITERALS,
     PM_ERR_STATEMENT_ALIAS,
     PM_ERR_STATEMENT_POSTEXE_END,
@@ -282,9 +271,10 @@ typedef enum {
     PM_ERR_TERNARY_EXPRESSION_FALSE,
     PM_ERR_TERNARY_EXPRESSION_TRUE,
     PM_ERR_UNARY_RECEIVER,
+    PM_ERR_UNDEF_ARGUMENT,
+    PM_ERR_UNEXPECTED_BLOCK_ARGUMENT,
     PM_ERR_UNEXPECTED_TOKEN_CLOSE_CONTEXT,
     PM_ERR_UNEXPECTED_TOKEN_IGNORE,
-    PM_ERR_UNDEF_ARGUMENT,
     PM_ERR_UNTIL_TERM,
     PM_ERR_VOID_EXPRESSION,
     PM_ERR_WHILE_TERM,
@@ -293,17 +283,101 @@ typedef enum {
     PM_ERR_WRITE_TARGET_UNEXPECTED,
     PM_ERR_XSTRING_TERM,
 
-    // These are the warning codes.
+    // These are the warning diagnostics.
     PM_WARN_AMBIGUOUS_FIRST_ARGUMENT_MINUS,
     PM_WARN_AMBIGUOUS_FIRST_ARGUMENT_PLUS,
+    PM_WARN_AMBIGUOUS_PREFIX_AMPERSAND,
     PM_WARN_AMBIGUOUS_PREFIX_STAR,
+    PM_WARN_AMBIGUOUS_PREFIX_STAR_STAR,
     PM_WARN_AMBIGUOUS_SLASH,
+    PM_WARN_COMPARISON_AFTER_COMPARISON,
+    PM_WARN_DOT_DOT_DOT_EOL,
+    PM_WARN_EQUAL_IN_CONDITIONAL,
+    PM_WARN_EQUAL_IN_CONDITIONAL_3_3_0,
     PM_WARN_END_IN_METHOD,
-
-    // This is the number of diagnostic codes.
-    PM_DIAGNOSTIC_ID_LEN,
+    PM_WARN_DUPLICATED_HASH_KEY,
+    PM_WARN_DUPLICATED_WHEN_CLAUSE,
+    PM_WARN_FLOAT_OUT_OF_RANGE,
+    PM_WARN_IGNORED_FROZEN_STRING_LITERAL,
+    PM_WARN_INTEGER_IN_FLIP_FLOP,
+    PM_WARN_INVALID_CHARACTER,
+    PM_WARN_INVALID_NUMBERED_REFERENCE,
+    PM_WARN_INVALID_SHAREABLE_CONSTANT_VALUE,
+    PM_WARN_KEYWORD_EOL,
+    PM_WARN_LITERAL_IN_CONDITION_DEFAULT,
+    PM_WARN_LITERAL_IN_CONDITION_VERBOSE,
+    PM_WARN_SHEBANG_CARRIAGE_RETURN,
+    PM_WARN_UNEXPECTED_CARRIAGE_RETURN,
+    PM_WARN_UNREACHABLE_STATEMENT,
+    PM_WARN_UNUSED_LOCAL_VARIABLE,
+    PM_WARN_VOID_STATEMENT,
 } pm_diagnostic_id_t;
 
+/**
+ * This struct represents a diagnostic generated during parsing.
+ *
+ * @extends pm_list_node_t
+ */
+typedef struct {
+    /** The embedded base node. */
+    pm_list_node_t node;
+
+    /** The location of the diagnostic in the source. */
+    pm_location_t location;
+
+    /** The ID of the diagnostic. */
+    pm_diagnostic_id_t diag_id;
+
+    /** The message associated with the diagnostic. */
+    const char *message;
+
+    /**
+     * Whether or not the memory related to the message of this diagnostic is
+     * owned by this diagnostic. If it is, it needs to be freed when the
+     * diagnostic is freed.
+     */
+    bool owned;
+
+    /**
+     * The level of the diagnostic, see `pm_error_level_t` and
+     * `pm_warning_level_t` for possible values.
+     */
+    uint8_t level;
+} pm_diagnostic_t;
+
+/**
+ * The levels of errors generated during parsing.
+ */
+typedef enum {
+    /** For errors that should raise a syntax error. */
+    PM_ERROR_LEVEL_SYNTAX = 0,
+
+    /** For errors that should raise an argument error. */
+    PM_ERROR_LEVEL_ARGUMENT = 1,
+
+    /** For errors that should raise a load error. */
+    PM_ERROR_LEVEL_LOAD = 2
+} pm_error_level_t;
+
+/**
+ * The levels of warnings generated during parsing.
+ */
+typedef enum {
+    /** For warnings which should be emitted if $VERBOSE != nil. */
+    PM_WARNING_LEVEL_DEFAULT = 0,
+
+    /** For warnings which should be emitted if $VERBOSE == true. */
+    PM_WARNING_LEVEL_VERBOSE = 1
+} pm_warning_level_t;
+
+/**
+ * Get the human-readable name of the given diagnostic ID.
+ *
+ * @param diag_id The diagnostic ID.
+ * @return The human-readable name of the diagnostic ID.
+ */
+const char * pm_diagnostic_id_human(pm_diagnostic_id_t diag_id);
+
 /**
  * Append a diagnostic to the given list of diagnostics that is using shared
  * memory for its message.

data/include/prism/encoding.h

@@ -135,7 +135,14 @@ extern const uint8_t pm_encoding_unicode_table[256];
  */
 typedef enum {
     PM_ENCODING_UTF_8 = 0,
+    PM_ENCODING_US_ASCII,
     PM_ENCODING_ASCII_8BIT,
+    PM_ENCODING_EUC_JP,
+    PM_ENCODING_WINDOWS_31J,
+
+// We optionally support excluding the full set of encodings to only support the
+// minimum necessary to process Ruby code without encoding comments.
+#ifndef PRISM_ENCODING_EXCLUDE_FULL
     PM_ENCODING_BIG5,
     PM_ENCODING_BIG5_HKSCS,
     PM_ENCODING_BIG5_UAO,
@@ -148,7 +155,6 @@ typedef enum {
     PM_ENCODING_CP950,
     PM_ENCODING_CP951,
     PM_ENCODING_EMACS_MULE,
-    PM_ENCODING_EUC_JP,
     PM_ENCODING_EUC_JP_MS,
     PM_ENCODING_EUC_JIS_2004,
     PM_ENCODING_EUC_KR,
@@ -208,7 +214,6 @@ typedef enum {
     PM_ENCODING_STATELESS_ISO_2022_JP,
     PM_ENCODING_STATELESS_ISO_2022_JP_KDDI,
     PM_ENCODING_TIS_620,
-    PM_ENCODING_US_ASCII,
     PM_ENCODING_UTF8_MAC,
     PM_ENCODING_UTF8_DOCOMO,
     PM_ENCODING_UTF8_KDDI,
@@ -222,8 +227,9 @@ typedef enum {
     PM_ENCODING_WINDOWS_1256,
     PM_ENCODING_WINDOWS_1257,
     PM_ENCODING_WINDOWS_1258,
-    PM_ENCODING_WINDOWS_31J,
     PM_ENCODING_WINDOWS_874,
+#endif
+
     PM_ENCODING_MAXIMUM
 } pm_encoding_type_t;
 
@@ -248,10 +254,22 @@ extern const pm_encoding_t pm_encodings[PM_ENCODING_MAXIMUM];
 /**
  * This is the ASCII-8BIT encoding. We need a reference to it so that pm_strpbrk
  * can compare against it because invalid multibyte characters are not a thing
- * in this encoding.
+ * in this encoding. It is also needed for handling Regexp encoding flags.
  */
 #define PM_ENCODING_ASCII_8BIT_ENTRY (&pm_encodings[PM_ENCODING_ASCII_8BIT])
 
+/**
+ * This is the EUC-JP encoding. We need a reference to it to quickly process
+ * regular expression modifiers.
+ */
+#define PM_ENCODING_EUC_JP_ENTRY (&pm_encodings[PM_ENCODING_EUC_JP])
+
+/**
+ * This is the Windows-31J encoding. We need a reference to it to quickly
+ * process regular expression modifiers.
+ */
+#define PM_ENCODING_WINDOWS_31J_ENTRY (&pm_encodings[PM_ENCODING_WINDOWS_31J])
+
 /**
  * Parse the given name of an encoding and return a pointer to the corresponding
  * encoding struct if one can be found, otherwise return NULL.

data/include/prism/node.h

@@ -8,6 +8,14 @@
 
 #include "prism/defines.h"
 #include "prism/parser.h"
+#include "prism/util/pm_buffer.h"
+
+/**
+ * Loop through each node in the node list, writing each node to the given
+ * pm_node_t pointer.
+ */
+#define PM_NODE_LIST_FOREACH(list, index, node) \
+    for (size_t index = 0; index < (list)->size && ((node) = (list)->nodes[index]); index++)
 
 /**
  * Append a new node onto the end of the node list.
@@ -17,6 +25,29 @@
  */
 void pm_node_list_append(pm_node_list_t *list, pm_node_t *node);
 
+/**
+ * Prepend a new node onto the beginning of the node list.
+ *
+ * @param list The list to prepend to.
+ * @param node The node to prepend.
+ */
+void pm_node_list_prepend(pm_node_list_t *list, pm_node_t *node);
+
+/**
+ * Concatenate the given node list onto the end of the other node list.
+ *
+ * @param list The list to concatenate onto.
+ * @param other The list to concatenate.
+ */
+void pm_node_list_concat(pm_node_list_t *list, pm_node_list_t *other);
+
+/**
+ * Free the internal memory associated with the given node list.
+ *
+ * @param list The list to free.
+ */
+void pm_node_list_free(pm_node_list_t *list);
+
 /**
  * Deallocate a node and all of its children.
  *
@@ -54,4 +85,66 @@ PRISM_EXPORTED_FUNCTION void pm_node_memsize(pm_node_t *node, pm_memsize_t *mems
  */
 PRISM_EXPORTED_FUNCTION const char * pm_node_type_to_str(pm_node_type_t node_type);
 
+/**
+ * Visit each of the nodes in this subtree using the given visitor callback. The
+ * callback function will be called for each node in the subtree. If it returns
+ * false, then that node's children will not be visited. If it returns true,
+ * then the children will be visited. The data parameter is treated as an opaque
+ * pointer and is passed to the visitor callback for consumers to use as they
+ * see fit.
+ *
+ * As an example:
+ *
+ * ```c
+ * #include "prism.h"
+ *
+ * bool visit(const pm_node_t *node, void *data) {
+ *     size_t *indent = (size_t *) data;
+ *     for (size_t i = 0; i < *indent * 2; i++) putc(' ', stdout);
+ *     printf("%s\n", pm_node_type_to_str(node->type));
+ *
+ *     size_t next_indent = *indent + 1;
+ *     size_t *next_data = &next_indent;
+ *     pm_visit_child_nodes(node, visit, next_data);
+ *
+ *     return false;
+ * }
+ *
+ * int main(void) {
+ *     const char *source = "1 + 2; 3 + 4";
+ *     size_t size = strlen(source);
+ *
+ *     pm_parser_t parser;
+ *     pm_options_t options = { 0 };
+ *     pm_parser_init(&parser, (const uint8_t *) source, size, &options);
+ *
+ *     size_t indent = 0;
+ *     pm_node_t *node = pm_parse(&parser);
+ *
+ *     size_t *data = &indent;
+ *     pm_visit_node(node, visit, data);
+ *
+ *     pm_node_destroy(&parser, node);
+ *     pm_parser_free(&parser);
+ *     return EXIT_SUCCESS;
+ * }
+ * ```
+ *
+ * @param node The root node to start visiting from.
+ * @param visitor The callback to call for each node in the subtree.
+ * @param data An opaque pointer that is passed to the visitor callback.
+ */
+PRISM_EXPORTED_FUNCTION void pm_visit_node(const pm_node_t *node, bool (*visitor)(const pm_node_t *node, void *data), void *data);
+
+/**
+ * Visit the children of the given node with the given callback. This is the
+ * default behavior for walking the tree that is called from pm_visit_node if
+ * the callback returns true.
+ *
+ * @param node The node to visit the children of.
+ * @param visitor The callback to call for each child node.
+ * @param data An opaque pointer that is passed to the visitor callback.
+ */
+PRISM_EXPORTED_FUNCTION void pm_visit_child_nodes(const pm_node_t *node, bool (*visitor)(const pm_node_t *node, void *data), void *data);
+
 #endif

data/include/prism/options.h

@@ -13,6 +13,22 @@
 #include <stddef.h>
 #include <stdint.h>
 
+/**
+ * String literals should be made frozen.
+ */
+#define PM_OPTIONS_FROZEN_STRING_LITERAL_DISABLED   ((int8_t) -1)
+
+/**
+ * String literals may be frozen or mutable depending on the implementation
+ * default.
+ */
+#define PM_OPTIONS_FROZEN_STRING_LITERAL_UNSET      ((int8_t)  0)
+
+/**
+ * String literals should be made mutable.
+ */
+#define PM_OPTIONS_FROZEN_STRING_LITERAL_ENABLED    ((int8_t)  1)
+
 /**
  * A scope of locals surrounding the code that is being parsed.
  */
@@ -76,10 +92,56 @@ typedef struct {
      */
     pm_options_version_t version;
 
-    /** Whether or not the frozen string literal option has been set. */
-    bool frozen_string_literal;
+    /** A bitset of the various options that were set on the command line. */
+    uint8_t command_line;
+
+    /**
+    * Whether or not the frozen string literal option has been set.
+    * May be:
+    *  - PM_OPTIONS_FROZEN_STRING_LITERAL_DISABLED
+    *  - PM_OPTIONS_FROZEN_STRING_LITERAL_ENABLED
+    *  - PM_OPTIONS_FROZEN_STRING_LITERAL_UNSET
+    */
+    int8_t frozen_string_literal;
 } pm_options_t;
 
+/**
+ * A bit representing whether or not the command line -a option was set. -a
+ * splits the input line $_ into $F.
+ */
+static const uint8_t PM_OPTIONS_COMMAND_LINE_A = 0x1;
+
+/**
+ * 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.
+ */
+static const uint8_t PM_OPTIONS_COMMAND_LINE_E = 0x2;
+
+/**
+ * A bit representing whether or not the command line -l option was set. -l
+ * chomps the input line by default.
+ */
+static const uint8_t PM_OPTIONS_COMMAND_LINE_L = 0x4;
+
+/**
+ * A bit representing whether or not the command line -n option was set. -n
+ * wraps the script in a while gets loop.
+ */
+static const uint8_t PM_OPTIONS_COMMAND_LINE_N = 0x8;
+
+/**
+ * A bit representing whether or not the command line -p option was set. -p
+ * prints the value of $_ at the end of each loop.
+ */
+static const uint8_t PM_OPTIONS_COMMAND_LINE_P = 0x10;
+
+/**
+ * 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.
+ */
+static const uint8_t PM_OPTIONS_COMMAND_LINE_X = 0x20;
+
 /**
  * Set the filepath option on the given options struct.
  *
@@ -112,6 +174,14 @@ PRISM_EXPORTED_FUNCTION void pm_options_encoding_set(pm_options_t *options, cons
  */
 PRISM_EXPORTED_FUNCTION void pm_options_frozen_string_literal_set(pm_options_t *options, bool frozen_string_literal);
 
+/**
+ * Sets the command line option on the given options struct.
+ *
+ * @param options The options struct to set the command line option on.
+ * @param command_line The command_line value to set.
+ */
+PRISM_EXPORTED_FUNCTION void pm_options_command_line_set(pm_options_t *options, uint8_t command_line);
+
 /**
  * Set the version option on the given options struct by parsing the given
  * string. If the string contains an invalid option, this returns false.
@@ -129,8 +199,9 @@ PRISM_EXPORTED_FUNCTION bool pm_options_version_set(pm_options_t *options, const
  *
  * @param options The options struct to initialize the scopes array on.
  * @param scopes_count The number of scopes to allocate.
+ * @return Whether or not the scopes array was initialized successfully.
  */
-PRISM_EXPORTED_FUNCTION void pm_options_scopes_init(pm_options_t *options, size_t scopes_count);
+PRISM_EXPORTED_FUNCTION bool pm_options_scopes_init(pm_options_t *options, size_t scopes_count);
 
 /**
  * Return a pointer to the scope at the given index within the given options.
@@ -147,8 +218,9 @@ PRISM_EXPORTED_FUNCTION const pm_options_scope_t * pm_options_scope_get(const pm
  *
  * @param scope The scope struct to initialize.
  * @param locals_count The number of locals to allocate.
+ * @return Whether or not the scope was initialized successfully.
  */
-PRISM_EXPORTED_FUNCTION void pm_options_scope_init(pm_options_scope_t *scope, size_t locals_count);
+PRISM_EXPORTED_FUNCTION bool pm_options_scope_init(pm_options_scope_t *scope, size_t locals_count);
 
 /**
  * Return a pointer to the local at the given index within the given scope.
@@ -184,7 +256,10 @@ PRISM_EXPORTED_FUNCTION void pm_options_free(pm_options_t *options);
  * | `4`     | the length the encoding    |
  * | ...     | the encoding bytes         |
  * | `1`     | frozen string literal      |
- * | `1`     | suppress warnings          |
+ * | `1`     | -p command line option     |
+ * | `1`     | -n command line option     |
+ * | `1`     | -l command line option     |
+ * | `1`     | -a command line option     |
  * | `1`     | the version                |
  * | `4`     | the number of scopes       |
  * | ...     | the scopes                 |
@@ -196,14 +271,14 @@ PRISM_EXPORTED_FUNCTION void pm_options_free(pm_options_t *options);
  * | `0`   | use the latest version of prism |
  * | `1`   | use the version of prism that is vendored in CRuby 3.3.0 |
  *
- * Each scope is layed out as follows:
+ * Each scope is laid out as follows:
  *
  * | # bytes | field                      |
  * | ------- | -------------------------- |
  * | `4`     | the number of locals       |
  * | ...     | the locals                 |
  *
- * Each local is layed out as follows:
+ * Each local is laid out as follows:
  *
  * | # bytes | field                      |
  * | ------- | -------------------------- |