ruby_tree_sitter 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7447395b7231af234e93a7cdaa245beb48e72b41121350365d71123ae170baa5
-  data.tar.gz: 16bdb9be8c40402fcd135a177802108d70eb6c504541e045917af2c2045a109d
+  metadata.gz: 76f6accef62b96e6e67a815317815eee260d79c439e2efad49d2f235329d4b8e
+  data.tar.gz: 4affeaa090844fd467042247444f6cfdf5f98e63bc79e11cd8ff6b23ffac0795
 SHA512:
-  metadata.gz: 80f1ba5a83de868997ebe8cb3308f5c5d1acc1ae6e4d18645446f2ebfff10884d27651749b013cff2e2f2aeefedaf26b51012fa490fdb26f6ebd4533b85f293c
-  data.tar.gz: 7387367fc5cc306f80be04607ae08be2fd0ca5913bb9463129547682230620449d9449fe67d898f208975c4c14ea0d72f0b7ae2c84c84ea1d78e8b84091e4db6
+  metadata.gz: f0e629b66d07a20f5a4d9b274f7a16ec1ca3b748d66548878b58e153129b158844674eb7d8d512781ba7ab2a56cf9b97213587aadf6e66e00a55e595eb263390
+  data.tar.gz: b648d4546b019f336b7e84a945d6741bfb6ae320525abf9300d288f8e6b84059f5f2b4ecfa199502e5eae638f41b816ccaeb50693e509ae9cbb81d4f04f7c0e5

data/README.md

@@ -1,6 +1,12 @@
 # Ruby tree-sitter bindings
 
-[![ci](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/ci.yml/badge.svg)](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/ci.yml) [![valgrind](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/valgrind.yml/badge.svg)](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/valgrind.yml) [![asan/ubsan](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/asan.yml/badge.svg)](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/asan.yml)
+[![docs](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/publish-docs.yml/badge.svg)](https://faveod.github.io/ruby-tree-sitter)
+[![rubygems.org](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/publish.yml/badge.svg)](https://rubygems.org/gems/ruby_tree_sitter)
+[![ci](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/ci.yml/badge.svg)](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/ci.yml)
+<!--
+[![valgrind](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/valgrind.yml/badge.svg)](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/valgrind.yml)
+[![asan/ubsan](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/asan.yml/badge.svg)](https://github.com/Faveod/ruby-tree-sitter/actions/workflows/asan.yml)
+-->
 
 Ruby bindings for [tree-sitter](https://github.com/tree-sitter/tree-sitter).
 
@@ -63,8 +69,7 @@ This gem is a binding for `tree-sitter`. It doesn't have a version of
 
 You must install `tree-sitter` and make sure that their dynamic library is
 accessible from `$PATH`, or build the gem with `--disable-sys-libs`, which will
-download the latest tagged `tree-sitter` and build against it (see [Build from
-source](docs/Contributing.md#build-from-source) .)
+download the latest tagged `tree-sitter` and build against it (see [Build from source](docs/Contributing.md#build-from-source) .)
 
 You can either install `tree-sitter` from source or through your go-to package manager.
 
@@ -133,8 +138,7 @@ bundle config set build.ruby_tree_sitter --disable-sys-libs
 If you don't want to install from `rubygems`, `git`, or if you don't want to
 compile on install, then download a native gem from this repository's
 [releases](https://github.com/Faveod/ruby-tree-sitter/releases), or you can
-compile it yourself (see [Build from
-source](docs/Contributing.md#build-from-source) .)
+compile it yourself (see [Build from source](docs/Contributing.md#build-from-source) .)
 
 In that case, you'd have to point your `Gemfile` to the `gem` as such:
 
@@ -171,7 +175,7 @@ See `examples` directory.
 
 ## Development
 
-See [`docs/README.md`](docs/Contributing.md).
+See [`docs/Contributing.md`](docs/Contributing.md).
 
 ## 🚧 👷‍♀️ Notes 👷 🚧
 
@@ -186,7 +190,7 @@ don't copy them left and right, and then expect them to work without
 `SEGFAULT`ing and creating a black-hole in your living-room.  Assume that you
 have to work locally with them. If you get a `SEGFAULT`, you can debug the
 native `C` code using `gdb`.  You can read more on `SEGFAULT`s
-[here](docs/SIGSEGV.md), and debugging [here](docs/Contributing.md#Debugging).
+[here](docs/SIGSEGV.md), and debugging [here](docs/Contributing#Debugging.md).
 
 That said, we do aim at providing an idiomatic `Ruby` interface.  It should also
 provide a _safer_ interface, where you don't have to worry about when and how

data/ext/tree_sitter/language.c

@@ -32,7 +32,7 @@ VALUE new_language(const TSLanguage *language) {
  * with this gem.
  *
  * @param name [String] the parser's name.
- * @param path [String] the parser's shared library (so, dylib) path on disk.
+ * @param path [String, Pathname] the parser's shared library (so, dylib) path on disk.
  *
  * @return [Language]
  */

data/ext/tree_sitter/logger.c

@@ -154,9 +154,9 @@ static void logger_initialize_stderr(logger_t *logger) {
  *
  * You can provide your proper backend. You have to make sure that it
  * exposes a +printf+, +puts+, or +write+ (lookup is done in that specific
- * order). {StringIO} is a perfect candidate.
+ * order). {::StringIO} is a perfect candidate.
  *
- * You can also provide a format ({String}) if your backend supports a +printf+.
+ * You can also provide a format ({::String}) if your backend supports a +printf+.
  *
  * @example
  *   backend = StringIO.new

data/ext/tree_sitter/node.c

@@ -166,14 +166,19 @@ static VALUE node_child_by_field_id(VALUE self, VALUE field_id) {
 /**
  * Get the node's child with the given field name.
  *
- * @param field_name [String]
+ * @param field_name [String, Symbol]
  *
  * @return [Node]
  */
 static VALUE node_child_by_field_name(VALUE self, VALUE field_name) {
-  const char *name = StringValuePtr(field_name);
-  uint32_t length = (uint32_t)RSTRING_LEN(field_name);
-  return new_node_by_val(ts_node_child_by_field_name(SELF, name, length));
+  if (Qtrue == rb_funcall(self, rb_intern("field?"), 1, field_name)) {
+    VALUE field_str = rb_funcall(field_name, rb_intern("to_s"), 0);
+    const char *name = StringValuePtr(field_str);
+    uint32_t length = (uint32_t)RSTRING_LEN(field_str);
+    return new_node_by_val(ts_node_child_by_field_name(SELF, name, length));
+  } else {
+    return Qnil;
+  }
 }
 
 /**

data/ext/tree_sitter/parser.c

@@ -208,7 +208,7 @@ static VALUE parser_set_logger(VALUE self, VALUE logger) {
  *    same arguments. Or you can start parsing from scratch by first calling
  *    {Parser#reset}.
  * 3. Parsing was cancelled using a cancellation flag that was set by an
- *    earlier call to {Parsert#cancellation_flag=}. You can resume parsing
+ *    earlier call to {Parser#cancellation_flag=}. You can resume parsing
  *    from where the parser left out by calling {Parser#parse} again with
  *    the same arguments.
  *

data/lib/tree_sitter/node.rb

@@ -13,28 +13,17 @@ module TreeSitter
         @fields << name.to_sym if name
       end
 
-      @fields
+      @fields.to_a
     end
 
+    # @param field [String, Symbol]
     def field?(field)
-      fields.include?(field)
+      fields.include?(field.to_sym)
     end
 
-    # FIXME: These APIs (`[]` and `fetch`) need absolute fixing.
-    # 1. The documentation with the table doesn't work.
-    # 1. The APIs are very confusing! Make them act similarly to Hash's
-    #    `fetch` and `[]`.
-    #    1. `[]` should take a single input and return nil if nothing found
-    #       (no exceptions).
-    #    1. `fetch` should should accept a single argument, potentially a
-    #       default, and raise exception if no default was provided.
-    #       Also allow for the `all:` kwarg.
-    #    1. `values_at` takes many arguments.
-    # And I don't think we can move to 1.0 without adressing them.
-    #
     # Access node's named children.
     #
-    # It's similar to {#fetch}, but differes in input type, return values, and
+    # It's similar to {#fetch}, but differs in input type, return values, and
     # the internal implementation.
     #
     # Both of these methods exist for separate use cases, but also because
@@ -60,15 +49,15 @@ module TreeSitter
     # @return [Node | Array<Node>]
     def [](*keys)
       case keys.length
-      when 0 then raise "#{self.class.name}##{__method__} requires a key."
+      when 0 then raise ArgumentError, "#{self.class.name}##{__method__} requires a key."
       when 1
         case k = keys.first
-        when Numeric then named_child(k)
+        when Integer then named_child(k)
         when String, Symbol
-          raise "Cannot find field #{k}" unless fields.include?(k.to_sym)
+          raise IndexError, "Cannot find field #{k}. Available: #{fields}" unless fields.include?(k.to_sym)
 
           child_by_field_name(k.to_s)
-        else raise <<~ERR
+        else raise ArgumentError, <<~ERR
           #{self.class.name}##{__method__} accepts Integer and returns named child at given index,
               or a (String | Symbol) and returns the child by given field name.
         ERR
@@ -139,7 +128,7 @@ module TreeSitter
 
     # Access node's named children.
     #
-    # It's similar to {#fetch}, but differes in input type, return values, and
+    # It's similar to {#[]}, but differs in input type, return values, and
     # the internal implementation.
     #
     # Both of these methods exist for separate use cases, but also because
@@ -159,39 +148,18 @@ module TreeSitter
     # uses         named_child                   | field_name_for_child
     #              child_by_field_name           |   via each_node
     #              ------------------------------+----------------------
-    # @param all [Boolean] If `true`, return an array of nodes for all the
-    # demanded keys, putting `nil` for missing ones.  If `false`, return the
-    # same array after calling `compact`. Defaults to `false`.
-    #
-    # See {#fetch_all}.
-    def fetch(*keys, all: false, **_kwargs)
-      dict = {}
-      keys.each.with_index do |k, i|
-        dict[k.to_s] = i
-      end
+    #
+    # See {#[]}.
+    def fetch(*keys)
+      keys = keys.map(&:to_s)
+      key_set = keys.to_set
+      fields = {}
+      each_field do |f, _c|
+        fields[f] = self[f] if key_set.delete(f)
 
-      res = {}
-      each_field do |f, c|
-        if dict.key?(f)
-          res[f] = c
-          dict.delete(f)
-        end
-        break if dict.empty?
+        break if key_set.empty?
       end
-
-      res = keys.uniq.map { |k| res[k.to_s] }
-      res = res.compact if !all
-      res
-    end
-
-    # Access all named children of a node, returning `nil` for missing ones.
-    #
-    # Equivalent to `fetch(…, all: true)`.
-    #
-    # See {#fetch}.
-    def fetch_all(*keys, **kwargs)
-      kwargs[:all] = true
-      fetch(*keys, **kwargs)
+      fields.values_at(*keys)
     end
   end
 end

data/lib/tree_sitter/version.rb

@@ -4,5 +4,5 @@ module TreeSitter
   # The version of the tree-sitter library.
   TREESITTER_VERSION = '0.22.6'
   # The current version of the gem.
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

data/lib/tree_stand/config.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 # typed: true
 
+require 'pathname'
+
 module TreeStand
   # Global configuration for the gem.
   # @api private
   class Config
     extend T::Sig
 
-    sig { returns(String) }
-    attr_accessor :parser_path
+    sig { returns(T.nilable(Pathname)) }
+    attr_reader :parser_path
+
+    def parser_path=(path)
+      @parser_path = Pathname(path)
+    end
   end
 end

data/lib/tree_stand/node.rb

@@ -11,16 +11,60 @@ module TreeStand
     extend Forwardable
     include Enumerable
 
+    # @!method changed?
+    #   @return [Boolean] true if a syntax node has been edited.
+    # @!method child_count
+    #   @return [Integer] the number of child nodes.
+    # @!method extra?
+    #   @return [Boolean] true if the node is *extra* (e.g. comments).
+    # @!method has_error?
+    #   @return [Boolean] true if the node is a syntax error or contains any syntax errors.
+    # @!method missing?
+    #   @return [Boolean] true if the parser inserted that node to recover from error.
+    # @!method named?
+    #   @return [Boolean] true if the node is not a literal in the grammar.
+    # @!method named_child_count
+    #   @return [Integer] the number of *named* children.
     # @!method type
     #   @return [Symbol] the type of the node in the tree-sitter grammar.
     # @!method error?
     #   @return [bool] true if the node is an error node.
     def_delegators(
       :@ts_node,
-      :type,
+      :changed?,
+      :child_count,
       :error?,
+      :extra?,
+      :has_error?,
+      :missing?,
+      :named?,
+      :named_child_count,
+      :type,
     )
 
+    # These are methods defined in {TreeStand::Node} but map to something
+    # in {TreeSitter::Node}, because we want a more idiomatic API.
+    THINLY_REMAPPED_METHODS = {
+      '[]': :[],
+      fetch: :fetch,
+      field: :child_by_field_name,
+      next: :next_sibling,
+      prev: :prev_sibling,
+      next_named: :next_named_sibling,
+      prev_named: :prev_named_sibling,
+      field_names: :fields,
+    }.freeze
+
+    # These are methods from {TreeSitter} that are thinly wrapped to create
+    # {TreeStand::Node} instead.
+    THINLY_WRAPPED_METHODS = (
+      %i[
+        child
+        named_child
+        parent
+      ] + THINLY_REMAPPED_METHODS.keys
+    ).freeze
+
     sig { returns(TreeStand::Tree) }
     attr_reader :tree
 
@@ -32,7 +76,6 @@ module TreeStand
     def initialize(tree, ts_node)
       @tree = tree
       @ts_node = ts_node
-      @fields = @ts_node.each_field.to_a.map(&:first)
     end
 
     # TreeSitter uses a `TreeSitter::Cursor` to iterate over matches by calling
@@ -131,6 +174,74 @@ module TreeStand
       enumerator
     end
 
+    # Enumerate named children.
+    # @example
+    #   node.text # => "3 * 4"
+    #
+    # @example Iterate over the child nodes
+    #   node.each_named do |child|
+    #     print child.text
+    #   end
+    #   # prints: 34
+    #
+    # @example Enumerable methods
+    #   node.each_named.map(&:text) # => ["3", "4"]
+    #
+    # @yieldparam child [TreeStand::Node]
+    sig do
+      params(block: T.nilable(T.proc.params(node: TreeStand::Node).returns(BasicObject)))
+        .returns(T::Enumerator[TreeStand::Node])
+    end
+    def each_named(&block)
+      enumerator = Enumerator.new do |yielder|
+        @ts_node.each_named do |child|
+          yielder << TreeStand::Node.new(@tree, child)
+        end
+      end
+      enumerator.each(&block) if block_given?
+      enumerator
+    end
+
+    # Iterate of (field, child).
+    #
+    # @example
+    #   node.text # => "3 * 4"
+    #
+    # @example Iterate over the child nodes
+    #   node.each_field do |field, child|
+    #     puts "#{field}: #{child.text}"
+    #   end
+    #   # prints:
+    #   #  left: 3
+    #   #  right: 4
+    #
+    # @example Enumerable methods
+    #   node.each_field.map { |f, c| "#{f}: #{c}" } # => ["left: 3", "right: 4"]
+    #
+    # @yieldparam field [Symbol]
+    # @yieldparam child [TreeStand::Node]
+    sig do
+      params(block: T.nilable(T.proc.params(node: TreeStand::Node).returns(BasicObject)))
+        .returns(T::Enumerator[[Symbol, TreeStand::Node]])
+    end
+    def each_field(&block)
+      enumerator = Enumerator.new do |yielder|
+        @ts_node.each_field do |field, child|
+          yielder << [field.to_sym, TreeStand::Node.new(@tree, child)]
+        end
+      end
+      enumerator.each(&block) if block_given?
+      enumerator
+    end
+
+    # @example Enumerable methods
+    #   node.named.map(&:text) # => ["3", "4"]
+    alias_method :named, :each_named
+
+    # @example Enumerable methods
+    #   node.fields.map { |f, c| "#{f}: #{c}" } # => ["left: 3", "right: 4"]
+    alias_method :fields, :each_field
+
     # (see TreeStand::Visitors::TreeWalker)
     # Backed by {TreeStand::Visitors::TreeWalker}.
     #
@@ -154,15 +265,6 @@ module TreeStand
       enumerator
     end
 
-    # @example
-    #   node.text # => "4"
-    #   node.parent.text # => "3 * 4"
-    #   node.parent.parent.text # => "1 + 3 * 4"
-    sig { returns(TreeStand::Node) }
-    def parent
-      TreeStand::Node.new(@tree, @ts_node.parent)
-    end
-
     # @example
     #   node.text # => "3 * 4"
     #   node.to_a.map(&:text) # => ["3", "*", "4"]
@@ -174,7 +276,7 @@ module TreeStand
     # wraps the parent {TreeStand::Tree #tree} and has access to the source document.
     sig { returns(String) }
     def text
-      T.must(@tree.document[@ts_node.start_byte...@ts_node.end_byte])
+      T.must(@tree.document.byteslice(@ts_node.start_byte...@ts_node.end_byte))
     end
 
     # This class overrides the `method_missing` method to delegate to the
@@ -193,10 +295,20 @@ module TreeStand
     #
     # @overload method_missing(method_name, *args, &block)
     #   @raise [NoMethodError]
-    def method_missing(method, *args, &block)
-      return super unless @fields.include?(method.to_s)
-
-      TreeStand::Node.new(@tree, T.unsafe(@ts_node).public_send(method, *args, &block))
+    def method_missing(method, *args, **kwargs, &block)
+      if thinly_wrapped?(method)
+        from(
+          T.unsafe(@ts_node)
+            .public_send(
+              THINLY_REMAPPED_METHODS[method] || method,
+              *args,
+              **kwargs,
+              &block
+            ),
+        )
+      else
+        super
+      end
     end
 
     sig { params(other: Object).returns(T::Boolean) }
@@ -217,8 +329,31 @@ module TreeStand
 
     private
 
-    def respond_to_missing?(method, *)
-      @fields.include?(method.to_s) || super
+    def respond_to_missing?(method, *_args, **_kwargs)
+      thinly_wrapped?(method) || super
+    end
+
+    def thinly_wrapped?(method)
+      @ts_node.fields.include?(method) || THINLY_WRAPPED_METHODS.include?(method)
+    end
+
+    # FIXME: Make more generic if needed in other classes.
+
+    # 1 instance of {TreeStand} from a {TreeSitter} equivalent.
+    def from_a(node)
+      node.is_a?(TreeSitter::Node) ? TreeStand::Node.new(@tree, node) : node
+    end
+
+    # {TreeSitter} instance, or a collection ({Array, Hash})
+    def from(obj)
+      case obj
+      when Array
+        obj.map { |n| from(n) }
+      when Hash
+        obj.to_h { |k, v| [from(k), from(v)] }
+      else
+        from_a(obj)
+      end
     end
   end
 end

data/lib/tree_stand/parser.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 # typed: true
 
+require 'pathname'
+
 module TreeStand
   # Wrapper around the TreeSitter parser. It looks up the parser by filename in
   # the configured parsers directory.
@@ -14,6 +16,14 @@ module TreeStand
   #
   #   # Looks for a parser in `path/to/parser/folder/ruby.{so,dylib}`
   #   ruby_parser = TreeStand::Parser.new("ruby")
+  #
+  # If no {TreeStand::Config#parser_path} is setup, {TreeStand} will lookup in a
+  # set of default paths.  You can always override any configuration by passing
+  # the environment variable `TREE_SITTER_PARSERS` (colon-separated).
+  #
+  # @see language
+  # @see search_for_lib
+  # @see LIBDIRS
   class Parser
     extend T::Sig
 
@@ -23,14 +33,160 @@ module TreeStand
     sig { returns(TreeSitter::Parser) }
     attr_reader :ts_parser
 
+    # A colon-seprated list of paths pointing to directories that can contain parsers.
+    # Order matters.
+    # Takes precedence over default lookup paths.
+    ENV_PARSERS =
+      ENV['TREE_SITTER_PARSERS']
+        &.split(':')
+        &.map { |v| Pathname(v) }
+        .freeze
+
+    # The default paths we use to lookup parsers when no specific
+    # {TreeStand::Config#parser_path} is {nil}.
+    # Order matters.
+    LIBDIRS = [
+      'tree-sitter-parsers',
+      '/opt/local/lib',
+      '/opt/lib',
+      '/usr/local/lib',
+      '/usr/lib',
+    ].map { |p| Pathname(p) }.freeze
+
+    # The library directories we need to look into.
+    #
+    # @return [Array<Pathname>] the list of candidate places to use when searching for parsers.
+    #
+    # @see ENV_PARSERS
+    # @see LIBDIRS
+    sig { returns(T::Array[Pathname]) }
+    def self.lib_dirs = [
+      *ENV_PARSERS,
+      *(TreeStand.config.parser_path ? [TreeStand.config.parser_path] : LIBDIRS),
+    ].compact
+
+    # The platform-specific extension of the parser.
+    # @return [String] `dylib` or `so` for mac or linux.
+    sig { returns(String) }
+    def self.ext
+      case Gem::Platform.local.os
+      in   /darwin/ then 'dylib'
+      else               'so'
+      end
+    end
+
+    # Lookup a parser by name.
+    #
+    # Precedence:
+    # 1. `Env['TREE_SITTER_PARSERS]`
+    # 2. {TreeStand::Config#parser_path}
+    # 3. {LIBDIRS}
+    #
+    # If a {TreeStand::Config#parser_path} is `nil`, {LIBDIRS} is used.
+    # If a {TreeStand::Config#parser_path} is a {::Pathname}, {LIBDIRS} is ignored.
+    sig { params(name: String).returns(T.nilable(Pathname)) }
+    def self.search_for_lib(name)
+      files = [
+        name,
+        "tree-sitter-#{name}",
+        "libtree-sitter-#{name}",
+      ].map { |v| "#{v}.#{ext}" }
+
+      res = lib_dirs
+        .product(files)
+        .find do |dir, so|
+          path = dir / so
+          path = dir / name / so if !path.exist?
+          break path.expand_path if path.exist?
+        end
+      res.is_a?(Array) ? nil : res
+    end
+
+    # Generates a string message on where parser lookup happens.
+    #
+    # @return [String] A pretty message.
+    sig { returns(String) }
+    def self.search_lib_message
+      indent = 2
+      pretty = ->(arr) {
+        if arr
+          arr
+            .compact
+            .map { |v| "#{' ' * indent}#{v.expand_path}" }
+            .join("\n")
+        end
+      }
+      <<~MSG
+        From ENV['TREE_SITTER_PARSERS']:
+        #{pretty.call(ENV_PARSERS)}
+
+        From TreeStand.config.parser_path:
+        #{pretty.call([TreeStand.config.parser_path])}
+
+        From Defaults:
+        #{pretty.call(LIBDIRS)}
+      MSG
+    end
+
+    # Load a language from configuration or default lookup paths.
+    #
+    # @example Load java from default paths
+    #    # This will look for:
+    #    #
+    #    #   tree-sitter-parsers/(java/)?(libtree-sitter-)?java.{ext}
+    #    #   /opt/local/lib/(java/)?(libtree-sitter-)?java.{ext}
+    #    #   /opt/lib/(java/)?(libtree-sitter-)?java.{ext}
+    #    #   /usr/local/lib/(java/)?(libtree-sitter-)?java.{ext}
+    #    #   /usr/lib/(java/)?(libtree-sitter-)?java.{ext}
+    #    #
+    #    java = TreeStand::Parser.language('java')
+    #
+    # @example Load java from a configured path
+    #    # This will look for:
+    #    #
+    #    #   /my/path/(java/)?(libtree-sitter-)?java.{ext}
+    #    #
+    #    TreeStand.config.parser_path = '/my/path'
+    #    java = TreeStand::Parser.language('java')
+    #
+    # @example Load java from environment variables
+    #    # This will look for:
+    #    #
+    #    #   /my/forced/env/path/(java/)?(libtree-sitter-)?java.{ext}
+    #    #   /my/path/(java/)?(libtree-sitter-)?java.{ext}
+    #    #
+    #    # … and the same works for the default paths if `TreeStand.config.parser_path`
+    #    # was `nil`
+    #    ENV['TREE_SITTER_PARSERS'] = '/my/forced/env/path'
+    #    TreeStand.config.parser_path = '/my/path'
+    #    java = TreeStand::Parser.language('java')
+    #
+    # @param name [String] the name of the parser.
+    #   This name is used to load the symbol from the compiled parser, replacing `-` with `_`.
+    # @return [TreeSitter:language] a language object to use in your parsers.
+    # @raise [RuntimeError] if the parser was not found.
+    # @see search_for_lib
+    sig { params(name: String).returns(TreeSitter::Language) }
+    def self.language(name)
+      lib = search_for_lib(name)
+
+      if lib.nil?
+        raise <<~MSG
+          Failed to load a parser for #{name}.
+
+          #{search_lib_message}
+        MSG
+      end
+
+      # We know that the bindings will accept `lib`, but I don't know how to tell sorbet
+      # the types in ext/tree_sitter where `load` is defined.
+      TreeSitter::Language.load(name.gsub(/-/, '_'), T.unsafe(lib))
+    end
+
     # @param language [String]
     sig { params(language: String).void }
     def initialize(language)
-      @language_string = language
-      @ts_language = TreeSitter::Language.load(
-        language,
-        "#{TreeStand.config.parser_path}/#{language}.so",
-      )
+      @ts_language = Parser.language(language)
       @ts_parser = TreeSitter::Parser.new.tap do |parser|
         parser.language = @ts_language
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_tree_sitter
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Firas al-Khalil
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-10 00:00:00.000000000 Z
+date: 2024-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime