ruby_tree_sitter 1.10.0-x86_64-darwin → 1.11.0-x86_64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8c5144410762c39463ba56e6524acea04f11ae0eb634ed392d59523bcffdec7
-  data.tar.gz: c1b5ed8af53aa9e6d5869a13cbe85ff110f796157414976c0147b8a4811363b0
+  metadata.gz: bdc265f5dda9c4123b013602244d37e9c00da87535cee01297cb0c9c0e543107
+  data.tar.gz: 0a0dfc57b524ea7d9fef98982f48ea64fa5d3ceac325cfdff82eda8fcde06447
 SHA512:
-  metadata.gz: 804c1ac45131bc4c27feccd9394f393d918c185115dddce4a3d0e539154bbbbe8aeb158ff82afb2e90bd8e24f548041b10937bb7cd5f4862020dd188215ec133
-  data.tar.gz: b5eb50f2d06cc45c97a64ad4f258133232dcf52668dfa0be94b688f4511d1a3ffe0d54cab06256851ff86d6b3a7b56284e74d960fec6efd8852f69b35d86043c
+  metadata.gz: 68f29d8ae25d85c620e86400340361e4f53a56b8dcb4b60ef74baecbd6ec9165de1b9aec762a821eadc3b15460df5932fa416af1264bac0e96a8adff76fde78e
+  data.tar.gz: f35912cc08fa32058500b7cf935e22a2da112977ecdce12403887a97aa3ca1b89dbcb058af2f6cf5dd7842902581a5b709bfa88c84e5867e40eed7c37571c32c

data/README.md

@@ -175,6 +175,20 @@ You will have to install parsers yourself, either by:
    [Faveod/tree-sitter-parsers](https://github.com/Faveod/tree-sitter-parsers)
    which supports numerous architectures.
 
+### Utilities
+
+`ruby_tree_sitter` ships with some useful utility programs to help work with parsers & queries.
+
+#### `rbts`
+
+```sh
+$ rbts --source SOURCE --query QUERY --parser PARSER
+```
+
+Watches a source and a query file and prints the matches when one of the files are updated. Uses [entr](https://github.com/eradman/entr), if available, otherwise [watch(1)](https://man7.org/linux/man-pages/man1/watch.1.html) is used by default or if --watch is specified.
+
+See `rbts --help` for more information.
+
 ## Examples
 
 See `examples` directory.

data/exe/print_matches

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'tree_stand/cli'
+
+program = TreeStand::Cli::Options.new
+OptionParser.new do |parser|
+  program.define_options(parser)
+  parser.parse!(ARGV)
+end
+program.check!
+
+def main(program)
+  program.tree.query(program.query).each do |match|
+    pp match.transform_values(&:text)
+  end
+end
+
+main(program)

data/exe/rbts

@@ -0,0 +1,83 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'tree_stand/cli'
+
+BANNER = <<~BANNER
+  Usage: rbts --source SOURCE --query QUERY --parser PARSER
+
+      Watches a source and a query file and prints the matches when one of the
+      files are updated. Uses entr, if available, otherwise watch(1) is used by
+      default or if --watch is specified.
+
+      Check out the tree-sitter repository & documentation for information on how
+      to write S-expression queries.
+
+          Repo: https://github.com/tree-sitter/tree-sitter
+          Docs: https://tree-sitter.github.io/tree-sitter/using-parsers/queries
+
+      Example:
+
+          rbts --source tmp/rbts/code.rb \\
+            --query tmp/rbts/query.scm \\
+            --parser tmp/rbts/ruby.so
+BANNER
+
+program = TreeStand::Cli::Options.new
+OptionParser.new do |parser|
+  parser.banner = BANNER
+  parser.separator('')
+  program.define_options(parser)
+  parser.separator('')
+  parser.on_tail(
+    '-w',
+    '--watch',
+    "use watch(1) to continuously print matches, by default entr is used if it's available",
+    TrueClass,
+  ) do |watch|
+    program.watch = watch
+  end
+
+  parser.parse!(ARGV)
+end
+program.check!
+
+def print_matches = File.join(__dir__, 'print_matches')
+
+# ls -1 SOURCE QUERY |
+#   entr -c exe/print_matches
+#     --source SOURCE
+#     --query QUERY
+#     --parser PARSER
+def entr_cmd(source, query, parser)
+  [
+    'ls', '-1', source, query, '|',
+    'entr', '-c',
+    print_matches,
+    '--source', source,
+    '--query', query,
+    '--parser', parser
+  ].join(' ')
+end
+
+# watch 'exe/print_matches --source SOURCE --query QUERY --parser PARSER'
+def watch_cmd(source, query, parser)
+  [
+    'watch',
+    "'#{print_matches} --source #{source} --query #{query} --parser #{parser}'",
+  ].join(' ')
+end
+
+def main(program)
+  cmd = if !program.watch && system('which', 'entr')
+    entr_cmd(program.source_file, program.query_file, program.parser_file)
+  else
+    watch_cmd(program.source_file, program.query_file, program.parser_file)
+  end
+
+  program.logger.debug("Running `#{cmd}`")
+  exec(cmd)
+end
+
+main(program)

data/lib/tree_sitter/node.rb

@@ -56,7 +56,7 @@ module TreeSitter
         case k = keys.first
         when Integer then named_child(k)
         when String, Symbol
-          raise IndexError, "Cannot find field #{k}. Available: #{fields}" unless fields.include?(k.to_sym)
+          raise IndexError, "Cannot find field #{k.to_sym}. Available: #{fields.to_a}" unless fields.include?(k.to_sym)
 
           child_by_field_name(k.to_s)
         else raise ArgumentError, <<~ERR
@@ -163,5 +163,94 @@ module TreeSitter
       end
       fields.values_at(*keys)
     end
+
+    # Regex for line annotation extraction from sexpr with source.
+    #
+    # @!visibility private
+    LINE_ANNOTATION = /\0\{(.*?)\0\}/
+
+    # Pretty-prints the node's sexp.
+    #
+    # The default call to {to_s} or {to_string} calls tree-sitter's
+    # `ts_node_string`. It's displayed on a single line, so reading a rich node
+    # becomes tiresome.
+    #
+    # This provides a better sexpr where you can control the "screen" width to
+    # decide when to break.
+    #
+    # @param indent   [Integer]
+    #   indentation for nested nodes.
+    # @param width    [Integer]
+    #   the screen's width.
+    # @param source   [Nil|String]
+    #   display source on the margin if not `nil`.
+    # @param vertical [Nil|Boolean]
+    #   fit as much sexpr on a single line if `false`, else, go vertical.
+    #   This is always `true` if `source` is not `nil`.
+    #
+    # @return [String] the pretty-printed sexpr.
+    def sexpr(indent: 2, width: 120, source: nil, vertical: nil)
+      res =
+        sexpr_recur(
+          indent: indent,
+          width: width,
+          source: source,
+          vertical: !source.nil? || !!vertical,
+        ).output
+      return res if source.nil?
+
+      max_width = 0
+      res
+        .lines
+        .map { |line|
+          extracted = line.scan(LINE_ANNOTATION).flatten.first || ''
+          base = line.gsub(LINE_ANNOTATION, '').rstrip
+          max_width = [max_width, base.length].max
+          [base, extracted]
+        }
+        .map { |base, extracted|
+          ("%-#{max_width}s | %s" % [base, extracted]).rstrip
+        }
+        .join("\n")
+    end
+
+    # Helper function for {sexpr}.
+    #
+    # @!visibility private
+    def sexpr_recur(indent: 2, width: 120, out: nil, source: nil, vertical: false)
+      out ||= Oppen::Wadler.new(width: width)
+      out.group(indent) {
+        out.text "(#{type}"
+        if source.is_a?(String) && child_count.zero?
+          out.text "\0{#{source.byteslice(start_byte...end_byte)}\0}", width: 0
+        end
+        brk(out, vertical) if child_count.positive?
+        each.with_index do |child, index|
+          if field_name = field_name_for_child(index)
+            out.text "#{field_name}:"
+            out.group(indent) {
+              brk(out, vertical)
+              child.sexpr_recur(indent: indent, width: width, out: out, vertical: vertical, source: source)
+            }
+          else
+            child.sexpr_recur(indent: indent, width: width, out: out, vertical: vertical, source: source)
+          end
+          brk(out, vertical) if index < child_count - 1
+        end
+        out.text ')'
+      }
+      out
+    end
+
+    # Break helper
+    #
+    # !@visibility private
+    def brk(out, vertical)
+      if vertical
+        out.break
+      else
+        out.breakable
+      end
+    end
   end
 end

data/lib/tree_sitter/version.rb

@@ -2,7 +2,7 @@
 
 module TreeSitter
   # The version of the tree-sitter library.
-  TREESITTER_VERSION = '0.24.4'
+  TREESITTER_VERSION = '0.24.5'
   # The current version of the gem.
-  VERSION = '1.10.0'
+  VERSION = '1.11.0'
 end

data/lib/tree_sitter.rb

@@ -23,6 +23,8 @@ require 'tree_sitter/query_matches'
 require 'tree_sitter/query_predicate'
 require 'tree_sitter/text_predicate_capture'
 
+require 'oppen'
+
 # TreeSitter is a Ruby interface to the tree-sitter parsing library.
 module TreeSitter
   extend Mixins::Language

data/lib/tree_stand/cli/options.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+# typed: true
+
+module TreeStand
+  module Cli
+    # @!visibility private
+    class Options
+      attr_accessor :source_file, :query_file, :parser_file, :watch
+
+      attr_reader :logger, :progname
+
+      def initialize(progname = File.basename($PROGRAM_NAME))
+        @logger = Logger.new($stderr, level: T.unsafe(ENV.fetch('LOG_LEVEL', Logger::INFO)), progname: progname)
+        @progname = progname
+      end
+
+      # @!visibility private
+      def define_options(parser)
+        parser.on_tail('-v', '--verbose', 'Enable verbose logging') { logger.level -= 1 }
+
+        parser.separator('Required options:')
+        parser.on('-s', '--source SOURCE', 'The filepath to the source code to be parsed') do |filepath|
+          self.source_file = error_no_file(File.expand_path(filepath), "Source file not found: #{filepath}", 1)
+        end
+        parser.on('-q', '--query QUERY', 'The filepath to the query to be run against the source code') do |filepath|
+          self.query_file = error_no_file(File.expand_path(filepath), "Query file not found: #{filepath}", 2)
+        end
+        parser.on('-p', '--parser PARSER', 'The parser to use to parse the source code') do |filepath|
+          self.parser_file = error_no_file(File.expand_path(filepath), "Parser file not found: #{filepath}", 3)
+        end
+      end
+
+      # @!visibility private
+      def check!
+        error!('No source file provided, specify with --source', 4) unless source_file
+        error!('No query file provided, specify with --query', 5) unless query_file
+        error!('No parser file provided, specify with --parser', 6) unless parser_file
+
+        parser_path = File.dirname(parser_file)
+        config = TreeStand.config
+
+        TreeStand.configure do
+          config.parser_path = parser_path
+        end
+      end
+
+      # @!visibility private
+      def source = @source ||= File.read(source_file)
+      # @!visibility private
+      def query = @query ||= File.read(query_file)
+      # @!visibility private
+      def parser = @parser ||= TreeStand::Parser.new(File.extname(source_file).delete_prefix('.'))
+      # @!visibility private
+      def tree = @tree ||= parser.parse_string(source)
+
+      private
+
+      def error_no_file(filepath, message, code)
+        return filepath if File.exist?(filepath)
+
+        error!(message, code)
+      end
+
+      def error!(message, code = 1)
+        logger.error(message)
+        exit(code)
+      end
+    end
+  end
+end

data/lib/tree_stand/cli.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+# typed: true
+
+require 'logger'
+require 'optparse'
+require 'tree_stand'
+
+require 'tree_stand/cli/options'
+
+$stdout.sync = $stderr.sync = true
+
+module TreeStand
+  # @!visibility private
+  module Cli
+  end
+end

data/lib/tree_stand/node.rb

@@ -15,6 +15,8 @@ module TreeStand
     #   @return [Boolean] true if a syntax node has been edited.
     # @!method child_count
     #   @return [Integer] the number of child nodes.
+    # @!method error?
+    #   @return [bool] true if the node is an error node.
     # @!method extra?
     #   @return [Boolean] true if the node is *extra* (e.g. comments).
     # @!method has_error?
@@ -25,10 +27,10 @@ module TreeStand
     #   @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 sexpr
+    #   @return [String] a pretty-printed sexpr.
     # @!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,
       :changed?,
@@ -39,6 +41,7 @@ module TreeStand
       :missing?,
       :named?,
       :named_child_count,
+      :sexpr,
       :type,
     )
 
@@ -310,13 +313,10 @@ module TreeStand
       T.must(range == other.range && type == other.type && text == other.text)
     end
 
-    # (see TreeStand::Utils::Printer)
-    # Backed by {TreeStand::Utils::Printer}.
-    #
-    # @see TreeStand::Utils::Printer
+    # @see TreeSitter:Node::sexpr
     sig { params(pp: PP).void }
     def pretty_print(pp)
-      Utils::Printer.new(ralign: 80).print(self, io: pp.output)
+      pp.output << sexpr(source: text)
     end
 
     private

data/lib/tree_stand.rb

@@ -10,6 +10,8 @@ require 'zeitwerk'
 loader = Zeitwerk::Loader.for_gem
 loader.ignore("#{__dir__}/tree_sitter")
 loader.ignore("#{__dir__}/tree_sitter.rb")
+loader.ignore("#{__dir__}/tree_stand/cli")
+loader.ignore("#{__dir__}/tree_stand/cli.rb")
 loader.setup
 
 # TreeStand is a high-level Ruby wrapper for {https://tree-sitter.github.io/tree-sitter tree-sitter} bindings. It makes

data/tree_sitter.gemspec

@@ -6,7 +6,7 @@ $LOAD_PATH.unshift(lib) if !$LOAD_PATH.include?(lib)
 require 'tree_sitter/version'
 
 Gem::Specification.new do |spec|
-  spec.required_ruby_version = '>= 3.0'
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.0.0')
 
   spec.authors       = ['Firas al-Khalil', 'Derek Stride']
   spec.email         = ['firasalkhalil@gmail.com', 'derek@stride.host']
@@ -27,8 +27,11 @@ Gem::Specification.new do |spec|
   spec.files         = %w[LICENSE README.md tree_sitter.gemspec]
   spec.files        += Dir.glob('ext/**/*.{c,h,rb}')
   spec.files        += Dir.glob('lib/**/*.rb')
+  spec.bindir        = 'exe'
+  spec.executables  << 'rbts' << 'print_matches'
   spec.require_paths = ['lib']
 
+  spec.add_dependency 'oppen', '0.9.8'
   spec.add_dependency 'sorbet-runtime'
   spec.add_dependency 'zeitwerk'
 end

metadata

@@ -1,16 +1,30 @@
 --- !ruby/object:Gem::Specification
 name: ruby_tree_sitter
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.11.0
 platform: x86_64-darwin
 authors:
 - Firas al-Khalil
 - Derek Stride
 autorequire: 
-bindir: bin
+bindir: exe
 cert_chain: []
-date: 2024-12-10 00:00:00.000000000 Z
+date: 2025-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: oppen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.9.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.9.8
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
   requirement: !ruby/object:Gem::Requirement
@@ -43,12 +57,16 @@ description:
 email:
 - firasalkhalil@gmail.com
 - derek@stride.host
-executables: []
+executables:
+- rbts
+- print_matches
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- exe/print_matches
+- exe/rbts
 - ext/tree_sitter/encoding.c
 - ext/tree_sitter/extconf.rb
 - ext/tree_sitter/input.c
@@ -77,7 +95,7 @@ files:
 - lib/tree_sitter/3.0/tree_sitter.bundle
 - lib/tree_sitter/3.1/tree_sitter.bundle
 - lib/tree_sitter/3.2/tree_sitter.bundle
-- lib/tree_sitter/3.3/tree_sitter.bundle
+- lib/tree_sitter/3.4/tree_sitter.bundle
 - lib/tree_sitter/error.rb
 - lib/tree_sitter/helpers.rb
 - lib/tree_sitter/mixins/language.rb
@@ -93,12 +111,13 @@ files:
 - lib/tree_stand.rb
 - lib/tree_stand/ast_modifier.rb
 - lib/tree_stand/breadth_first_visitor.rb
+- lib/tree_stand/cli.rb
+- lib/tree_stand/cli/options.rb
 - lib/tree_stand/config.rb
 - lib/tree_stand/node.rb
 - lib/tree_stand/parser.rb
 - lib/tree_stand/range.rb
 - lib/tree_stand/tree.rb
-- lib/tree_stand/utils/printer.rb
 - lib/tree_stand/version.rb
 - lib/tree_stand/visitor.rb
 - lib/tree_stand/visitors/tree_walker.rb
@@ -122,7 +141,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '3.0'
   - - "<"
     - !ruby/object:Gem::Version
-      version: 3.4.dev
+      version: 3.5.dev
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/tree_stand/utils/printer.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-# typed: true
-
-module TreeStand
-  # A collection of useful methods for working with syntax trees.
-  module Utils
-    # Used to {TreeStand::Node#pretty_print pretty-print} the node.
-    #
-    # @example
-    #   pp node
-    #   # (expression
-    #   #  (sum
-    #   #   left: (number)              | 1
-    #   #   ("+")                       | +
-    #   #   right: (variable)))         | x
-    class Printer
-      extend T::Sig
-
-      # @param ralign the right alignment for the text column.
-      sig { params(ralign: Integer).void }
-      def initialize(ralign:)
-        @ralign = ralign
-      end
-
-      # (see TreeStand::Utils::Printer)
-      sig { params(node: TreeStand::Node, io: T.any(IO, StringIO, String)).returns(T.any(IO, StringIO, String)) }
-      def print(node, io: StringIO.new)
-        lines = pretty_output_lines(node)
-
-        lines.each do |line|
-          if line.text.empty?
-            io << line.sexpr << "\n"
-            next
-          end
-
-          io << "#{line.sexpr}#{' ' * [(@ralign - line.sexpr.size), 0].max}| #{line.text}\n"
-        end
-
-        io
-      end
-
-      private
-
-      Line = Struct.new(:sexpr, :text)
-      private_constant :Line
-
-      def pretty_output_lines(node, prefix: '', depth: 0)
-        indent = ' ' * depth
-        ts_node = node.ts_node
-        if indent.size + prefix.size + ts_node.to_s.size < @ralign || ts_node.child_count.zero?
-          return [Line.new("#{indent}#{prefix}#{ts_node}", node.text)]
-        end
-
-        lines = T.let([Line.new("#{indent}#{prefix}(#{ts_node.type}", '')], T::Array[Line])
-
-        node.each.with_index do |child, index|
-          lines += if field_name = ts_node.field_name_for_child(index)
-            pretty_output_lines(
-              child,
-              prefix: "#{field_name}: ",
-              depth: depth + 1,
-            )
-          else
-            pretty_output_lines(child, depth: depth + 1)
-          end
-        end
-
-        T.must(lines.last).sexpr << ')'
-        lines
-      end
-    end
-  end
-end