ruby-lint 0.0.1a

data/lib/rlint/formatter/text.rb

@@ -0,0 +1,54 @@
+module Rlint
+  module Formatter
+    ##
+    # {Rlint::Formatter::Text} is a formatter class that formats a report in a
+    # format similar to the one used by Ruby when validating a Ruby file using
+    # the `ruby` executable. An example of this format is the following:
+    #
+    #     b.rb: error: line 1, column 1: test error
+    #     b.rb: info: line 3, column 1: test info b.rb
+    #
+    # Basic usage of this formatter is as following:
+    #
+    #     report    = Rlint::Report.new
+    #     formatter = Rlint::Formatter::Text.new
+    #
+    #     # Add some data to the report.
+    #     # ...
+    #
+    #     puts formatter.format(report)
+    #
+    class Text
+      ##
+      # A short description of the class.
+      #
+      # @return [String]
+      #
+      DESCRIPTION = 'Formats a report in a human readable format.'
+
+      ##
+      # Formats the specified report.
+      #
+      # @param  [Rlint::Report] report The report to format.
+      # @return [String]
+      #
+      def format(report)
+        lines = []
+
+        report.messages.sort.each do |level, messages|
+          messages.each do |message|
+            lines << '%s: %s: line %s, column %s: %s' % [
+              report.file,
+              level,
+              message[:line],
+              message[:column],
+              message[:message]
+            ]
+          end
+        end
+
+        return lines.join("\n")
+      end
+    end # Text
+  end # Formatter
+end # Rlint

data/lib/rlint/helper/definition_resolver.rb

@@ -0,0 +1,143 @@
+module Rlint
+  module Helper
+    ##
+    # {Rlint::Helper::DefinitionResolver} is a helper module that can be used
+    # to work with scoping information similar to {Rlint::Helper::Scoping}.
+    #
+    # This module depends on {Rlint::Helper::Scoping} and will include it
+    # automatically.
+    #
+    # ## Methods
+    #
+    # This module defines a set of methods that are called before and after a
+    # method, class or module is defined. These methods take care of retrieving
+    # the scope for each definition.
+    #
+    # These methods will also call two special callback methods that make it
+    # easier to run code whenever the scope changes:
+    #
+    # * `on_new_scope`: called when a new scope has been set.
+    # * `after_new_scope`: called when the code has reached the end of the
+    #   current scope.
+    #
+    # Using these methods classes including this module don't have to redefine
+    # methods such as `on_class` (unless explicitly needed of course). Both of
+    # these methods are called *after* the current scope has been updated.
+    #
+    module DefinitionResolver
+      include Scoping
+
+      ##
+      # Called before processing all the tokens.
+      #
+      def on_start
+        call_method(:on_new_scope)
+      end
+
+      ##
+      # Called after all the tokens have been processed.
+      #
+      def on_finish
+        call_method(:after_new_scope)
+      end
+
+      ##
+      # Sets the scope for the current method definition.
+      #
+      # @param [Rlint::Token::MethodDefinitionToken] token
+      #
+      def on_method_definition(token)
+        @scopes << scope.lookup(
+          token.receiver ? :method : :instance_method,
+          token.name
+        )
+
+        @call_types << :instance_method
+
+        call_method(:on_new_scope)
+      end
+
+      ##
+      # Resets the scope back to the one used before the method definition.
+      #
+      # @see Rlint::Helper::DefinitionResolver#on_method_definition
+      #
+      def after_method_definition(token)
+        @scopes.pop
+        @call_types.pop
+
+        call_method(:after_new_scope)
+      end
+
+      ##
+      # Sets the scope for the current class.
+      #
+      # @param [Rlint::Token::ClassToken] token
+      #
+      def on_class(token)
+        name = token.name.join('::')
+
+        @scopes     << scope.lookup(:constant, name)
+        @namespace  << name
+        @call_types << :method
+
+        call_method(:on_new_scope)
+      end
+
+      ##
+      # Resets the scope back to the one used before the class definition.
+      #
+      # @see Rlint::Helper::DefinitionResolver#on_class
+      #
+      def after_class(token)
+        @scopes.pop
+        @namespace.pop
+        @call_types.pop
+
+        call_method(:after_new_scope)
+      end
+
+      ##
+      # Sets the scope for the current module.
+      #
+      # @param [Rlint::Token::Token] token
+      #
+      def on_module(token)
+        name = token.name.join('::')
+
+        @scopes     << scope.lookup(:constant, name)
+        @namespace  << name
+        @call_types << :method
+
+        call_method(:on_new_scope)
+      end
+
+      ##
+      # Resets the scope back to the one used before the module definition.
+      #
+      # @see Rlint::Helper::DefinitionResolver#on_module
+      #
+      def after_module(token)
+        @scopes.pop
+        @namespace.pop
+        @call_types.pop
+
+        call_method(:after_new_scope)
+      end
+
+      private
+
+      ##
+      # Calls the specified method if it exists.
+      #
+      # @param [String|Symbol] method The name of the method to call.
+      # @param [Array] args Array of arguments to pass to the method that is
+      #  being called.
+      # @return [Mixed]
+      #
+      def call_method(method, *args)
+        return send(method, *args) if respond_to?(method)
+      end
+    end # DefinitionResolver
+  end # Helper
+end # Rlint

data/lib/rlint/helper/scoping.rb

@@ -0,0 +1,138 @@
+module Rlint
+  module Helper
+    ##
+    # {Rlint::Helper::Scoping} is a helper module that can be used to more
+    # easily access scoping related information in subclasses of
+    # {Rlint::Callback}.
+    #
+    # Note that unlike {Rlint::Helper::DefinitionResolver} this method does not
+    # automatically update the `@scopes` array mentioned below, it merely
+    # creates the required variables and provides a few helper methods.
+    #
+    # ## Methods
+    #
+    # This module provides two methods:
+    #
+    # * scope: a method that can be used to retrieve the current
+    #   scope/definition.
+    # * resolve_definition: a method that can be used to retrieve the
+    #   scope/definition for the last constant in a constant path.
+    #
+    # ## Variables
+    #
+    # The following instance variables are created upon initializing a class
+    # that includes this module:
+    #
+    # * `@scopes`: an array that should be updated with instance of
+    #   {Rlint::Definition} based on the current scope.
+    # * `@namespace`: array containing the constant names for the current
+    #   namespace.
+    #
+    # The following keys are set in the `@storage` instance variable:
+    #
+    # * `:scope`: an instance of {Rlint::Definition} that will contain the
+    #   definition list of the current block of code that's being analyzed.
+    #
+    module Scoping
+      ##
+      # @see Rlint::Callback#initialize
+      #
+      def initialize(*args)
+        super
+
+        @scopes     = []
+        @namespace  = []
+        @call_types = []
+
+        unless @storage[:scope].is_a?(Definition)
+          @storage[:scope] = Definition.new(nil, :lazy => true, :kernel => true)
+        end
+      end
+
+      private
+
+      ##
+      # Returns the scope/definition for the last segment in the specified
+      # constant path.
+      #
+      # @param  [Array] path The constant path.
+      # @return [Rlint::Definition]
+      #
+      def resolve_definition(path)
+        current = scope
+
+        path.each do |segment|
+          found   = current.lookup(:constant, segment)
+          current = found if found
+        end
+
+        return current
+      end
+
+      ##
+      # Checks if the specified token's name is a valid constant path.
+      #
+      # @param  [Rlint::Token::VariableToken] token The token to validate.
+      # @return [TrueClass|FalseClass]
+      #
+      def valid_constant_path?(token)
+        current = scope
+
+        token.name.each do |segment|
+          found = current.lookup(:constant, segment)
+
+          if found and token.line > found.token.line
+            current = found
+          else
+            return false
+          end
+        end
+
+        return true
+      end
+
+      ##
+      # Checks if the specified type and token result in a valid
+      # {Rlint::Definition} instance.
+      #
+      # @param [#to_sym] type The type of data to look up.
+      # @param [Rlint::Token::VariableToken] token The token containing details
+      #  about the variable.
+      # @param [Rlint::Definition] scope The scope to use for looking up the
+      #  data.
+      # @return [TrueClass|FalseClass]
+      #
+      def definition_exists?(type, token, scope = scope)
+        found    = scope.lookup(type, token.name)
+        has_line = found.respond_to?(:token) \
+          && !found.token.nil? \
+          && !found.token.line.nil?
+
+        if !found or (has_line and found.token.line > token.line)
+          return false
+        else
+          return true
+        end
+      end
+
+      ##
+      # Returns the call type to use for method calls.
+      #
+      # @return [Symbol]
+      #
+      def call_type
+        return !@call_types.empty? ? @call_types[-1] : :instance_method
+      end
+
+      ##
+      # Returns the current scope. This method is primarily used to make the
+      # code in this class a bit more pleasant to read.
+      #
+      # @return [Rlint::Definition]
+      #
+      def scope
+        return !@scopes.empty? ? @scopes[-1] : @storage[:scope]
+      end
+    end # Scoping
+  end # Helper
+end # Rlint

data/lib/rlint/iterator.rb

@@ -0,0 +1,193 @@
+module Rlint
+  ##
+  # {Rlint::Iterator} is a class that can be used to iterate over the AST
+  # generated by {Rlint::Parser} and execute callback methods for each
+  # encountered node. Basic usage is as following:
+  #
+  #     code = <<-CODE
+  #     [10, 20].each do |number|
+  #       puts number
+  #     end
+  #     CODE
+  #
+  #     parser   = Rlint::Parser.new(code)
+  #     tokens   = parser.parse
+  #     iterator = Rlint::Iterator.new
+  #
+  #     iterator.run(tokens)
+  #
+  # 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.
+  #
+  # ## Callback Classes
+  #
+  # 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
+  # {Rlint::Iterator#bind}. At the most basic level each callback class should
+  # have the following structure:
+  #
+  #     class MyCallback
+  #       attr_reader :options
+  #
+  #       def initialize(report = nil, storage = {})
+  #         @report  = report
+  #         @storage = storage
+  #       end
+  #     end
+  #
+  # The constructor method should take two parameters: the first one is used
+  # for storing a instance of {Rlint::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 {Rlint::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 {Rlint::Callback}:
+  #
+  #     class MyCallback < Rlint::Callback
+  #
+  #     end
+  #
+  # To add your class to an iterator instance you'd run the following:
+  #
+  #     iterator = Rlint::Iterator.new
+  #
+  #     iterator.bind(MyCallback)
+  #
+  # ## Callback Methods
+  #
+  # When iterating over an AST the method {Rlint::Iterator#iterator} calls two
+  # callback methods based on the event name stored in the token (in
+  # {Rlint::Token::Token#event}):
+  #
+  # * `on_EVENT_NAME`
+  # * `after_EVENT_NAME`
+  #
+  # 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
+  # {Rlint::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 < Rlint::Callback
+  #       def on_string(token)
+  #         puts token.value
+  #       end
+  #     end
+  #
+  class Iterator
+    ##
+    # Array containing a set of instance specific callback objects.
+    #
+    # @return [Array]
+    #
+    attr_reader :callbacks
+
+    ##
+    # Returns the Hash that is used by callback classes to store arbitrary
+    # data.
+    #
+    # @return [Hash]
+    #
+    attr_reader :storage
+
+    ##
+    # Creates a new instance of the iterator class.
+    #
+    # @param [Rlint::Report|NilClass] report The report to use, set to `nil` by
+    #  default.
+    #
+    def initialize(report = nil)
+      @callbacks = []
+      @report    = report
+      @storage   = {}
+    end
+
+    ##
+    # Processes the entire AST for each callback class in sequence. For each
+    # callback class the method {Rlint::Iterator#iterate} is called to process
+    # an *entire* AST before moving on to the next callback class.
+    #
+    # @param [#each] nodes An array of nodes to process.
+    #
+    def run(nodes)
+      @callbacks.each do |obj|
+        execute_callback(obj, :on_start)
+
+        iterate(obj, nodes)
+
+        execute_callback(obj, :on_finish)
+      end
+    end
+
+    ##
+    # Processes an AST and calls callbacks methods for a specific callback
+    # object.
+    #
+    # @param [Rlint::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.
+    #
+    def iterate(callback_obj, nodes)
+      nodes.each do |node|
+        next unless node.is_a?(Rlint::Token::Token)
+
+        event_name     = node.event.to_s
+        callback_name  = 'on_' + event_name
+        after_callback = 'after_' + event_name
+
+        execute_callback(callback_obj, callback_name, node)
+
+        node.child_nodes.each do |child_nodes|
+          iterate(callback_obj, child_nodes) if child_nodes.respond_to?(:each)
+        end
+
+        execute_callback(callback_obj, after_callback, node)
+      end
+    end
+
+    ##
+    # Adds the specified class to the list of callback classes for this
+    # instance.
+    #
+    # @example
+    #  iterator = Rlint::Iterator.new
+    #
+    #  iterator.bind(CustomCallbackClass)
+    #
+    # @param [Class] callback_class The class to add.
+    #
+    def bind(callback_class)
+      @callbacks << callback_class.new(@report, @storage)
+    end
+
+    private
+
+    ##
+    # Loops through all the bound callback classes and executes the specified
+    # callback method if it exists.
+    #
+    # @param [Rlint::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)
+    end
+  end # Iterator
+end # Rlint