prism 0.15.1 → 0.17.0

data/sig/prism_static.rbs

@@ -0,0 +1,123 @@
+module Prism
+  class ParseResult
+    def value: () -> ProgramNode
+    def comments: () -> Array[Comment]
+    def errors: () -> Array[ParseError]
+    def warnings: () -> Array[ParseWarning]
+    def source: () -> Source
+  end
+
+  class ParseError
+    def message: () -> String
+    def location: () -> Location
+  end
+
+  class ParseWarning
+    def message: () -> String
+    def location: () -> Location
+  end
+
+  class Node
+    def child_nodes: () -> Array[Node?]
+    def location: () -> Location
+    def slice: () -> String
+  end
+
+  class Comment
+    def location: () -> Location
+    def trailing?: () -> bool
+  end
+
+  class InlineComment < Comment
+    def trailing?: () -> bool
+  end
+
+  class EmbDocComment < Comment
+  end
+
+  class DATAComment < Comment
+  end
+
+  class Location
+    def initialize: (source: Source, start_offset: Integer, length: Integer) -> void
+    def slice: () -> String
+    def comments: () -> Array[Comment]
+    def copy: (**untyped) -> Location
+    def start_offset: () -> Integer
+    def end_offset: () -> Integer
+    def start_line: () -> Integer
+    def end_line: () -> Integer
+    def start_column: () -> Integer
+    def end_column: () -> Integer
+  end
+
+  class Source
+    attr_reader source: String
+    attr_reader start_line: Integer
+    attr_reader offsets: Array[Integer]
+
+    @source: String
+    @start_line: Integer
+    @offsets: Array[Integer]
+
+    def initialize: (source: String, start_line: Integer, offsets: Array[Integer]) -> void
+    def slice: (offset: Integer, length: Integer) -> String
+    def line: (value: Integer) -> Integer
+    def line_offset: (value: Integer) -> Integer
+    def column: (value: Integer) -> Integer
+  end
+
+  class Token
+    attr_reader type: untyped
+    attr_reader value: String
+    attr_reader location: Location
+
+    @type: untyped
+    @value: String
+    @location: Location
+
+    def initialize: (type: untyped, value: String, location: Location) -> void
+    def deconstruct_keys: (keys: untyped) -> untyped
+    def pretty_print: (q: untyped) -> untyped
+    def ==: (other: untyped) -> bool
+  end
+
+  class NodeInspector
+    attr_reader prefix: String
+    attr_reader output: String
+
+    @prefix: String
+    @output: String
+
+    def initialize: (prefix: String) -> void
+
+    # Appends a line to the output with the current prefix.
+    def <<: (line: String) -> void
+
+    # This generates a string that is used as the header of the inspect output
+    # for any given node.
+    def header: (node: Node) -> String
+
+    # Generates a string that represents a list of nodes. It handles properly
+    # using the box drawing characters to make the output look nice.
+    def list: (prefix: String, nodes: Array[Node]) -> String
+
+    # Generates a string that represents a location field on a node.
+    def location: (value: Location) -> String
+
+    # Generates a string that represents a child node.
+    def child_node: (node: Node, append: String) -> String
+
+    # Returns a new inspector that can be used to inspect a child node.
+    def child_inspector: (append: String) -> NodeInspector
+
+    # Returns the output as a string.
+    def to_str: () -> String
+  end
+
+  class BasicVisitor
+    def visit: (node: Node?) -> void
+    def visit_all: (nodes: Array[Node?]) -> void
+    def visit_child_nodes: (node: Node) -> void
+  end
+end

data/src/diagnostic.c

@@ -1,56 +1,55 @@
 #include "prism/diagnostic.h"
 
-/*
-  ## Message composition
-
-  When composing an error message, use sentence fragments.
-
-  Try describing the property of the code that caused the error, rather than the rule that is being
-  violated. It may help to use a fragment that completes a sentence beginning, "The parser
-  encountered (a) ...". If appropriate, add a description of the rule violation (or other helpful
-  context) after a semicolon.
-
-  For example:, instead of "Control escape sequence cannot be doubled", prefer:
-
-  > "Invalid control escape sequence; control cannot be repeated"
-
-  In some cases, where the failure is more general or syntax expectations are violated, it may make
-  more sense to use a fragment that completes a sentence beginning, "The parser ...".
-
-  For example:
-
-  > "Expected an expression after `(`"
-  > "Cannot parse the expression"
-
-
-  ## Message style guide
-
-  - Use articles like "a", "an", and "the" when appropriate.
-    - e.g., prefer "Cannot parse the expression" to "Cannot parse expression".
-  - Use the common name for tokens and nodes.
-    - e.g., prefer "keyword splat" to "assoc splat"
-    - e.g., prefer "embedded document" to "embdoc"
-  - Capitalize the initial word of the message.
-  - Use back ticks around token literals
-    - e.g., "Expected a `=>` between the hash key and value"
-  - Do not use `.` or other punctuation at the end of the message.
-  - Do not use contractions like "can't". Prefer "cannot" to "can not".
-  - For tokens that can have multiple meanings, reference the token and its meaning.
-    - e.g., "`*` splat argument" is clearer and more complete than "splat argument" or "`*` argument"
-
-
-  ## Error names (PM_ERR_*)
-
-  - When appropriate, prefer node name to token name.
-    - e.g., prefer "SPLAT" to "STAR" in the context of argument parsing.
-  - Prefer token name to common name.
-    - e.g., prefer "STAR" to "ASTERISK".
-  - Try to order the words in the name from more general to more specific,
-    - e.g., "INVALID_NUMBER_DECIMAL" is better than "DECIMAL_INVALID_NUMBER".
-    - When in doubt, look for similar patterns and name them so that they are grouped when lexically
-      sorted. See PM_ERR_ARGUMENT_NO_FORWARDING_* for an example.
-*/
-
+/**
+ * ## Message composition
+ *
+ * When composing an error message, use sentence fragments.
+ *
+ * Try describing the property of the code that caused the error, rather than the rule that is being
+ * violated. It may help to use a fragment that completes a sentence beginning, "The parser
+ * encountered (a) ...". If appropriate, add a description of the rule violation (or other helpful
+ * context) after a semicolon.
+ *
+ * For example:, instead of "Control escape sequence cannot be doubled", prefer:
+ *
+ * > "Invalid control escape sequence; control cannot be repeated"
+ *
+ * In some cases, where the failure is more general or syntax expectations are violated, it may make
+ * more sense to use a fragment that completes a sentence beginning, "The parser ...".
+ *
+ * For example:
+ *
+ * > "Expected an expression after `(`"
+ * > "Cannot parse the expression"
+ *
+ *
+ * ## Message style guide
+ *
+ * - Use articles like "a", "an", and "the" when appropriate.
+ *   - e.g., prefer "Cannot parse the expression" to "Cannot parse expression".
+ * - Use the common name for tokens and nodes.
+ *   - e.g., prefer "keyword splat" to "assoc splat"
+ *   - e.g., prefer "embedded document" to "embdoc"
+ * - Capitalize the initial word of the message.
+ * - Use back ticks around token literals
+ *   - e.g., "Expected a `=>` between the hash key and value"
+ * - Do not use `.` or other punctuation at the end of the message.
+ * - Do not use contractions like "can't". Prefer "cannot" to "can not".
+ * - For tokens that can have multiple meanings, reference the token and its meaning.
+ *   - e.g., "`*` splat argument" is clearer and more complete than "splat argument" or "`*` argument"
+ *
+ *
+ * ## Error names (PM_ERR_*)
+ *
+ * - When appropriate, prefer node name to token name.
+ *   - e.g., prefer "SPLAT" to "STAR" in the context of argument parsing.
+ * - Prefer token name to common name.
+ *   - e.g., prefer "STAR" to "ASTERISK".
+ * - Try to order the words in the name from more general to more specific,
+ *   - e.g., "INVALID_NUMBER_DECIMAL" is better than "DECIMAL_INVALID_NUMBER".
+ *   - When in doubt, look for similar patterns and name them so that they are grouped when lexically
+ *     sorted. See PM_ERR_ARGUMENT_NO_FORWARDING_* for an example.
+ */
 static const char* const diagnostic_messages[PM_DIAGNOSTIC_ID_LEN] = {
     [PM_ERR_ALIAS_ARGUMENT]                     = "Invalid argument being passed to `alias`; expected a bare word, symbol, constant, or global variable",
     [PM_ERR_AMPAMPEQ_MULTI_ASSIGN]              = "Unexpected `&&=` in a multiple assignment",
@@ -263,7 +262,9 @@ pm_diagnostic_message(pm_diagnostic_id_t diag_id) {
     return message;
 }
 
-// Append an error to the given list of diagnostic.
+/**
+ * Append an error to the given list of diagnostic.
+ */
 bool
 pm_diagnostic_list_append(pm_list_t *list, const uint8_t *start, const uint8_t *end, pm_diagnostic_id_t diag_id) {
     pm_diagnostic_t *diagnostic = (pm_diagnostic_t *) calloc(sizeof(pm_diagnostic_t), 1);
@@ -274,7 +275,9 @@ pm_diagnostic_list_append(pm_list_t *list, const uint8_t *start, const uint8_t *
     return true;
 }
 
-// Deallocate the internal state of the given diagnostic list.
+/**
+ * Deallocate the internal state of the given diagnostic list.
+ */
 void
 pm_diagnostic_list_free(pm_list_t *list) {
     pm_list_node_t *node, *next;

data/src/enc/pm_big5.c

@@ -42,6 +42,7 @@ pm_encoding_big5_isupper_char(const uint8_t *b, ptrdiff_t n) {
     }
 }
 
+/** Big5 encoding */
 pm_encoding_t pm_encoding_big5 = {
     .name = "big5",
     .char_width = pm_encoding_big5_char_width,

data/src/enc/pm_euc_jp.c

@@ -48,6 +48,7 @@ pm_encoding_euc_jp_isupper_char(const uint8_t *b, ptrdiff_t n) {
     }
 }
 
+/** EUC-JP encoding */
 pm_encoding_t pm_encoding_euc_jp = {
     .name = "euc-jp",
     .char_width = pm_encoding_euc_jp_char_width,

data/src/enc/pm_gbk.c

@@ -51,6 +51,7 @@ pm_encoding_gbk_isupper_char(const uint8_t *b, ptrdiff_t n) {
     }
 }
 
+/** GBK encoding */
 pm_encoding_t pm_encoding_gbk = {
     .name = "gbk",
     .char_width = pm_encoding_gbk_char_width,

data/src/enc/pm_shift_jis.c

@@ -46,6 +46,7 @@ pm_encoding_shift_jis_isupper_char(const uint8_t *b, ptrdiff_t n) {
     }
 }
 
+/** Shift_JIS encoding */
 pm_encoding_t pm_encoding_shift_jis = {
     .name = "shift_jis",
     .char_width = pm_encoding_shift_jis_char_width,