wool 0.5.1

data/lib/wool/analysis/annotations.rb

@@ -0,0 +1,34 @@
+module Wool
+  module SexpAnalysis
+    # This is the base module for all annotations that can run on ASTs.
+    # It includes all other annotation modules to provide all the
+    # annotations to the Sexp class. These annotations are run at initialize
+    # time for the Sexps and have access to a node and all of its child nodes,
+    # all of which have been annotated. Synthesized attributes are fair game,
+    # and adding inherited attributes to subnodes is also fair game.
+    #
+    # All annotations add O(V) to the parser runtime.
+    #
+    # This module also provides some helper methods to inject functionality into
+    # the Sexp class. Since that's what an annotation is, I don't consider
+    # this bad form!
+    module BasicAnnotation
+      def add_annotator(*args)
+        SexpAnalysis::Sexp.annotations.concat args.map(&:new)
+      end
+      alias_method :add_annotators, :add_annotator
+      def add_global_annotator(*args)
+        SexpAnalysis.global_annotations.concat args.map(&:new)
+      end
+      alias_method :add_global_annotators, :add_global_annotator
+      def add_property(*args)
+        SexpAnalysis::Sexp.__send__(:attr_accessor, *args)
+      end
+      alias_method :add_properties, :add_property
+    end
+  end
+end
+
+Dir[File.expand_path(File.join(File.dirname(__FILE__), 'annotations', '**', '*.rb'))].each do |file|
+  load file
+end

data/lib/wool/analysis/annotations/next_annotation.rb

@@ -0,0 +1,26 @@
+module Wool
+  module SexpAnalysis
+    # This is a simple inherited attribute applied to each node,
+    # giving a pointer to that node's next and previous AST node.
+    # That way AST traversal is easier.
+    module NextPrevAnnotation
+      extend BasicAnnotation
+      add_properties :next, :prev
+      
+      # This is the annotator for the next and prev annotation.
+      class Annotator
+        def annotate!(root)
+          children = root.children
+          children.each_with_index do |elt, idx|
+            # ignore non-sexps. Primitives can't be annotated, sadly.
+            if SexpAnalysis::Sexp === elt
+              elt.next = children[idx+1]
+              elt.prev = children[idx-1] if idx >= 1
+            end
+          end
+        end
+      end
+      add_annotator Annotator
+    end
+  end
+end

data/lib/wool/analysis/annotations/parent_annotation.rb

@@ -0,0 +1,20 @@
+module Wool
+  module SexpAnalysis
+    # This is a simple inherited attribute applied to each node,
+    # giving a pointer to that node's parent. That way AST traversal
+    # is easier.
+    module ParentAnnotation
+      extend BasicAnnotation
+      add_property :parent
+      
+      # This is the annotator for the parent annotation.
+      class Annotator
+        def annotate!(root)
+          root.parent = nil
+          root.children.select {|x| SexpAnalysis::Sexp === x}.each {|sexp| sexp.parent = root}
+        end
+      end
+      add_annotator Annotator
+    end
+  end
+end

data/lib/wool/analysis/annotations/scope_annotation.rb

@@ -0,0 +1,37 @@
+module Wool
+  module SexpAnalysis
+    # This is a *global* annotation, namely the one that determines the statically-known
+    # scope for each node in the AST, at the time of that node's execution. For
+    # example, every node should be able to say "hey scope, what's 'this' for this
+    # statement?", and be able to return its type (*NOT* its class, they're different).
+    module ScopeAnnotation
+      extend BasicAnnotation
+      add_property :scope
+      
+      # This is the annotator for the parent annotation.
+      class Annotator
+        include Visitor
+        def annotate!(root)
+          @current_scope = Scope::GlobalScope
+          visit(root)
+        end
+        
+        # Replaces the general node visit method with one that assigns
+        # the current scope to the visited node.
+        def default_visit(node)
+          node.scope = @current_scope
+        end
+        
+        def visit_module(node)
+          path_node, body = node.children
+        end
+        
+        def visit_class(node)
+          path_to_new_class, superclass, body = node.children
+          superclass = superclass ? superclass.eval_as_constant(@current_scope) : ClassRegistry['Object']
+        end
+      end
+      add_global_annotator Annotator
+    end
+  end
+end

data/lib/wool/analysis/lexical_analysis.rb

@@ -0,0 +1,165 @@
+module Wool
+  # This is a set of methods that get provided to Warnings so they can perform
+  # lexical analysis of their bodies. This module handles tokenizing only - not
+  # parse-trees.
+  module LexicalAnalysis
+    # This is a wrapper class around the tokens returned by Ripper. Since the
+    # tokens are just arrays, this class lets us use nice mnemonics with almost zero
+    # runtime overhead.
+    class Token < Struct.new(:type, :body, :line, :col)
+      # Unpacks the token from Ripper and breaks it into its separate components.
+      #
+      # @param [Array<Array<Integer, Integer>, Symbol, String>] token the token
+      #     from Ripper that we're wrapping
+      def initialize(token)
+        pos, self.type, self.body = token
+        self.line, self.col = pos
+      end
+    end
+    
+    # Lexes the given text.
+    #
+    # @param [String] body (self.body) The text to lex
+    # @return [Array<Array<Integer, Integer>, Symbol, String>] A set of tokens
+    #   in Ripper's result format. Each token is an array of the form:
+    #   [[1, token_position], token_type, token_text]. I'm not exactly clear on
+    #   why the 1 is always there. At any rate - the result is an array of those
+    #   tokens.
+    def lex(body = self.body)
+      Ripper.lex(body).map {|token| Token.new(token) }
+    end
+
+    # Returns the text between two token positions. The token positions are
+    # in [line, column] format. The body, left, and right tokens must be provided,
+    # and optionally, you can override the inclusiveness of the text-between operation.
+    # It defaults to :none, for including neither the left nor right tokens in the
+    # result. You can pass :none, :left, :right, or :both.
+    #
+    # @param [String] body (self.body) The first parameter is optional: the text
+    #   to search. This defaults to the full text.
+    # @param [Token] left the left token to get the text between
+    # @param [Token] right the right token to get the text between
+    # @param [Symbol] inclusive should the :left, :right, :both, or :none tokens
+    #    be included in the resulting text?
+    # @return the text between the two tokens within the text. This is necessary
+    #    because the lexer provides [line, column] coordinates which is quite
+    #    unfortunate.
+    def text_between_token_positions(text, left, right, inclusive = :none)
+      result = ""
+      lines = text.lines.to_a
+      left.line.upto(right.line) do |cur_line|
+        line = lines[cur_line - 1]
+        result << left.body if cur_line == left.line && (inclusive == :both || inclusive == :left)
+        left_bound = cur_line == left.line ? left.col + left.body.size : 0
+        right_bound = cur_line == right.line ? right.col - 1 : -1
+        result << line[left_bound..right_bound]
+        result << right.body if cur_line == right.line && (inclusive == :both || inclusive == :right)
+      end
+      result
+    end
+      
+    # Searches for the given token using standard [body], target symbols syntax.
+    # Yields for each token found that matches the query, and returns all those
+    # who match.
+    #
+    # @param [String] body (self.body) The first parameter is optional: the text
+    #   to search. This defaults to the full text.
+    # @param [Symbol] token The rest of the arguments are tokens to search
+    #   for. Any number of tokens may be specified.
+    # @return [Array<Array>] All the matching tokens for the query
+    def select_token(*args)
+      body, list = _extract_token_search_args(args)
+      result = []
+      while (token = find_token(body, *list)) && token != nil
+        result << token if yield(*token)
+        _, body = split_on_token(body, *list)
+        body = body[token.body.size..-1]
+      end
+      return result
+    end
+    
+    # Finds the first instance of a set of keywords in the body. If no text is
+    # given to scan, then the full content is scanned.
+    #
+    # @param [String] body (self.body) The first parameter is optional: the text
+    #   to search. This defaults to the full text.
+    # @param [Symbol] keyword The rest of the arguments are keywords to search
+    #   for. Any number of keywords may be specified.
+    # @return [Array] the token in the form returned by Ripper. See #lex.
+    def find_keyword(*args)
+      body, list = _extract_token_search_args(args)
+      list.map! {|x| x.to_s}
+      lexed = lex(body)
+      lexed.find.with_index do |tok, idx|
+        is_keyword = tok.type == :on_kw && list.include?(tok.body)
+        is_not_symbol = idx == 0 || lexed[idx-1].type != :on_symbeg
+        is_keyword && is_not_symbol
+      end
+    end
+
+    # Finds the first instance of a set of tokens in the body. If no text is
+    # given to scan, then the full content is scanned.
+    #
+    # @param [String] body (self.body) The first parameter is optional: the text
+    #   to search. This defaults to the full text.
+    # @param [Symbol] token The rest of the arguments are tokens to search
+    #   for. Any number of tokens may be specified.
+    # @return [Array] the token in the form returned by Ripper. See #lex.
+    def find_token(*args)
+      body, list = _extract_token_search_args(args)
+      lexed = lex(body)
+      lexed.find.with_index do |tok, idx|
+        is_token = list.include?(tok.type)
+        is_not_symbol = idx == 0 || lexed[idx-1].type != :on_symbeg
+        is_token && is_not_symbol
+      end
+    end
+
+    # Splits the body into two halfs based on the first appearance of a keyword.
+    #
+    # @example
+    #   split_on_keyword('x = 5 unless y == 2', :unless)
+    #   # => ['x = 5 ', 'unless y == 2']
+    # @param [String] body (self.body) The first parameter is optional: the text
+    #   to search. This defaults to the full text.
+    # @param [Symbol] token The rest of the arguments are keywords to search
+    #   for. Any number of keywords may be specified.
+    # @return [Array<String, String>] The body split by the keyword.
+    def split_on_keyword(*args)
+      body, keywords = _extract_token_search_args(args)
+      token = find_keyword(body, *keywords)
+      return _split_body_with_raw_token(body, token)
+    end
+
+    # Splits the body into two halfs based on the first appearance of a token.
+    #
+    # @example
+    #   split_on_token('x = 5 unless y == 2', :on_kw)
+    #   # => ['x = 5 ', 'unless y == 2']
+    # @param [String] body (self.body) The first parameter is optional: the text
+    #   to search. This defaults to the full text.
+    # @param [Symbol] token The rest of the arguments are tokens to search
+    #   for. Any number of tokens may be specified.
+    # @return [Array<String, String>] The body split by the token.
+    def split_on_token(*args)
+      body, tokens = _extract_token_search_args(args)
+      token = find_token(body, *tokens)
+      return _split_body_with_raw_token(body, token)
+    end
+
+    private
+
+    def _extract_token_search_args(args)
+      if args.first.is_a?(String)
+        return args[0], args[1..-1]
+      else
+        return self.body, args
+      end
+    end
+
+    def _split_body_with_raw_token(body, token)
+      max = token ? [0, token.col].max : body.size
+      return body[0,max], body[max..-1]
+    end
+  end
+end

data/lib/wool/analysis/protocol_registry.rb

@@ -0,0 +1,32 @@
+module Wool
+  module SexpAnalysis
+    # The ProtocolRegistry module handles negotiating instantiated protocols at
+    # compile-time, such as the automatically-generated protocols created by a
+    # class creation (as each class has a corresponding protocol, though some
+    # distinct classes may have equivalent protocols).
+    module ProtocolRegistry
+      extend ModuleExtensions
+      cattr_accessor_with_default :protocols, []
+      cattr_accessor_with_default :class_protocols, {}
+
+      def self.add_protocol(proto)
+        self.protocols << proto
+      end
+      
+      def self.add_class_protocol(class_protocol)
+        add_protocol class_protocol
+        self.class_protocols[class_protocol.class_used.path] = class_protocol
+      end
+
+      def self.[](class_name)
+        return query(:class_path => class_name.gsub(/^::/, ''))
+      end
+
+      def self.query(query={})
+        if query[:class_path]
+          return [self.class_protocols[query[:class_path]]]
+        end
+      end
+    end
+  end
+end

data/lib/wool/analysis/protocols.rb

@@ -0,0 +1,82 @@
+module Wool
+  module SexpAnalysis
+    # This module contains a class hierarchy that represents the type
+    # hierarchy in the analyzed Ruby code. This is where method responsiveness
+    # can be checked. Some protocols are simple, such as a ClassProtocol,
+    # which responds to all the methods that the corresponding Class does.
+    # Some might be structural or dependent or generic! The key part is that
+    # method signatures can be listed and queried.
+    module Protocols
+      # The base class for all protocols.
+      class Base
+        include Comparable
+
+        # Returns the list of all known signatures that this protocol responds
+        # to.
+        #
+        # @return [Array<Signature>] the supported signatures for this protocol.
+        def signatures
+          raise NotImplementedError.new('You must implement #signatures yourself.')
+        end
+        
+        # Compares the protocol to another protocol by comparing their signatures
+        # list (sorted).
+        def <=>(other)
+          self.signatures.sort <=> other.signatures.sort
+        end
+      end
+      
+      # This is a simple protocol whose signature set is just the union of the
+      # signature sets of its constituent protocols.
+      class UnionProtocol < Base
+        # Initializes the Union protocol to a set of constituent protocols.
+        #
+        # @param [Array<Base>] constituents the set of constituent protocols that
+        #    this protocol is a union of.
+        def initialize(constituents)
+          @protocols = constituents
+        end
+        
+        # Returns the list of all known signatures that this protocol responds
+        # to, which is the union of all the constituent protocols.
+        #
+        # @return [Array<Signature>] the supported signatures for this protocol.
+        def signatures
+          @protocols.map(&:signatures).inject(:|)
+        end
+      end
+      
+      # A protocol that has the same signatures as a given class.
+      class ClassProtocol < Base
+        attr_reader :class_used
+
+        # Initializes the class protocol with the given class.
+        #
+        # @param [WoolClass] klass the wool class whose protocol we are representing
+        def initialize(klass)
+          @class_used = klass
+        end
+        
+        # Compares two ClassProtocols. Has a short-circuit check if two protocols
+        # refer to the same class or not. Otherwise, it has to check the signatures.
+        #
+        # @param [Protocols::Base] other the other protocol to compare against
+        # @return [-1, 0, 1] a standard comparison result.
+        def <=>(other)
+          if ClassProtocol === other && self.class_used == other.class_used
+          then return 0
+          else self.signatures <=> other.signatures
+          end
+        end
+        
+        # Returns all the signatures that the class responds to, since this protocol
+        # has the same signatures.
+        #
+        # @return [Array<Signature>] the supported signatures for this protocol.
+        def signatures
+          @class_used.signatures
+        end
+      end
+    end
+  end
+end

data/lib/wool/analysis/scope.rb

@@ -0,0 +1,13 @@
+module Wool
+  module SexpAnalysis
+    # This class models a scope in Ruby. It has a constant table,
+    # a self pointer, and a parent pointer to the enclosing scope.
+    # It also has a local variable table.
+    class Scope
+      attr_reader :constants, :self_ptr, :parent
+      def initialize(parent, self_ptr, constants={})
+        @parent, @self_ptr, @constants = parent, self_ptr, constants
+      end
+    end
+  end
+end

data/lib/wool/analysis/sexp_analysis.rb

@@ -0,0 +1,98 @@
+module Wool
+  # This is a set of methods that get provided to Warnings so they can perform
+  # parse-tree analysis of their bodies.
+  module SexpAnalysis
+    extend ModuleExtensions
+    
+    # Replaces the ParseTree Sexps by adding a few handy-dandy methods.
+    class Sexp < Array
+      extend ModuleExtensions
+      
+      # Returns a mutable reference to the list of annotations that will run
+      # upon initializing a new Sexp.
+      #
+      # @return [Array[Class < Annotation]] the activated annotations, in the
+      #    order they will run in.
+      cattr_accessor_with_default :annotations, []
+      
+      # Initializes the Sexp with the contents of the array returned by Ripper.
+      #
+      # @param [Array<Object>] other the other 
+      def initialize(other)
+        replace other
+        replace_children!
+        self.class.annotations.each {|annotator| annotator.annotate!(self) }
+      end
+      
+      # @return [Array<Object>] the children of the node.
+      def children
+        (Array === self[0] ? self : self[1..-1]) || []
+      end
+      
+      # @return [Symbol] the type of the node.
+      def type
+        self[0]
+      end
+      
+      # Replaces the children with Sexp versions of them
+      def replace_children!
+        replace(map do |x|
+          case x
+          when Array
+            self.class.new(x)
+          else x
+          end
+        end)
+      end
+      private :replace_children!
+      
+      # Evaluates the constant reference/path with the given scope
+      # as context.
+      def eval_as_constant(scope)
+        case type
+        # [:var_ref, [:@const, "B", [1, 17]]]
+        when :var_ref then scope.constants[self[1][1]]
+        # [:const_ref, [:@const, "M", [1, 17]]]
+        when :const_ref then scope.constants[self[1][1]]
+        # [:top_const_ref, [:@const, "M", [1, 2]]]
+        when :top_const_ref then Scope::GlobalScope.constants[self[1][1]]
+        # [:@const, "B", [1, 7]]
+        when :@const then scope.constants[self[1]]
+        # [:const_path_ref, [:var_ref, [:@const, "B", [1, 17]]], [:@const, "M", [1, 20]]]
+        when :const_path_ref
+          left, right = children
+          scope = left.eval_as_constant(scope).scope
+          right.eval_as_constant(scope)
+        end
+      end
+    end
+    
+    # Global annotations are only run once, at the root. 
+    cattr_accessor_with_default :global_annotations, []
+    
+    # Parses the given text.
+    #
+    # @param [String] body (self.body) The text to parse
+    # @return [Sexp, NilClass] the sexp representing the input text.
+    def parse(body = self.body)
+      result = Sexp.new Ripper.sexp(body)
+      SexpAnalysis.global_annotations.each {|annotator| annotator.annotate!(result)}
+      result
+    end
+    
+    # Finds all sexps of the given type in the given Sexp tree.
+    #
+    # @param [Symbol] type the type of sexp to search for
+    # @param [Sexp] tree (self.parse(self.body)) The tree to search in. Leave
+    #   blank to search the entire body.
+    # @return [Array<Sexp>] all sexps in the input tree (or whole body) that
+    #   are of the given type.
+    def find_sexps(type, tree = self.parse(self.body))
+      result = tree[0] == type ? [tree] : []
+      tree.each do |node|
+        result.concat find_sexps(type, node) if node.is_a?(Array)
+      end
+      result
+    end
+  end
+end