ruby-lint 0.0.2 → 0.0.3

data/lib/ruby-lint/iterator.rb

@@ -1,193 +1,253 @@
 module RubyLint
   ##
-  # {RubyLint::Iterator} is a class that can be used to iterate over the AST
-  # generated by {RubyLint::Parser} and execute callback methods for each
-  # encountered node. Basic usage is as following:
+  # The Iterator class provides the means to iterate over an AST generated by
+  # {RubyLint::Parser} using callback methods for the various node types
+  # generated by this parser.
   #
-  #     code = <<-CODE
-  #     [10, 20].each do |number|
-  #       puts number
-  #     end
-  #     CODE
-  #
-  #     parser   = RubyLint::Parser.new(code)
-  #     tokens   = parser.parse
-  #     iterator = RubyLint::Iterator.new
-  #
-  #     iterator.run(tokens)
+  # For each node type two events are called: one before and one after
+  # processing the node and all of its children. The names of these events are
+  # the following:
   #
-  # This particular example doesn't do anything but iterating over the nodes
-  # due to no callback classes being defined. How to add these classes is
-  # discussed below.
+  # * `on_X`
+  # * `after_X`
   #
-  # ## Callback Classes
+  # Here "X" is the name of the event. For example, when iterator an integer
+  # this would result in the event names `on_integer` and `after_integer`.
   #
-  # Without any custom callback classes the iterator class is fairly useless as
-  # it does nothing but iterate over all the nodes. These classes are defined
-  # as any ordinary class and are added to an interator instance using
-  # {RubyLint::Iterator#bind}. At the most basic level each callback class should
-  # have the following structure:
+  # These event names are used to call the corresponding callback methods if
+  # they exist. Each callback method takes a single argument: the node (an
+  # instance of {RubyLint::Node}) that belongs to the event.
   #
-  #     class MyCallback
-  #       attr_reader :options
+  # Creating iterator classes is done by extending this particular class and
+  # adding the needed methods to it:
   #
-  #       def initialize(report = nil, storage = {})
-  #         @report  = report
-  #         @storage = storage
+  #     class MyIterator < RubyLint::Iterator
+  #       def on_integer(node)
+  #         puts node.children[0]
   #       end
-  #     end
-  #
-  # The constructor method should take two parameters: the first one is used
-  # for storing a instance of {RubyLint::Report} (this parameter should be set to
-  # `nil` by default). The second parameter is a Hash containing custom data
-  # that is shared between callback classes bound to the same {RubyLint::Iterator}
-  # instance. This Hash can be used to share, for example, definitions defined
-  # in callback class #1 with callback class #2.
-  #
-  # To make this, as well as adding errors and such to a report easier your own
-  # classes can extend {RubyLint::Callback}:
-  #
-  #     class MyCallback < RubyLint::Callback
   #
+  #       def after_integer(node)
+  #         puts '---'
+  #       end
   #     end
   #
-  # To add your class to an iterator instance you'd run the following:
-  #
-  #     iterator = RubyLint::Iterator.new
+  # When used this particular iterator class would display the values of all
+  # integers it processes. After processing an integer it will display three
+  # dashes.
   #
-  #     iterator.bind(MyCallback)
+  # Each instance of a class that subclasses {RubyLint::Iterator} also has
+  # access to the instance variable `@options`. This instance variable is used
+  # to store certain information, such as the list of definitions for a block
+  # of Ruby code. The following two keys are set by default:
   #
-  # ## Callback Methods
+  # * `:definitions`: a set of Ruby definitions such as classes and methods.
+  # * `:report`: an instance of {RubyLint::Report} that can be used for adding
+  #   information about the analyzed code.
+  # * `:node_definitions`: a Hash that associates {RubyLint::Node} instances
+  #   with the corresponding scope.
   #
-  # When iterating over an AST the method {RubyLint::Iterator#iterator} calls two
-  # callback methods based on the event name stored in the token (in
-  # {RubyLint::Token::Token#event}):
+  # To make it easier to add data to a report sub classes can use the following
+  # three methods:
   #
-  # * `on_EVENT_NAME`
-  # * `after_EVENT_NAME`
+  # * error
+  # * info
+  # * warning
   #
-  # Where `EVENT_NAME` is the name of the event. For example, for strings this
-  # would result in the following methods being called:
-  #
-  # * `on_string`
-  # * `after_string`
-  #
-  # Note that the "after" callback is not executed until all child nodes have
-  # been processed.
-  #
-  # Each method should take a single parameter that contains details about the
-  # token that is currently being processed. Each token is an instance of
-  # {RubyLint::Token::Token} or one of its child classes.
-  #
-  # If you wanted to display the values of all strings in your console you'd
-  # write the following class:
-  #
-  #     class StringPrinter < RubyLint::Callback
-  #       def on_string(token)
-  #         puts token.value
-  #       end
-  #     end
+  # These methods take away some of the boilerplate that would otherwise be
+  # required to check for a report and add data to it if it's set.
   #
   class Iterator
     ##
-    # Array containing a set of instance specific callback objects.
+    # Hash containing the options that were set for the iterator.
     #
-    # @return [Array]
+    # @return [Hash]
     #
-    attr_reader :callbacks
+    attr_reader :options
 
     ##
-    # Returns the Hash that is used by callback classes to store arbitrary
-    # data.
+    # @param [Hash] options Hash containing custom options to set for the
+    #  iterator.
     #
-    # @return [Hash]
+    def initialize(options = {})
+      @options     = default_options.merge(options)
+      @definitions = []
+      @call_types  = []
+    end
+
+    ##
+    # Recursively processes the specified list of nodes.
     #
-    attr_reader :storage
+    # @param [RubyLint::Node] node A node and optionally a set of sub nodes to
+    #  iterate over.
+    #
+    def iterate(node)
+      return unless node.is_a?(Node)
+
+      before, after = callback_names(node)
+
+      execute_callback(before, node)
+
+      node.children.each do |child|
+        if child.is_a?(Array)
+          child.each { |c| iterate(c) }
+        else
+          iterate(child)
+        end
+      end
+
+      execute_callback(after, node)
+    end
+
+    protected
 
     ##
-    # Creates a new instance of the iterator class.
+    # Adds an error message to the report.
     #
-    # @param [RubyLint::Report|NilClass] report The report to use, set to `nil` by
-    #  default.
+    # @param [String] message The message to add.
+    # @param [RubyLint::Node] node The node for which to add the message.
     #
-    def initialize(report = nil)
-      @callbacks = []
-      @report    = report
-      @storage   = {}
+    def error(message, node)
+      add_message(:error, message, node)
     end
 
     ##
-    # Processes the entire AST for each callback class in sequence. For each
-    # callback class the method {RubyLint::Iterator#iterate} is called to process
-    # an *entire* AST before moving on to the next callback class.
+    # Adds a warning message to the report.
     #
-    # @param [#each] nodes An array of nodes to process.
+    # @see RubyLint::Callback#error
     #
-    def run(nodes)
-      @callbacks.each do |obj|
-        execute_callback(obj, :on_start)
+    def warning(message, node)
+      add_message(:warning, message, node)
+    end
 
-        iterate(obj, nodes)
+    ##
+    # Adds a regular informational message to the report.
+    #
+    # @see RubyLint::Callback#error
+    #
+    def info(message, node)
+      add_message(:info, message, node)
+    end
 
-        execute_callback(obj, :on_finish)
+    ##
+    # Adds a message of the given level.
+    #
+    # @param [Symbol] level
+    # @param [String] message
+    # @param [String] node
+    #
+    def add_message(level, message, node)
+      if has_report?
+        @options[:report].add(
+          level,
+          message,
+          node.line,
+          node.column,
+          node.file
+        )
       end
     end
 
     ##
-    # Processes an AST and calls callbacks methods for a specific callback
-    # object.
+    # Returns `true` if the current iterator has a report instance set.
     #
-    # @param [RubyLint::Callback] callback_obj The callback object on which to
-    #  invoke callback method.
-    # @param [#each] nodes An array (or a different object that responds to
-    #  `#each()`) that contains a set of tokens to process.
+    # @return [TrueClass|FalseClass]
     #
-    def iterate(callback_obj, nodes)
-      nodes.each do |node|
-        next unless node.is_a?(RubyLint::Token::Token)
-
-        event_name     = node.event.to_s
-        callback_name  = 'on_' + event_name
-        after_callback = 'after_' + event_name
+    def has_report?
+      return @options[:report].is_a?(Report)
+    end
 
-        execute_callback(callback_obj, callback_name, node)
+    ##
+    # Returns a definition list to use for the last segment in the constant
+    # path. If one of the segments is invalid `nil` is returned instead.
+    #
+    # @param [Array] path An array of nodes or definitions that make up the
+    #  constant path.
+    # @return [RubyLint::Definition::RubyObject|NilClass]
+    #
+    def resolve_definitions(path)
+      current = definitions
 
-        node.child_nodes.each do |child_nodes|
-          iterate(callback_obj, child_nodes) if child_nodes.respond_to?(:each)
+      path.each do |segment|
+        if segment.is_a?(Definition::RubyObject)
+          name = segment.name
+        else
+          name = segment.children[0]
         end
 
-        execute_callback(callback_obj, after_callback, node)
+        found = current.lookup(segment.type, name)
+        found ? current = found : return
       end
+
+      return current
     end
 
     ##
-    # Adds the specified class to the list of callback classes for this
-    # instance.
+    # Returns the call type to use for method calls.
     #
-    # @example
-    #  iterator = RubyLint::Iterator.new
+    # @return [Symbol]
     #
-    #  iterator.bind(CustomCallbackClass)
+    def call_type
+      return @call_types.empty? ? :instance_method : @call_types[-1]
+    end
+
+    ##
+    # Returns the current definition list to use.
     #
-    # @param [Class] callback_class The class to add.
+    # @return [RubyLint::Definition::RubyObject]
     #
-    def bind(callback_class)
-      @callbacks << callback_class.new(@report, @storage)
+    def definitions
+      return @definitions.empty? ? @options[:definitions] : @definitions[-1]
     end
 
-    private
+    protected
 
     ##
-    # Loops through all the bound callback classes and executes the specified
-    # callback method if it exists.
+    # Executes the specified callback method if it exists.
     #
-    # @param [RubyLint::Callback] obj The object on which to invoke the callback
-    #  method.
     # @param [String|Symbol] name The name of the callback method to execute.
     # @param [Array] args Arguments to pass to the callback method.
     #
-    def execute_callback(obj, name, *args)
-      obj.send(name, *args) if obj.respond_to?(name)
+    def execute_callback(name, *args)
+      send(name, *args) if respond_to?(name)
+    end
+
+    ##
+    # Returns an array containin the callback names for the specified node.
+    #
+    # @param [RubyLint::Node] node
+    # @return [Array]
+    #
+    def callback_names(node)
+      return [:"on_#{node.type}", :"after_#{node.type}"]
+    end
+
+    ##
+    # Associates a definitions object with a node of the AST.
+    #
+    # @param [RubyLint::Node] node
+    # @param [RubyLint::Definition::RubyObject] definitions
+    #
+    def associate_node_definition(node, definitions)
+      @options[:node_definitions][node] = definitions
+    end
+
+    ##
+    # Retrieves the definitions list associated to an AST node.
+    #
+    # @param [RubyLint::Node] node
+    # @return [RubyLint::Definition::RubyObject|NilClass]
+    #
+    def associated_definition(node)
+      return @options[:node_definitions][node]
+    end
+
+    ##
+    # Returns a Hash containing the default configuration options.
+    #
+    # @return [Hash]
+    #
+    def default_options
+      return {:node_definitions => {}}
     end
   end # Iterator
 end # RubyLint

data/lib/ruby-lint/node.rb

@@ -0,0 +1,107 @@
+module RubyLint
+  ##
+  # {RubyLint::Node} is a class that represents a single node in the AST of a
+  # Ruby program. It contains information such as the type, children, line
+  # number and column number.
+  #
+  class Node < AST::Node
+    include VariablePredicates
+
+    ##
+    # Returns the line number of the node.
+    #
+    # @return [Fixnum]
+    #
+    attr_reader :line
+
+    ##
+    # Returns the column number of the node.
+    #
+    # @return [Fixnum]
+    #
+    attr_reader :column
+
+    ##
+    # Returns the name of the file that the node belongs to.
+    #
+    # @return [String]
+    #
+    attr_reader :file
+
+    ##
+    # @return [String]
+    #
+    def name
+      name = children[0] || type
+      name = name.is_a?(Node) ? name.children[0] : name
+
+      return name.to_s
+    end
+
+    ##
+    # @return [Mixed]
+    #
+    def value
+      value = collection? ? children : children[-1]
+      value = children[1] if variable?
+
+      return value
+    end
+
+    ##
+    # Returns the receiver of the method call/definition.
+    #
+    # @return [RubyLint::Node]
+    #
+    def receiver
+      return method? ? children[-1] : children[-2]
+    end
+
+    ##
+    # Returns a symbol that indicates if a node is either a method or instance
+    # method.
+    #
+    # @return [Symbol]
+    #
+    def method_type
+      return receiver ? :method : :instance_method
+    end
+
+    ##
+    # Gathers a set of arguments and returns them as an Array.
+    #
+    # @param [#to_sym] type The type of arguments to gather.
+    # @return [Array]
+    #
+    def gather_arguments(type = :argument)
+      args = []
+      type = type.to_sym
+
+      children.each do |child|
+        if !child.is_a?(Node) or child.type != :arguments
+          next
+        end
+
+        child.children.each do |child_arg|
+          next unless child_arg.type == type
+
+          args << child_arg.children[0]
+        end
+      end
+
+      return args
+    end
+
+    ##
+    # Iterates over each argument of the given type.
+    #
+    # @param [Symbol] type The argument type.
+    # @yieldparam [RubyLint::Node] argument
+    #
+    def each_argument(type = :argument)
+      gather_arguments(type).each do |arg|
+        yield arg
+      end
+    end
+  end # Node
+end # RubyLint