rattler 0.5.0 → 0.6.0

data/lib/rattler/util/graphviz.rb

@@ -1,28 +1,17 @@
-#
-# = rattler/util/graphviz.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
 require 'rattler/util'
 
 module Rattler::Util
-  #
-  # The +GraphViz+ provides utilities to build GraphViz objects representing
-  # trees of nodes.
-  #
-  # @author Jason Arhart
-  #
+
+  # +GraphViz+ provides utilities to build GraphViz objects representing trees
+  # of nodes.
   module GraphViz
 
     autoload :DigraphBuilder, 'rattler/util/graphviz/digraph_builder'
     autoload :NodeBuilder, 'rattler/util/graphviz/node_builder'
 
-    # Return a new +GraphViz+ digraph object representing +root+.
-    #
-    # @return a new +GraphViz+ digraph object representing +root+
-    def self.digraph(root)
-      DigraphBuilder.digraph(root)
+    # (see DigraphBuilder.digraph)
+    def self.digraph(root, name='G')
+      DigraphBuilder.digraph(root, name)
     end
 
   end

data/lib/rattler/util/graphviz/digraph_builder.rb

@@ -1,10 +1,3 @@
-#
-# = rattler/util/graphviz/digraph_builder.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 begin
   require 'graphviz'
 rescue LoadError => e
@@ -14,28 +7,27 @@ end
 require 'rattler/util/graphviz'
 
 module Rattler::Util::GraphViz
-  #
+
   # +DigraphBuilder+ is used to build GraphViz objects representing trees of
   # nodes.
-  #
-  # @author Jason Arhart
-  #
   class DigraphBuilder
+    include NodeBuilder
 
-    # Return a new +GraphViz+ digraph object representing +root+.
-    #
+    # @param (see #initialize)
     # @return a new +GraphViz+ digraph object representing +root+
     def self.digraph(root, name='G')
       self.new(root, name).digraph
     end
 
     # Create a new digraph builder for +root+.
+    #
+    # @param root the root node
+    # @param [String] name the name of the graph
     def initialize(root, name='G')
       @root = root
       @g = ::GraphViz.digraph(name)
       @nodes = {}
       @node_serial = 0
-      @node_builder = NodeBuilder.new
     end
 
     # @return a new +GraphViz+ digraph object representing the root object
@@ -49,12 +41,13 @@ module Rattler::Util::GraphViz
     # Return a <tt>GraphViz::Node</tt> object for +o+. Multiple requests with
     # the same object return the same node object.
     #
-    # @return a <tt>GraphViz::Node</tt> object for +o+
+    # @param o an object
+    # @return [GraphViz::Node] a node object for +o+
     def node(o)
       @nodes.fetch(o.object_id) do
-        new_node = @g.add_node new_node_name, @node_builder.node_options(o)
+        new_node = @g.add_nodes new_node_name, node_options(o)
         @nodes[o.object_id] = new_node
-        @node_builder.each_child_of(o) {|_| new_node << node(_) }
+        each_child_node_of(o) {|_| new_node << node(_) }
         new_node
       end
     end

data/lib/rattler/util/graphviz/node_builder.rb

@@ -1,23 +1,18 @@
-#
-# = rattler/util/graphviz/node_builder.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
 require 'rattler/util/graphviz'
 
 module Rattler::Util::GraphViz
-  #
-  # +NodeBuilder+ is used by +DigraphBuilder+ to build nodes for a GraphViz
+
+  # +NodeBuilder+ is used by {DigraphBuilder} to build nodes for a GraphViz
   # digraph object representing a tree of nodes.
-  #
-  # @author Jason Arhart
-  #
-  class NodeBuilder
-
-    # Yield any children of +o+ that should be represented as separate nodes in
-    # the graph.
-    def each_child_of(o)
+  module NodeBuilder
+
+    # Run the block with any children of +o+ that should be represented as
+    # separate nodes in the graph.
+    #
+    # @param o an object
+    # @yield [child] each child of +o+ that should be represented as a separate
+    #   node in the graph
+    def each_child_node_of(o)
       if array_like? o and not record_like? o
         if o.respond_to? :to_hash
           o.each {|k, v| yield Mapping.new(k, v) }
@@ -27,13 +22,13 @@ module Rattler::Util::GraphViz
       end
     end
 
-    # Return the options for a node representing +o+.
+    # @param o an object
     # @return the options for a node representing +o+.
     def node_options(o)
       { :shape => node_shape(o), :label => node_label(o) }
     end
 
-    # Return the shape option for a node representing +o+.
+    # @param o an object
     # @return the shape option for a node representing +o+.
     def node_shape(o)
       case o
@@ -46,7 +41,7 @@ module Rattler::Util::GraphViz
       end
     end
 
-    # Return the label option for a node representing +o+.
+    # @param o an object
     # @return the label option for a node representing +o+.
     def node_label(o)
       if o.is_a? ::Rattler::Util::Node
@@ -56,29 +51,30 @@ module Rattler::Util::GraphViz
       elsif array_like? o
         type_label(o)
       elsif o.respond_to? :to_str
-        "\"#{o}\""
+        string_label(o)
       else
         o.inspect
       end
     end
 
-    def type_label(o)
-      case o
-      when Hash then '\\{\\}'
-      when Array then '\\[\\]'
-      when Mapping then '->'
-      else o.respond_to?(:name) ? o.name : o.class.name
-      end
+    # @param o an object
+    # @return whether +o+ should be represented as a record
+    def record_like?(o)
+      o.respond_to? :each_pair and
+      o.none? {|k, v| array_like? v or record_like? v }
     end
 
+    # @param o an object
+    # @return whether +o+ should be represented as an array
     def array_like?(o)
       o.respond_to? :each and
       not o.respond_to? :to_str
     end
 
-    def record_like?(o)
-      o.respond_to? :each_pair and
-      o.none? {|k, v| array_like? v or record_like? v }
+    private
+
+    def string_label(s)
+      "\"#{s}\""
     end
 
     def record_label(o, fields)
@@ -86,7 +82,24 @@ module Rattler::Util::GraphViz
     end
 
     def hash_content_labels(h)
-      h.map {|pair| '{' + pair.map {|_| _.inspect }.join('|') + '}' }
+      h.map {|k, v| "{#{k.inspect}|#{record_value v}}" }
+    end
+
+    def record_value(v)
+      if v.respond_to? :to_str
+        string_label(v)
+      else
+        v.inspect
+      end.gsub(/([|<>\\])/) { "\\#{$1}" }
+    end
+
+    def type_label(o)
+      case o
+      when Hash then '\\{\\}'
+      when Array then '\\[\\]'
+      when Mapping then '-&gt;'
+      else o.respond_to?(:name) ? o.name : o.class.name
+      end
     end
 
     def parse_node_fields(attrs)
@@ -106,5 +119,6 @@ module Rattler::Util::GraphViz
       end
     end
 
+    extend self
   end
 end

data/lib/rattler/util/line_counter.rb

@@ -1,27 +1,18 @@
-#
-# = rattler/util/line_counter.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
 require 'rattler/util'
 
 module Rattler::Util
-  #
+
   # A +LineCounter+ takes a linear index into text and calculates line and
   # column numbers.
-  #
-  # @author Jason Arhart
-  #
   class LineCounter
-    
+
     # @private
     @@newline = "\n" #:nodoc:
-    
+
     # @private
     @@tab = "\t" #:nodoc:
-    
-    # Create a <tt>Rattler::Util::LineCounter</tt> object for +source+.
+
+    # Create a +LineCounter+ object for +source+.
     #
     # @param [String] source the text in which to count lines
     # @param [Hash] options any optional options for the line counter
@@ -31,7 +22,7 @@ module Rattler::Util
       @source = source
       @tab_size = options[:tab_size] || 8
     end
-    
+
     # Return the line number of the character at +index+.
     #
     # @param [Integer] index the (0-based) index into the text
@@ -40,7 +31,7 @@ module Rattler::Util
       count(index)
       return @line
     end
-    
+
     # Return the column number of the character at +index+. When a _tab_
     # character is encountered the next tab stop is used for the column
     # number of the character following the _tab_ character.
@@ -51,9 +42,9 @@ module Rattler::Util
       count(index)
       return @column
     end
-    
+
     private
-    
+
     def count(index)
       unless @index == index
         @index = index
@@ -69,10 +60,10 @@ module Rattler::Util
         end
       end
     end
-    
+
     def next_tab_stop
       ((@column - 1) / @tab_size + 1) * @tab_size + 1
     end
-    
+
   end
 end

data/lib/rattler/util/node.rb

@@ -1,48 +1,33 @@
-#
-# = rattler/util/node.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
 require 'rattler/util'
 
 module Rattler::Util
-  #
+
   # A +Node+ is a node that can be used as-is to compose tree structures or
-  # as a base class for nodes. It is the base class used for all tree
-  # structures in the +Rattler+ framework.
-  #
-  # @author Jason Arhart
-  #
+  # as a base class for user-defined node types. It is the base class used for
+  # all tree structures in the +Rattler+ framework.
   class Node
     include Enumerable
 
-    # Create a +Node+ object.
-    #
-    # @return [Node]
-    #
     # @overload Node.[]()
-    #   @return [Node]
+    #   @return [Node] a +Node+ object with no children or attributes
     # @overload Node.[](child...)
-    #   @return [Node]
+    #   @return [Node] a +Node+ object with children and no attributes
     # @overload Node.[](attribute...)
-    #   @return [Node]
+    #   @return [Node] a +Node+ object with attributes and no children
     # @overload Node.[](child..., attribute...)
-    #   @return [Node]
+    #   @return [Node] a +Node+ object with children and attributes
     def self.[](*args)
       self.new(*args)
     end
 
-    # Create a +Node+ object.
-    #
     # @overload initialize()
-    #   @return [Node]
+    #   Create a +Node+ object with no children or attributes.
     # @overload initialize(child...)
-    #   @return [Node]
+    #   Create a +Node+ object with children and no attributes.
     # @overload initialize(attribute...)
-    #   @return [Node]
+    #   Create a +Node+ object with attributes and no children.
     # @overload initialize(child..., attribute...)
-    #   @return [Node]
+    #   Create a +Node+ object with children and attributes.
     def initialize(*args)
       @attrs = args.last.respond_to?(:to_hash) ? args.pop : {}
       @__children__ = args
@@ -95,16 +80,25 @@ module Rattler::Util
       block_given? ? children.each { |_| yield _ } : children.each
     end
 
+    # @param [Array] new_children a new array of children
+    # @return [Node] a new code with the new children replacing the node's
+    #   children
     def with_children(new_children)
       self.class.new(new_children, attrs)
     end
 
     alias_method :with_child, :with_children
 
+    # @param (see #new_attrs!)
+    # @return [Node] a new node with the new attributes added to the node's
+    #   attributes
     def with_attrs(new_attrs)
       self.with_attrs!(attrs.merge new_attrs)
     end
 
+    # @param [Hash] new_attrs a new set of attributes
+    # @return [Node] a new node with the new attributes replacing the node's
+    #   attributes
     def with_attrs!(new_attrs)
       self.class.new(children, new_attrs)
     end
@@ -119,18 +113,14 @@ module Rattler::Util
     # Access the node's children as if the node were an array of its children.
     #
     # @overload [](index)
-    #   Return the node's child at +index+.
     #   @param [Integer] index index of the child
     #   @return the child at +index+
     # @overload [](start, length)
-    #   Return an array of the node's children starting at +start+ and
-    #   continuing for +length+ children.
     #   @param [Integer] start the index of the first child
     #   @param [Integer] length the number of children to return
     #   @return [Array] the node's children starting at +start+ and
     #     continuing for +length+ children
     # @overload [](range)
-    #   Return an array of the node's children specified by +range+.
     #   @param [Range] range the range of children
     #   @return [Array] the node's children specified by +range+
     def [](*args)
@@ -186,9 +176,41 @@ module Rattler::Util
       ']'
     end
 
+    # @private
+    def pretty_print(q) #:nodoc:
+      pretty_print_name(q)
+      q.group(1, '[', ']') do
+        q.breakable('')
+        q.seplist(children) {|_| q.pp _ }
+        q.comma_breakable unless children.empty? or pretty_keys.empty?
+        q.seplist(pretty_keys) do |k|
+          q.pp k
+          q.text '=>'
+          q.pp attrs[k]
+        end
+      end
+    end
+
+    # @private
+    def pretty_print_cycle(q) #:nodoc:
+      pretty_print_name(q)
+    end
+
+    # @return a new +GraphViz+ digraph object representing the node
     def to_graphviz
       Rattler::Util::GraphViz.digraph(self)
     end
 
+    private
+
+    def pretty_print_name(q)
+      q.text(self.class.name)
+      q.text("<#{self.name.inspect}>") if attrs.has_key?(:name)
+    end
+
+    def pretty_keys
+      @pretty_keys ||= attrs.keys.reject {|_| _ == :name }.sort_by {|_| _.to_s }
+    end
+
   end
 end