rgl 0.2.3 → 0.3.0

data/lib/rgl/bidirectional.rb

@@ -0,0 +1,40 @@
+require 'rgl/base'
+
+module RGL
+
+  # BGL defines the concept BidirectionalGraph as follows:
+  # 
+  # The BidirectionalGraph concept refines IncidenceGraph and adds the
+  # requirement for efficient access to the in-edges of each vertex.  This
+  # concept is separated from IncidenceGraph because, for directed graphs,
+  # efficient access to in-edges typically requires more storage space,
+  # and many algorithms do not require access to in-edges.  For undirected
+  # graphs, this is not an issue; because the in_edges() and out_edges()
+  # functions are the same, they both return the edges incident to the vertex.
+  module BidirectionalGraph
+    include Graph
+
+    # Iterator providing access to the in-edges (for directed graphs) or incident
+    # edges (for undirected graphs) of vertex _v_. For both directed and
+    # undirected graphs, the target of an out-edge is required to be vertex _v_
+    # and the source is required to be a vertex that is adjacent to _v_.
+    def each_in_neighbor (v)
+      raise NotImplementedError
+      yield u
+    end
+    
+    # Returns the number of in-edges (for directed graphs) or the number of
+    # incident edges (for undirected graphs) of vertex _v_.
+    def in_degree (v)
+      r = 0;
+      each_in_neighbor(v) { |u| r += 1}
+      r
+    end
+
+    # Returns the number of in-edges plus out-edges (for directed graphs) or the 
+    # number of incident edges (for undirected graphs) of vertex _v_.
+    def degree (v)
+      in_degree(v) + out_degree(v)
+    end
+  end
+end

data/lib/rgl/dot.rb

@@ -1,6 +1,6 @@
 # dot.rb
 # 
-# $Id: dot.rb,v 1.5 2005/02/04 22:41:46 monora Exp $
+# $Id: dot.rb,v 1.7 2008/02/26 06:01:22 javanthropus Exp $
 # 
 # Minimal Dot support, based on Dave Thomas's dot module (included in rdoc).
 # rdot.rb is a modified version which also contains support for undirected
@@ -23,13 +23,13 @@ module RGL
     edge_class = directed? ? DOT::DOTDirectedEdge : DOT::DOTEdge
     each_vertex do |v|
       name = v.to_s
-      graph << DOT::DOTNode.new('name'     => '"' + name + '"',
+      graph << DOT::DOTNode.new('name'     => name,
                                 'fontsize' => fontsize,
                                 'label'    => name)
     end
     each_edge do |u,v|
-      graph << edge_class.new('from'     => '"'+ u.to_s + '"',
-                              'to'       => '"'+ v.to_s + '"',
+      graph << edge_class.new('from'     => u.to_s,
+                              'to'       => v.to_s,
                               'fontsize' => fontsize)
       end
       graph
@@ -41,7 +41,7 @@ module RGL
       s << to_dot_graph(params).to_s << "\n"
     end
 
-    # Call +dotty+ for the graph which is written to the file 'graph.dot'
+    # Call dotty[http://www.graphviz.org] for the graph which is written to the file 'graph.dot'
     # in the # current directory.
 
     def dotty (params = {})
@@ -52,8 +52,8 @@ module RGL
       system("dotty", dotfile)
     end
 
-    # Use +do+ to create a graphical representation of the graph.  Returns the
-    # filename of the graphics file.
+    # Use dot[http://www.graphviz.org] to create a graphical representation of
+    # the graph.  Returns the filename of the graphics file.
 
     def write_to_graphic_file (fmt='png', dotfile="graph")
       src = dotfile + ".dot"

data/lib/rgl/enumerable_ext.rb

@@ -0,0 +1,13 @@
+module Enumerable
+  # Fixnum()
+  #
+  # Return the number of elements of the Enumerable. Same as _size_ but not all
+  # Enumerables implement size.
+  #--
+  # Should we call the methods _size_?
+  def length
+    inject(0) do |sum,v|
+      sum + 1
+    end
+  end
+end

data/lib/rgl/graphxml.rb

@@ -16,26 +16,20 @@ require 'rexml/document'
 require 'rexml/streamlistener'
 
 module RGL
-
-  # Module GraphXML adds to each class, including module MutableGraph, a class
-  # method from_graphxml.
-  #
-  # Attention: Because append_features is used to provide the functionality,
-  # GraphXML must be loaded before the concrete class including MutableGraph
-  # is loaded.
-
-  module GraphXML
-
+  module MutableGraph
+    # Used to parse a subset of GraphML into an RGL graph implementation.
     class MutableGraphParser
-
       include REXML::StreamListener
 
-      attr_reader :graph
-
+      # First resets +graph+ to be empty and stores a reference for use with
+      # #tag_start.
       def initialize (graph)
         @graph = graph
+        @graph.remove_vertices(@graph.vertices)
       end
 
+      # Processes incoming edge and node elements from GraphML in order to
+      # populate the graph given to #new.
       def tag_start (name, attrs)
         case name
         when 'edge'
@@ -44,20 +38,14 @@ module RGL
           @graph.add_vertex(attrs['id'])
         end
       end
-
     end		# class MutableGraphParser
-        
-    def MutableGraph.append_features (includingClass)
-      super
-
-      # Create a new MutableGraph from the XML-Source _source_.
 
-      def includingClass.from_graphxml (source)
-        listener = MutableGraphParser.new(self.new)
-        REXML::Document.parse_stream(source, listener)
-        listener.graph
-      end
+    # Initializes an RGL graph from a subset of the GraphML format given in
+    # +source+ (see http://www.graphdrawing.org/graphml).
+    def from_graphxml(source)
+      listener = MutableGraphParser.new(self)
+      REXML::Document.parse_stream(source, listener)
+      self
     end
-
-  end                           # module GraphXML
+  end                           # module MutableGraph
 end                             # module RGL

data/lib/rgl/mutable.rb

@@ -6,7 +6,6 @@ module RGL
 
   # A MutableGraph can be changed via the addition or removal of edges and
   # vertices. 
-
   module MutableGraph
 
     include Graph
@@ -71,5 +70,34 @@ module RGL
       a.each { |v| remove_vertex v }
     end
 
+    # Returns all minimum cycles that pass through a give vertex. 
+    # The format is an Array of cycles, with each cycle being an Array
+    # of vertices in the cycle.
+    def cycles_with_vertex(vertex)
+      cycles_with_vertex_helper(vertex, vertex, [])
+    end
+
+  protected
+    def cycles_with_vertex_helper(vertex, start, visited) #:nodoc:
+      adjacent_vertices(start).reject {|x| visited.include?(x)}.inject([]) do |acc, adj|
+        local_visited = Array.new(visited) << adj
+        acc << local_visited if (adj==vertex)
+        acc = acc + cycles_with_vertex_helper(vertex,adj,local_visited)
+      end
+    end
+
+  public
+    # Returns an array of all minimum cycles in a graph
+    #
+    # This is not an efficient implementation O(n^4) and could
+    # be done using Minimum Spanning Trees. Hint. Hint.
+    def cycles
+      g = self.clone
+      self.inject([]) do |acc, v| 
+        acc = acc.concat(g.cycles_with_vertex(v))
+        g.remove_vertex(v); acc
+      end
+    end
+
   end		# module MutableGraph
 end		# module RGL

data/lib/rgl/rdot.rb

@@ -1,33 +1,16 @@
-# rdot.rb
-# 
-# $Id: rdot.rb,v 1.4 2005/03/26 15:06:36 wsdng Exp $
-#
 # This is a modified version of dot.rb from Dave Thomas's rdoc project.  I
 # renamed it to rdot.rb to avoid collision with an installed rdoc/dot.
 #
 # It also supports undirected edges.
 
 module DOT
-    
-  # These glogal vars are used to make nice graph source.
-
-  $tab  = '    '
-  $tab2 = $tab * 2
-    
-  # if we don't like 4 spaces, we can change it any time
 
-  def change_tab (t)
-    $tab  = t
-    $tab2 = t * 2
-  end
-    
   # options for node declaration
 
   NODE_OPTS = [
     # attributes due to
     # http://www.graphviz.org/Documentation/dotguide.pdf
-    # March, 26, 2005
-    'bottomlabel', # auxiliary label for nodes of shape M*
+    # February 23, 2008
     'color', # default: black; node shape color
     'comment', # any string (format-dependent)
     'distortion', # default: 0.0; node distortion for shape=polygon
@@ -36,7 +19,7 @@ module DOT
     'fontcolor', # default: black; type face color
     'fontname', # default: Times-Roman; font family
     'fontsize', #default: 14; point size of label
-    'group', # name of node�s group
+    'group', # name of node's group
     'height', # default: .5; height in inches
     'label', # default: node name; any string
     'layer', # default: overlay range; all, id or id:id
@@ -48,16 +31,17 @@ module DOT
     'sides', # default: 4; number of sides for shape=polygon
     'skew' , # default: 0.0; skewing of node for shape=polygon
     'style', # graphics options, e.g. bold, dotted, filled; cf. Section 2.3
-    'toplabel', # auxiliary label for nodes of shape M*
     'URL', # URL associated with node (format-dependent)
     'width', # default: .75; width in inches
     'z', #default: 0.0; z coordinate for VRML output
 
     # maintained for backward compatibility or rdot internal
+    'bottomlabel', # auxiliary label for nodes of shape M*
     'bgcolor',
-    'rank'
+    'rank',
+    'toplabel' # auxiliary label for nodes of shape M*
   ]
-    
+
   # options for edge declaration
 
   EDGE_OPTS = [
@@ -97,192 +81,286 @@ module DOT
     # maintained for backward compatibility or rdot internal
     'id'
   ]
-    
+
   # options for graph declaration
 
   GRAPH_OPTS = [
-    'bgcolor',
-    'center', 'clusterrank', 'color', 'concentrate',
-    'fontcolor', 'fontname', 'fontsize',
-    'label', 'layerseq',
-    'margin', 'mclimit',
-    'nodesep', 'nslimit',
-    'ordering', 'orientation',
-    'page',
-    'rank', 'rankdir', 'ranksep', 'ratio',
-    'size'
-  ]
-    
-  # a root class for any element in dot notation
-
-  class DOTSimpleElement
-
-    attr_accessor :name
-
-    def initialize (params = {})
-      @label = params['name'] ? params['name'] : ''
-    end
-
-    def to_s
-      @name
-    end
-  end
-    
-  # an element that has options ( node, edge, or graph )
+    'bgcolor', # background color for drawing, plus initial fill color
+    'center', # default: false; center draing on page
+    'clusterrank', # default: local; may be "global" or "none"
+    'color', # default: black; for clusters, outline color, and fill color if
+             # fillcolor not defined
+    'comment', # any string (format-dependent)
+    'compound', # default: false; allow edges between clusters
+    'concentrate', # default: false; enables edge concentrators
+    'fillcolor', # default: black; cluster fill color
+    'fontcolor', # default: black; type face color
+    'fontname', # default: Times-Roman; font family
+    'fontpath', # list of directories to search for fonts
+    'fontsize', # default: 14; point size of label
+    'label', # any string
+    'labeljust', # default: centered; "l" and "r" for left- and right-justified
+                 # cluster labels, respectively
+    'labelloc', # default: top; "t" and "b" for top- and bottom-justified
+                # cluster labels, respectively
+    'layers', # id:id:id...
+    'margin', # default: .5; margin included in page, inches
+    'mclimit', # default: 1.0; scale factor for mincross iterations
+    'nodesep', # default: .25; separation between nodes, in inches.
+    'nslimit', # if set to "f", bounds network simplex iterations by
+               # (f)(number of nodes) when setting x-coordinates
+    'nslimit1', # if set to "f", bounds network simplex iterations by
+                # (f)(number of nodes) when ranking nodes
+    'ordering', # if "out" out edge order is preserved
+    'orientation', # default: portrait; if "rotate" is not used and the value is
+                   # "landscape", use landscape orientation
+    'page', # unit of pagination, e.g. "8.5,11"
+    'rank', # "same", "min", "max", "source", or "sink"
+    'rankdir', # default: TB; "LR" (left to right) or "TB" (top to bottom)
+    'ranksep', # default: .75; separation between ranks, in inches.
+    'ratio', # approximate aspect ratio desired, "fill" or "auto"
+    'samplepoints', # default: 8; number of points used to represent ellipses
+                    # and circles on output
+    'searchsize', # default: 30; maximum edges with negative cut values to check
+                  # when looking for a minimum one during network simplex
+    'size', # maximum drawing size, in inches
+    'style', # graphics options, e.g. "filled" for clusters
+    'URL', # URL associated with graph (format-dependent)
 
-  class DOTElement < DOTSimpleElement
+    # maintained for backward compatibility or rdot internal
+    'layerseq'
+  ]
 
-    # attr_reader :parent
+  # Ancestor of DOTEdge, DOTNode, and DOTGraph.
+  class DOTElement
     attr_accessor :name, :options
 
-    def initialize (params = {}, option_list = [])
-      super(params)
-      @name   = params['name']   ? params['name']   : nil 
-      @parent = params['parent'] ? params['parent'] : nil
+    def initialize (params = {}, option_list = []) # :nodoc:
+      @name   = params['name']   ? params['name']   : nil
       @options = {}
       option_list.each{ |i|
         @options[i] = params[i] if params[i]
       }
-      @options['label'] ||= @name if @name != 'node'
-    end
-        
-    def each_option
-      @options.each{ |i| yield i }
     end
 
-    def each_option_pair
-      @options.each_pair{ |key, val| yield key, val }
-    end
+    private
+      # Returns the string given in _id_ within quotes if necessary. Special
+      # characters are escaped as necessary.
+      def quote_ID(id)
+        # Ensure that the ID is a string.
+        id = id.to_s
+
+        # Return the ID verbatim if it looks like a name, a number, or HTML.
+        return id if id =~ /^([[:alpha:]_][[:alnum:]_]*|-?(\.[[:digit:]]+|[[:digit:]]+(\.[[:digit:]]*)?)|<.*>)$/
 
-    #def parent=( thing )
-    #    @parent.delete( self ) if defined?( @parent ) and @parent
-    #    @parent = thing
-    #end
+        # Return a quoted version of the ID otherwise.
+        '"' + id.gsub('\\', '\\\\\\\\').gsub('"', '\\\\"') + '"'
+      end
 
+      # Returns the string given in _label_ within quotes if necessary. Special
+      # characters are escaped as necessary. Labels get special treatment in
+      # order to handle embedded *\n*, *\r*, and *\l* sequences which are copied
+      # into the new string verbatim.
+      def quote_label(label)
+        # Ensure that the label is a string.
+        label = label.to_s
+
+        # Return the label verbatim if it looks like a name, a number, or HTML.
+        return label if label =~ /^([[:alpha:]_][[:alnum:]_]*|-?(\.[[:digit:]]+|[[:digit:]]+(\.[[:digit:]]*)?)|<.*>)$/
+
+        # Return a quoted version of the label otherwise.
+        '"' + label.split(/(\\n|\\r|\\l)/).collect do |part|
+          case part
+          when "\\n", "\\r", "\\l"
+            part
+          else
+            part.gsub('\\', '\\\\\\\\').gsub('"', '\\\\"').gsub("\n", '\\n')
+          end
+        end.join + '"'
+      end
   end
-    
-    
-  # This is used when we build nodes that have shape=record
-  # ports don't have options :)
-
-  class DOTPort < DOTSimpleElement
-
-    attr_accessor :label
-        
-    def initialize (params = {})
-      super(params)
-      @name = params['label'] ? params['label'] : ''
+
+
+  # Ports are used when a DOTNode instance has its `shape' option set to
+  # _record_ or _Mrecord_.  Ports can be nested.
+  class DOTPort
+    attr_accessor :name, :label, :ports
+
+    # Create a new port with either an optional name and label or a set of
+    # nested ports.
+    #
+    # :call-seq:
+    #   new(name = nil, label =  nil)
+    #   new(ports)
+    #
+    # A +nil+ value for +name+ is valid; otherwise, it must be a String or it
+    # will be interpreted as +ports+.
+    def initialize (name_or_ports = nil, label = nil)
+      if name_or_ports.nil? or name_or_ports.kind_of?(String) then
+        @name = name_or_ports
+        @label = label
+        @ports = nil
+      else
+        @ports = name_or_ports
+        @name = nil
+        @label = nil
+      end
     end
 
+    # Returns a string representation of this port.  If ports is a non-empty
+    # Enumerable, a nested ports representation is returned; otherwise, a
+    # name-label representation is returned.
     def to_s
-      ( @name && @name != "" ? "<#{@name}>" : "" ) + "#{@label}"
+      if @ports.nil? or @ports.empty? then
+        n = (name.nil? or name.empty?) ? '' : "<#{name}>"
+        n + ((n.empty? or label.nil? or label.empty?) ? '' : ' ') + label.to_s
+      else
+        '{' + @ports.collect {|p| p.to_s}.join(' | ') + '}'
+      end
     end
   end
-    
-  # node element
 
+  # A node representation.  Edges are drawn between nodes.  The rendering of a
+  # node depends upon the options set for it.
   class DOTNode < DOTElement
+    attr_accessor :ports
 
-    @ports
-
+    # Creates a new DOTNode with the _params_ Hash providing settings for all
+    # node options. The _option_list_ parameter restricts those options to the
+    # list of valid names it contains. The exception to this is the _ports_
+    # option which, if specified, must be an Enumerable containing a list of
+    # ports.
     def initialize (params = {}, option_list = NODE_OPTS)
       super(params, option_list)
       @ports = params['ports'] ? params['ports'] : []
     end
 
-    def each_port
-      @ports.each { |i| yield i }
-    end
-
-    def << (thing)
-      @ports << thing
-    end
-
-    def push (thing)
-      @ports.push(thing)
-    end
-
-    def pop
-      @ports.pop
-    end
+    # Returns a string representation of this node which is consumable by the
+    # graphviz tools +dot+ and +neato+. The _leader_ parameter is used to indent
+    # every line of the returned string, and the _indent_ parameter is used to
+    # additionally indent nested items.
+    def to_s (leader = '', indent = '    ')
+      label_option = nil
+      if @options['shape'] =~ /^M?record$/ && !@ports.empty? then
+        # Ignore the given label option in this case since the ports should each
+        # provide their own name/label.
+        label_option = leader + indent + "#{quote_ID('label')} = #{quote_ID(@ports.collect { |port| port.to_s }.join(" | "))}"
+      elsif @options['label'] then
+        # Otherwise, use the label when given one.
+        label_option = leader + indent + "#{quote_ID('label')} = #{quote_label(@options['label'])}"
+      end
 
-    def to_s (t = '')
-
-      # This code is totally incomprehensible; it needs to be replaced!
-
-      label = @options['shape'] != 'record' && @ports.length == 0 ?
-                @options['label'] ? 
-                    t + $tab + "label = \"#{@options['label']}\"\n" :
-                    '' :
-                t + $tab + 'label = "' + " \\\n" +
-                t + $tab2 + "#{@options['label']}| \\\n" +
-                @ports.collect{ |i|
-                    t + $tab2 + i.to_s
-                }.join( "| \\\n" ) + " \\\n" +
-                t + $tab + '"' + "\n"
-            
-            t + "#{@name} [\n" +
-            @options.to_a.collect{ |i|
-                i[1] && i[0] != 'label' ? 
-                    t + $tab + "#{i[0]} = #{i[1]}" : nil
-            }.compact.join( ",\n" ) + ( label != '' ? ",\n" : "\n" ) + 
-            label +
-            t + "]\n" 
+      # Convert all the options except `label' and options with nil values
+      # straight into name = value pairs.  Then toss out any resulting nil
+      # entries in the final array.
+      stringified_options = @options.collect do |name, val|
+        unless name == 'label' || val.nil? then
+          leader + indent + "#{quote_ID(name)} = #{quote_ID(val)}"
+        end
+      end.compact
+      # Append the specially computed label option.
+      stringified_options.push(label_option) unless label_option.nil?
+      # Join them all together.
+      stringified_options = stringified_options.join(",\n")
+
+      # Put it all together into a single string with indentation and return the
+      # result.
+      if stringified_options.empty? then
+        return leader + quote_ID(@name) unless @name.nil?
+        return nil
+      else
+        return leader + (@name.nil? ? '' : quote_ID(@name) + " ") + "[\n" +
+          stringified_options + "\n" +
+          leader + "]"
       end
+    end
 
   end		# class DOTNode
 
-  # A subgraph element is the same to graph, but has another header in dot
-  # notation.
-
-  class DOTSubgraph < DOTElement
-
-    @nodes
-    @dot_string
+  # A graph representation. Whether or not it is rendered as directed or
+  # undirected depends on which of the programs *dot* or *neato* is used to
+  # process and render the graph.
+  class DOTGraph < DOTElement
 
+    # Creates a new DOTGraph with the _params_ Hash providing settings for all
+    # graph options. The _option_list_ parameter restricts those options to the
+    # list of valid names it contains. The exception to this is the _elements_
+    # option which, if specified, must be an Enumerable containing a list of
+    # nodes, edges, and/or subgraphs.
     def initialize (params = {}, option_list = GRAPH_OPTS)
       super(params, option_list)
-      @nodes      = params['nodes'] ? params['nodes'] : []
+      @elements   = params['elements'] ? params['elements'] : []
       @dot_string = 'graph'
     end
 
-    def each_node
-      @nodes.each{ |i| yield i }
+    # Calls _block_ once for each node, edge, or subgraph contained by this
+    # graph, passing the node, edge, or subgraph to the block.
+    #
+    # :call-seq:
+    #   graph.each_element {|element| block} -> graph
+    #
+    def each_element (&block)
+      @elements.each(&block)
+      self
     end
 
-    def << (thing)
-      @nodes << thing
-    end
-       
-    def push (thing)
-      @nodes.push( thing )
+    # Adds a new node, edge, or subgraph to this graph.
+    #
+    # :call-seq:
+    #   graph << element -> graph
+    #
+    def << (element)
+      @elements << element
+      self
     end
-
+    alias :push :<<
+
+    # Removes the most recently added node, edge, or subgraph from this graph
+    # and returns it.
+    #
+    # :call-seq:
+    #   graph.pop -> element
+    #
     def pop
-      @nodes.pop
+      @elements.pop
     end
 
-    def to_s (t = '')
-      hdr = t + "#{@dot_string} #{@name} {\n"
-
-      options = @options.to_a.collect{ |name, val|
-        val && name != 'label' ? 
-          t + $tab + "#{name} = #{val}" : 
-          name ? t + $tab + "#{name} = \"#{val}\"" : nil
-      }.compact.join( "\n" ) + "\n"
-
-      nodes = @nodes.collect{ |i|
-        i.to_s( t + $tab )
-      }.join( "\n" ) + "\n" 
-      hdr + options + nodes + t + "}\n"
+    # Returns a string representation of this graph which is consumable by the
+    # graphviz tools +dot+ and +neato+. The _leader_ parameter is used to indent
+    # every line of the returned string, and the _indent_ parameter is used to
+    # additionally indent nested items.
+    def to_s (leader = '', indent = '    ')
+      hdr = leader + @dot_string + (@name.nil? ? '' : ' ' + quote_ID(@name)) + " {\n"
+
+      options = @options.to_a.collect do |name, val|
+        unless val.nil? then
+          if name == 'label' then
+            leader + indent + "#{quote_ID(name)} = #{quote_label(val)}"
+          else
+            leader + indent + "#{quote_ID(name)} = #{quote_ID(val)}"
+          end
+        end
+      end.compact.join( "\n" )
+
+      elements = @elements.collect do |element|
+        element.to_s(leader + indent, indent)
+      end.join("\n\n")
+      hdr + (options.empty? ? '' : options + "\n\n") +
+        (elements.empty? ? '' : elements + "\n") + leader + "}"
     end
 
-  end		# class DOTSubgraph
-
-  # This is a graph.
+  end		# class DOTGraph
 
-  class DOTDigraph < DOTSubgraph
+  # A digraph is a directed graph representation which is the same as a DOTGraph
+  # except that its header in dot notation has an identifier of _digraph_
+  # instead of _graph_.
+  class DOTDigraph < DOTGraph
 
+    # Creates a new DOTDigraph with the _params_ Hash providing settings for all
+    # graph options.  The _option_list_ parameter restricts those options to the
+    # list of valid names it contains. The exception to this is the _elements_
+    # option which, if specified, must be an Enumerable containing a list of
+    # nodes, edges, and/or subgraphs.
     def initialize (params = {}, option_list = GRAPH_OPTS)
       super(params, option_list)
       @dot_string = 'digraph'
@@ -290,38 +368,78 @@ module DOT
 
   end		# class DOTDigraph
 
-  # This is an edge.
+  # A subgraph is a nested graph element and is the same as a DOTGraph except
+  # that its header in dot notation has an identifier of _subgraph_ instead of
+  # _graph_.
+  class DOTSubgraph < DOTGraph
+
+    # Creates a new DOTSubgraph with the _params_ Hash providing settings for
+    # all graph options.  The _option_list_ parameter restricts those options to
+    # list of valid names it contains. The exception to this is the _elements_
+    # option which, if specified, must be an Enumerable containing a list of
+    # nodes, edges, and/or subgraphs.
+    def initialize (params = {}, option_list = GRAPH_OPTS)
+      super(params, option_list)
+      @dot_string = 'subgraph'
+    end
+
+  end		# class DOTSubgraph
 
+  # This is an undirected edge representation.
   class DOTEdge < DOTElement
 
-    attr_accessor :from, :to
+    # A node or subgraph reference or instance to be used as the starting point
+    # for an edge.
+    attr_accessor :from
+    # A node or subgraph reference or instance to be used as the ending point
+    # for an edge.
+    attr_accessor :to
 
+    # Creates a new DOTEdge with the _params_ Hash providing settings for all
+    # edge options.  The _option_list_ parameter restricts those options to the
+    # list of valid names it contains.
     def initialize (params = {}, option_list = EDGE_OPTS)
       super(params, option_list)
       @from = params['from'] ? params['from'] : nil
       @to   = params['to'] ? params['to'] : nil
     end
-       
-    def edge_link
-      '--'
-    end
 
-    def to_s (t = '')
-      t + "#{@from} #{edge_link} #{to} [\n" +
-          @options.to_a.collect{ |i|
-            i[1] && i[0] != 'label' ? 
-              t + $tab + "#{i[0]} = #{i[1]}" : 
-              i[1] ? t + $tab + "#{i[0]} = \"#{i[1]}\"" : nil
-          }.compact.join( "\n" ) + "\n" + t + "]\n"
+    # Returns a string representation of this edge which is consumable by the
+    # graphviz tools +dot+ and +neato+. The _leader_ parameter is used to indent
+    # every line of the returned string, and the _indent_ parameter is used to
+    # additionally indent nested items.
+    def to_s (leader = '', indent = '    ')
+      stringified_options = @options.collect do |name, val|
+        unless val.nil? then
+          leader + indent + "#{quote_ID(name)} = #{quote_ID(val)}"
+        end
+      end.compact.join( ",\n" )
+
+      f_s = @from || ''
+      t_s = @to || ''
+      if stringified_options.empty? then
+        leader + quote_ID(f_s) + ' ' + edge_link + ' ' + quote_ID(t_s)
+      else
+        leader + quote_ID(f_s) + ' ' + edge_link + ' ' + quote_ID(t_s) + " [\n" +
+          stringified_options + "\n" +
+          leader + "]"
+      end
     end
 
+    private
+      def edge_link
+        '--'
+      end
+
   end		# class DOTEdge
-          
+
+  # A directed edge representation otherwise identical to DOTEdge.
   class DOTDirectedEdge < DOTEdge
 
-    def edge_link
-      '->'
-    end
+    private
+      def edge_link
+        '->'
+      end
 
   end                           # class DOTDirectedEdge
 end                             # module DOT