prism 2.0.0.rc1-arm64-darwin

data/sig/generated/prism/pattern.rbs

@@ -0,0 +1,156 @@
+# Generated from lib/prism/pattern.rb with RBS::Inline
+
+module Prism
+  # A pattern is an object that wraps a Ruby pattern matching expression. The
+  # expression would normally be passed to an `in` clause within a `case`
+  # expression or a rightward assignment expression. For example, in the
+  # following snippet:
+  #
+  #     case node
+  #     in ConstantPathNode[ConstantReadNode[name: :Prism], ConstantReadNode[name: :Pattern]]
+  #     end
+  #
+  # the pattern is the <tt>ConstantPathNode[...]</tt> expression.
+  #
+  # The pattern gets compiled into an object that responds to #call by running
+  # the #compile method. This method itself will run back through Prism to
+  # parse the expression into a tree, then walk the tree to generate the
+  # necessary callable objects. For example, if you wanted to compile the
+  # expression above into a callable, you would:
+  #
+  #     callable = Prism::Pattern.new("ConstantPathNode[ConstantReadNode[name: :Prism], ConstantReadNode[name: :Pattern]]").compile
+  #     callable.call(node)
+  #
+  # The callable object returned by #compile is guaranteed to respond to #call
+  # with a single argument, which is the node to match against. It also is
+  # guaranteed to respond to #===, which means it itself can be used in a `case`
+  # expression, as in:
+  #
+  #     case node
+  #     when callable
+  #     end
+  #
+  # If the query given to the initializer cannot be compiled into a valid
+  # matcher (either because of a syntax error or because it is using syntax we
+  # do not yet support) then a Prism::Pattern::CompilationError will be
+  # raised.
+  class Pattern
+    # Raised when the query given to a pattern is either invalid Ruby syntax or
+    # is using syntax that we don't yet support.
+    class CompilationError < StandardError
+      # Create a new CompilationError with the given representation of the node
+      # that caused the error.
+      #
+      # : (String repr) -> void
+      def initialize: (String repr) -> void
+    end
+
+    # The query that this pattern was initialized with.
+    attr_reader query: String
+
+    @compiled: Proc?
+
+    # Create a new pattern with the given query. The query should be a string
+    # containing a Ruby pattern matching expression.
+    #
+    # : (String query) -> void
+    def initialize: (String query) -> void
+
+    # Compile the query into a callable object that can be used to match against
+    # nodes.
+    #
+    # : () -> Proc
+    def compile: () -> Proc
+
+    # Scan the given node and all of its children for nodes that match the
+    # pattern. If a block is given, it will be called with each node that
+    # matches the pattern. If no block is given, an enumerator will be returned
+    # that will yield each node that matches the pattern.
+    #
+    # : (node root) -> Enumerator[node, void]
+    # : (node root) { (node) -> void } -> void
+    def scan: (node root) -> Enumerator[node, void]
+            | (node root) { (node) -> void } -> void
+
+    private
+
+    # Shortcut for combining two procs into one that returns true if both return
+    # true.
+    #
+    # : (Proc left, Proc right) -> Proc
+    def combine_and: (Proc left, Proc right) -> Proc
+
+    # Shortcut for combining two procs into one that returns true if either
+    # returns true.
+    #
+    # : (Proc left, Proc right) -> Proc
+    def combine_or: (Proc left, Proc right) -> Proc
+
+    # Raise an error because the given node is not supported. Note purposefully
+    # not typing this method since it is a no return method that Steep does not
+    # understand.
+    #
+    # : (node node) -> bot
+    def compile_error: (node node) -> bot
+
+    # in [foo, bar, baz]
+    #
+    # : (ArrayPatternNode node) -> Proc
+    def compile_array_pattern_node: (ArrayPatternNode node) -> Proc
+
+    # in foo | bar
+    #
+    # : (AlternationPatternNode node) -> Proc
+    def compile_alternation_pattern_node: (AlternationPatternNode node) -> Proc
+
+    # in Prism::ConstantReadNode
+    #
+    # : (ConstantPathNode node) -> Proc
+    def compile_constant_path_node: (ConstantPathNode node) -> Proc
+
+    # in ConstantReadNode
+    # in String
+    #
+    # : (ConstantReadNode node) -> Proc
+    def compile_constant_read_node: (ConstantReadNode node) -> Proc
+
+    # Compile a name associated with a constant.
+    #
+    # : ((ConstantPathNode | ConstantReadNode) node, Symbol name) -> Proc
+    def compile_constant_name: (ConstantPathNode | ConstantReadNode node, Symbol name) -> Proc
+
+    # in InstanceVariableReadNode[name: Symbol]
+    # in { name: Symbol }
+    #
+    # : (HashPatternNode node) -> Proc
+    def compile_hash_pattern_node: (HashPatternNode node) -> Proc
+
+    # in nil
+    #
+    # : (NilNode node) -> Proc
+    def compile_nil_node: (NilNode node) -> Proc
+
+    # in /foo/
+    #
+    # : (RegularExpressionNode node) -> Proc
+    def compile_regular_expression_node: (RegularExpressionNode node) -> Proc
+
+    # in ""
+    # in "foo"
+    #
+    # : (StringNode node) -> Proc
+    def compile_string_node: (StringNode node) -> Proc
+
+    # in :+
+    # in :foo
+    #
+    # : (SymbolNode node) -> Proc
+    def compile_symbol_node: (SymbolNode node) -> Proc
+
+    # Compile any kind of node. Dispatch out to the individual compilation
+    # methods based on the type of node.
+    #
+    # : (node node) -> Proc
+    def compile_node: (node node) -> Proc
+  end
+end

data/sig/generated/prism/reflection.rbs

@@ -0,0 +1,101 @@
+# Generated from lib/prism/reflection.rb with RBS::Inline
+
+module Prism
+  # The Reflection module provides the ability to reflect on the structure of
+  # the syntax tree itself, as opposed to looking at a single syntax tree. This
+  # is useful in metaprogramming contexts.
+  module Reflection
+    # A field represents a single piece of data on a node. It is the base class
+    # for all other field types.
+    class Field
+      # The name of the field.
+      attr_reader name: Symbol
+
+      # Initializes the field with the given name.
+      #
+      # : (Symbol name) -> void
+      def initialize: (Symbol name) -> void
+    end
+
+    # A node field represents a single child node in the syntax tree. It
+    # resolves to a Prism::Node in Ruby.
+    class NodeField < Field
+    end
+
+    # An optional node field represents a single child node in the syntax tree
+    # that may or may not be present. It resolves to either a Prism::Node or nil
+    # in Ruby.
+    class OptionalNodeField < Field
+    end
+
+    # A node list field represents a list of child nodes in the syntax tree. It
+    # resolves to an array of Prism::Node instances in Ruby.
+    class NodeListField < Field
+    end
+
+    # A constant field represents a constant value on a node. Effectively, it
+    # represents an identifier found within the source. It resolves to a symbol
+    # in Ruby.
+    class ConstantField < Field
+    end
+
+    # An optional constant field represents a constant value on a node that may
+    # or may not be present. It resolves to either a symbol or nil in Ruby.
+    class OptionalConstantField < Field
+    end
+
+    # A constant list field represents a list of constant values on a node. It
+    # resolves to an array of symbols in Ruby.
+    class ConstantListField < Field
+    end
+
+    # A string field represents a string value on a node. It almost always
+    # represents the unescaped value of a string-like literal. It resolves to a
+    # string in Ruby.
+    class StringField < Field
+    end
+
+    # A location field represents the location of some part of the node in the
+    # source code. For example, the location of a keyword or an operator. It
+    # resolves to a Prism::Location in Ruby.
+    class LocationField < Field
+    end
+
+    # An optional location field represents the location of some part of the
+    # node in the source code that may or may not be present. It resolves to
+    # either a Prism::Location or nil in Ruby.
+    class OptionalLocationField < Field
+    end
+
+    # An integer field represents an integer value. It is used to represent the
+    # value of an integer literal, the depth of local variables, and the number
+    # of a numbered reference. It resolves to an Integer in Ruby.
+    class IntegerField < Field
+    end
+
+    # A float field represents a double-precision floating point value. It is
+    # used exclusively to represent the value of a floating point literal. It
+    # resolves to a Float in Ruby.
+    class FloatField < Field
+    end
+
+    # A flags field represents a bitset of flags on a node. It resolves to an
+    # integer in Ruby. Note that the flags cannot be accessed directly on the
+    # node because the integer is kept private. Instead, the various flags in
+    # the bitset should be accessed through their query methods.
+    class FlagsField < Field
+      # The names of the flags in the bitset.
+      attr_reader flags: Array[Symbol]
+
+      # Initializes the flags field with the given name and flags.
+      #
+      # : (Symbol name, Array[Symbol] flags) -> void
+      def initialize: (Symbol name, Array[Symbol] flags) -> void
+    end
+
+    # Returns the fields for the given node.
+    #
+    # : (singleton(Node) node) -> Array[Field]
+    def self.fields_for: (singleton(Node) node) -> Array[Field]
+  end
+end

data/sig/generated/prism/relocation.rbs

@@ -0,0 +1,428 @@
+# Generated from lib/prism/relocation.rb with RBS::Inline
+
+module Prism
+  # Prism parses deterministically for the same input. This provides a nice
+  # property that is exposed through the #node_id API on nodes. Effectively this
+  # means that for the same input, these values will remain consistent every
+  # time the source is parsed. This means we can reparse the source same with a
+  # #node_id value and find the exact same node again.
+  #
+  # The Relocation module provides an API around this property. It allows you to
+  # "save" nodes and locations using a minimal amount of memory (just the
+  # node_id and a field identifier) and then reify them later.
+  module Relocation
+    type entry_value = untyped
+
+    type entry_values = Hash[Symbol, entry_value]
+
+    interface _Value
+      def start_line: () -> Integer
+
+      def end_line: () -> Integer
+
+      def start_offset: () -> Integer
+
+      def end_offset: () -> Integer
+
+      def start_character_offset: () -> Integer
+
+      def end_character_offset: () -> Integer
+
+      def cached_start_code_units_offset: (_CodeUnitsCache cache) -> Integer
+
+      def cached_end_code_units_offset: (_CodeUnitsCache cache) -> Integer
+
+      def start_column: () -> Integer
+
+      def end_column: () -> Integer
+
+      def start_character_column: () -> Integer
+
+      def end_character_column: () -> Integer
+
+      def cached_start_code_units_column: (_CodeUnitsCache cache) -> Integer
+
+      def cached_end_code_units_column: (_CodeUnitsCache cache) -> Integer
+    end
+
+    interface _Field
+      def fields: (_Value value) -> entry_values
+    end
+
+    # An entry in a repository that will lazily reify its values when they are
+    # first accessed.
+    class Entry
+      # Raised if a value that could potentially be on an entry is missing
+      # because it was either not configured on the repository or it has not yet
+      # been fetched.
+      class MissingValueError < StandardError
+      end
+
+      @values: Hash[Symbol, untyped]?
+
+      @repository: Repository?
+
+      # Initialize a new entry with the given repository.
+      #
+      # : (Repository repository) -> void
+      def initialize: (Repository repository) -> void
+
+      # Fetch the filepath of the value.
+      #
+      # : () -> String
+      def filepath: () -> String
+
+      # Fetch the start line of the value.
+      #
+      # : () -> Integer
+      def start_line: () -> Integer
+
+      # Fetch the end line of the value.
+      #
+      # : () -> Integer
+      def end_line: () -> Integer
+
+      # Fetch the start byte offset of the value.
+      #
+      # : () -> Integer
+      def start_offset: () -> Integer
+
+      # Fetch the end byte offset of the value.
+      #
+      # : () -> Integer
+      def end_offset: () -> Integer
+
+      # Fetch the start character offset of the value.
+      #
+      # : () -> Integer
+      def start_character_offset: () -> Integer
+
+      # Fetch the end character offset of the value.
+      #
+      # : () -> Integer
+      def end_character_offset: () -> Integer
+
+      # Fetch the start code units offset of the value, for the encoding that
+      # was configured on the repository.
+      #
+      # : () -> Integer
+      def start_code_units_offset: () -> Integer
+
+      # Fetch the end code units offset of the value, for the encoding that was
+      # configured on the repository.
+      #
+      # : () -> Integer
+      def end_code_units_offset: () -> Integer
+
+      # Fetch the start byte column of the value.
+      #
+      # : () -> Integer
+      def start_column: () -> Integer
+
+      # Fetch the end byte column of the value.
+      #
+      # : () -> Integer
+      def end_column: () -> Integer
+
+      # Fetch the start character column of the value.
+      #
+      # : () -> Integer
+      def start_character_column: () -> Integer
+
+      # Fetch the end character column of the value.
+      #
+      # : () -> Integer
+      def end_character_column: () -> Integer
+
+      # Fetch the start code units column of the value, for the encoding that
+      # was configured on the repository.
+      #
+      # : () -> Integer
+      def start_code_units_column: () -> Integer
+
+      # Fetch the end code units column of the value, for the encoding that was
+      # configured on the repository.
+      #
+      # : () -> Integer
+      def end_code_units_column: () -> Integer
+
+      # Reify the values on this entry with the given values. This is an
+      # internal-only API that is called from the repository when it is time to
+      # reify the values.
+      #
+      # : (entry_values values) -> void
+      def reify!: (entry_values values) -> void
+
+      private
+
+      # Fetch a value from the entry, raising an error if it is missing.
+      #
+      # : (Symbol name) -> entry_value
+      def fetch_value: (Symbol name) -> entry_value
+
+      # Return the values from the repository, reifying them if necessary.
+      #
+      # : () -> entry_values
+      def values: () -> entry_values
+    end
+
+    # Represents the source of a repository that will be reparsed.
+    class Source
+      # The value that will need to be reparsed.
+      attr_reader value: untyped
+
+      # Initialize the source with the given value.
+      #
+      # : (untyped value) -> void
+      def initialize: (untyped value) -> void
+
+      # Reparse the value and return the parse result.
+      #
+      # : () -> ParseResult
+      def result: () -> ParseResult
+
+      # Create a code units cache for the given encoding.
+      #
+      # : (Encoding encoding) -> _CodeUnitsCache
+      def code_units_cache: (Encoding encoding) -> _CodeUnitsCache
+    end
+
+    # A source that is represented by a file path.
+    class SourceFilepath < Source
+      # Reparse the file and return the parse result.
+      #
+      # : () -> ParseResult
+      def result: () -> ParseResult
+    end
+
+    # A source that is represented by a string.
+    class SourceString < Source
+      # Reparse the string and return the parse result.
+      #
+      # : () -> ParseResult
+      def result: () -> ParseResult
+    end
+
+    # A field that represents the file path.
+    class FilepathField
+      # The file path that this field represents.
+      attr_reader value: String
+
+      # Initialize a new field with the given file path.
+      #
+      # : (String value) -> void
+      def initialize: (String value) -> void
+
+      # Fetch the file path.
+      #
+      # : (_Value _value) -> entry_values
+      def fields: (_Value _value) -> entry_values
+    end
+
+    # A field representing the start and end lines.
+    class LinesField
+      # Fetches the start and end line of a value.
+      #
+      # : (_Value value) -> entry_values
+      def fields: (_Value value) -> entry_values
+    end
+
+    # A field representing the start and end byte offsets.
+    class OffsetsField
+      # Fetches the start and end byte offset of a value.
+      #
+      # : (_Value value) -> entry_values
+      def fields: (_Value value) -> entry_values
+    end
+
+    # A field representing the start and end character offsets.
+    class CharacterOffsetsField
+      # Fetches the start and end character offset of a value.
+      #
+      # : (_Value value) -> entry_values
+      def fields: (_Value value) -> entry_values
+    end
+
+    # A field representing the start and end code unit offsets.
+    class CodeUnitOffsetsField
+      # A pointer to the repository object that is used for lazily creating a
+      # code units cache.
+      attr_reader repository: Repository
+
+      # The associated encoding for the code units.
+      attr_reader encoding: Encoding
+
+      @cache: _CodeUnitsCache?
+
+      # Initialize a new field with the associated repository and encoding.
+      #
+      # : (Repository repository, Encoding encoding) -> void
+      def initialize: (Repository repository, Encoding encoding) -> void
+
+      # Fetches the start and end code units offset of a value for a particular
+      # encoding.
+      #
+      # : (_Value value) -> entry_values
+      def fields: (_Value value) -> entry_values
+
+      private
+
+      # Lazily create a code units cache for the associated encoding.
+      #
+      # : () -> _CodeUnitsCache
+      def cache: () -> _CodeUnitsCache
+    end
+
+    # A field representing the start and end byte columns.
+    class ColumnsField
+      # Fetches the start and end byte column of a value.
+      #
+      # : (_Value value) -> entry_values
+      def fields: (_Value value) -> entry_values
+    end
+
+    # A field representing the start and end character columns.
+    class CharacterColumnsField
+      # Fetches the start and end character column of a value.
+      #
+      # : (_Value value) -> entry_values
+      def fields: (_Value value) -> entry_values
+    end
+
+    # A field representing the start and end code unit columns for a specific
+    # encoding.
+    class CodeUnitColumnsField
+      # The repository object that is used for lazily creating a code units
+      # cache.
+      attr_reader repository: Repository
+
+      # The associated encoding for the code units.
+      attr_reader encoding: Encoding
+
+      @cache: _CodeUnitsCache?
+
+      # Initialize a new field with the associated repository and encoding.
+      #
+      # : (Repository repository, Encoding encoding) -> void
+      def initialize: (Repository repository, Encoding encoding) -> void
+
+      # Fetches the start and end code units column of a value for a particular
+      # encoding.
+      #
+      # : (_Value value) -> entry_values
+      def fields: (_Value value) -> entry_values
+
+      private
+
+      # Lazily create a code units cache for the associated encoding.
+      #
+      # : () -> _CodeUnitsCache
+      def cache: () -> _CodeUnitsCache
+    end
+
+    # A repository is a configured collection of fields and a set of entries
+    # that knows how to reparse a source and reify the values.
+    class Repository
+      # Raised when multiple fields of the same type are configured on the same
+      # repository.
+      class ConfigurationError < StandardError
+      end
+
+      # The source associated with this repository. This will be either a
+      # SourceFilepath (the most common use case) or a SourceString.
+      attr_reader source: Source
+
+      # The fields that have been configured on this repository.
+      attr_reader fields: Hash[Symbol, _Field]
+
+      # The entries that have been saved on this repository.
+      attr_reader entries: Hash[Integer, Hash[Symbol, Entry]]
+
+      # Initialize a new repository with the given source.
+      #
+      # : (Source source) -> void
+      def initialize: (Source source) -> void
+
+      # Create a code units cache for the given encoding from the source.
+      #
+      # : (Encoding encoding) -> _CodeUnitsCache
+      def code_units_cache: (Encoding encoding) -> _CodeUnitsCache
+
+      # Configure the filepath field for this repository and return self.
+      #
+      # : () -> self
+      def filepath: () -> self
+
+      # Configure the lines field for this repository and return self.
+      #
+      # : () -> self
+      def lines: () -> self
+
+      # Configure the offsets field for this repository and return self.
+      #
+      # : () -> self
+      def offsets: () -> self
+
+      # Configure the character offsets field for this repository and return
+      # self.
+      #
+      # : () -> self
+      def character_offsets: () -> self
+
+      # Configure the code unit offsets field for this repository for a specific
+      # encoding and return self.
+      #
+      # : (Encoding encoding) -> self
+      def code_unit_offsets: (Encoding encoding) -> self
+
+      # Configure the columns field for this repository and return self.
+      #
+      # : () -> self
+      def columns: () -> self
+
+      # Configure the character columns field for this repository and return
+      # self.
+      #
+      # : () -> self
+      def character_columns: () -> self
+
+      # Configure the code unit columns field for this repository for a specific
+      # encoding and return self.
+      #
+      # : (Encoding encoding) -> self
+      def code_unit_columns: (Encoding encoding) -> self
+
+      # This method is called from nodes and locations when they want to enter
+      # themselves into the repository. It it internal-only and meant to be
+      # called from the #save* APIs.
+      #
+      # : (Integer node_id, Symbol field_name) -> Entry
+      def enter: (Integer node_id, Symbol field_name) -> Entry
+
+      # This method is called from the entries in the repository when they need
+      # to reify their values. It is internal-only and meant to be called from
+      # the various value APIs.
+      #
+      # : () -> void
+      def reify!: () -> void
+
+      private
+
+      # Append the given field to the repository and return the repository so
+      # that these calls can be chained.
+      #
+      # : (Symbol name, _Field) -> self
+      def field: (Symbol name, _Field) -> self
+    end
+
+    # Create a new repository for the given filepath.
+    #
+    # : (String value) -> Repository
+    def self.filepath: (String value) -> Repository
+
+    # Create a new repository for the given string.
+    #
+    # : (String value) -> Repository
+    def self.string: (String value) -> Repository
+  end
+end