syntax_tree 3.6.3 → 4.0.0

data/lib/syntax_tree/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SyntaxTree
-  VERSION = "3.6.3"
+  VERSION = "4.0.0"
 end

data/lib/syntax_tree/visitor/environment.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module SyntaxTree
+  # The environment class is used to keep track of local variables and arguments
+  # inside a particular scope
+  class Environment
+    # [Array[Local]] The local variables and arguments defined in this
+    # environment
+    attr_reader :locals
+
+    # This class tracks the occurrences of a local variable or argument
+    class Local
+      # [Symbol] The type of the local (e.g. :argument, :variable)
+      attr_reader :type
+
+      # [Array[Location]] The locations of all definitions and assignments of
+      # this local
+      attr_reader :definitions
+
+      # [Array[Location]] The locations of all usages of this local
+      attr_reader :usages
+
+      #   initialize: (Symbol type) -> void
+      def initialize(type)
+        @type = type
+        @definitions = []
+        @usages = []
+      end
+
+      #   add_definition: (Location location) -> void
+      def add_definition(location)
+        @definitions << location
+      end
+
+      #   add_usage: (Location location) -> void
+      def add_usage(location)
+        @usages << location
+      end
+    end
+
+    #   initialize: (Environment | nil parent) -> void
+    def initialize(parent = nil)
+      @locals = {}
+      @parent = parent
+    end
+
+    # Adding a local definition will either insert a new entry in the locals
+    # hash or append a new definition location to an existing local. Notice that
+    # it's not possible to change the type of a local after it has been
+    # registered
+    #   add_local_definition: (Ident | Label identifier, Symbol type) -> void
+    def add_local_definition(identifier, type)
+      name = identifier.value.delete_suffix(":")
+
+      @locals[name] ||= Local.new(type)
+      @locals[name].add_definition(identifier.location)
+    end
+
+    # Adding a local usage will either insert a new entry in the locals
+    # hash or append a new usage location to an existing local. Notice that
+    # it's not possible to change the type of a local after it has been
+    # registered
+    #   add_local_usage: (Ident | Label identifier, Symbol type) -> void
+    def add_local_usage(identifier, type)
+      name = identifier.value.delete_suffix(":")
+
+      @locals[name] ||= Local.new(type)
+      @locals[name].add_usage(identifier.location)
+    end
+
+    # Try to find the local given its name in this environment or any of its
+    # parents
+    #   find_local: (String name) -> Local | nil
+    def find_local(name)
+      local = @locals[name]
+      return local unless local.nil?
+
+      @parent&.find_local(name)
+    end
+  end
+end

data/lib/syntax_tree/visitor/with_environment.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module SyntaxTree
+  # WithEnvironment is a module intended to be included in classes inheriting
+  # from Visitor. The module overrides a few visit methods to automatically keep
+  # track of local variables and arguments defined in the current environment.
+  # Example usage:
+  #   class MyVisitor < Visitor
+  #     include WithEnvironment
+  #
+  #     def visit_ident(node)
+  #       # Check if we're visiting an identifier for an argument, a local
+  #       variable or something else
+  #       local = current_environment.find_local(node)
+  #
+  #       if local.type == :argument
+  #         # handle identifiers for arguments
+  #       elsif local.type == :variable
+  #         # handle identifiers for variables
+  #       else
+  #         # handle other identifiers, such as method names
+  #       end
+  #   end
+  module WithEnvironment
+    def current_environment
+      @current_environment ||= Environment.new
+    end
+
+    def with_new_environment
+      previous_environment = @current_environment
+      @current_environment = Environment.new(previous_environment)
+      yield
+    ensure
+      @current_environment = previous_environment
+    end
+
+    # Visits for nodes that create new environments, such as classes, modules
+    # and method definitions
+    def visit_class(node)
+      with_new_environment { super }
+    end
+
+    def visit_module(node)
+      with_new_environment { super }
+    end
+
+    def visit_method_add_block(node)
+      with_new_environment { super }
+    end
+
+    def visit_def(node)
+      with_new_environment { super }
+    end
+
+    def visit_defs(node)
+      with_new_environment { super }
+    end
+
+    def visit_def_endless(node)
+      with_new_environment { super }
+    end
+
+    # Visit for keeping track of local arguments, such as method and block
+    # arguments
+    def visit_params(node)
+      node.requireds.each do |param|
+        @current_environment.add_local_definition(param, :argument)
+      end
+
+      node.posts.each do |param|
+        @current_environment.add_local_definition(param, :argument)
+      end
+
+      node.keywords.each do |param|
+        @current_environment.add_local_definition(param.first, :argument)
+      end
+
+      node.optionals.each do |param|
+        @current_environment.add_local_definition(param.first, :argument)
+      end
+
+      super
+    end
+
+    def visit_rest_param(node)
+      name = node.name
+      @current_environment.add_local_definition(name, :argument) if name
+
+      super
+    end
+
+    def visit_kwrest_param(node)
+      name = node.name
+      @current_environment.add_local_definition(name, :argument) if name
+
+      super
+    end
+
+    def visit_blockarg(node)
+      name = node.name
+      @current_environment.add_local_definition(name, :argument) if name
+
+      super
+    end
+
+    # Visit for keeping track of local variable definitions
+    def visit_var_field(node)
+      value = node.value
+
+      if value.is_a?(SyntaxTree::Ident)
+        @current_environment.add_local_definition(value, :variable)
+      end
+
+      super
+    end
+
+    alias visit_pinned_var_ref visit_var_field
+
+    # Visits for keeping track of variable and argument usages
+    def visit_aref_field(node)
+      name = node.collection.value
+      @current_environment.add_local_usage(name, :variable) if name
+
+      super
+    end
+
+    def visit_var_ref(node)
+      value = node.value
+
+      if value.is_a?(SyntaxTree::Ident)
+        definition = @current_environment.find_local(value.value)
+
+        if definition
+          @current_environment.add_local_usage(value, definition.type)
+        end
+      end
+
+      super
+    end
+  end
+end

data/lib/syntax_tree.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "delegate"
 require "etc"
 require "json"
 require "pp"
@@ -10,7 +9,6 @@ require "stringio"
 
 require_relative "syntax_tree/formatter"
 require_relative "syntax_tree/node"
-require_relative "syntax_tree/parser"
 require_relative "syntax_tree/version"
 
 require_relative "syntax_tree/basic_visitor"
@@ -19,6 +17,20 @@ require_relative "syntax_tree/visitor/field_visitor"
 require_relative "syntax_tree/visitor/json_visitor"
 require_relative "syntax_tree/visitor/match_visitor"
 require_relative "syntax_tree/visitor/pretty_print_visitor"
+require_relative "syntax_tree/visitor/environment"
+require_relative "syntax_tree/visitor/with_environment"
+
+require_relative "syntax_tree/parser"
+
+# We rely on Symbol#name being available, which is only available in Ruby 3.0+.
+# In case we're running on an older Ruby version, we polyfill it here.
+unless :+.respond_to?(:name)
+  class Symbol # rubocop:disable Style/Documentation
+    def name
+      to_s.freeze
+    end
+  end
+end
 
 # Syntax Tree is a suite of tools built on top of the internal CRuby parser. It
 # provides the ability to generate a syntax tree from source, as well as the

data/syntax_tree.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = %w[lib]
 
-  spec.add_dependency "prettier_print"
+  spec.add_dependency "prettier_print", ">= 1.0.0"
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "minitest"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: syntax_tree
 version: !ruby/object:Gem::Version
-  version: 3.6.3
+  version: 4.0.0
 platform: ruby
 authors:
 - Kevin Newton
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-11 00:00:00.000000000 Z
+date: 2022-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prettier_print
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -137,10 +137,12 @@ files:
 - lib/syntax_tree/rake_tasks.rb
 - lib/syntax_tree/version.rb
 - lib/syntax_tree/visitor.rb
+- lib/syntax_tree/visitor/environment.rb
 - lib/syntax_tree/visitor/field_visitor.rb
 - lib/syntax_tree/visitor/json_visitor.rb
 - lib/syntax_tree/visitor/match_visitor.rb
 - lib/syntax_tree/visitor/pretty_print_visitor.rb
+- lib/syntax_tree/visitor/with_environment.rb
 - syntax_tree.gemspec
 homepage: https://github.com/kddnewton/syntax_tree
 licenses: