GraphvizR 0.3.1 → 0.3.2

data/History.txt

@@ -1,3 +1,7 @@
+== 0.3.2 / 2007-02-21
+
+* add rdoc comments
+
 == 0.3.1 / 2007-02-19
 
 * fixed a bug

data/README.txt

@@ -46,7 +46,7 @@ To know more detail, please see test/test_graphviz_r.rb
 
 === On Rails :
 
-*use _render :rdot_ in controller*
+<b>use _render :rdot_ in controller</b>
 
   def show_graph
     render :rdot do
@@ -61,7 +61,7 @@ To know more detail, please see test/test_graphviz_r.rb
     end
   end
 
-*use rdot view template*
+<b>use rdot view template</b>
 
   class RdotGenController < ApplicationController
     def index
@@ -82,7 +82,7 @@ To know more detail, please see test/test_graphviz_r.rb
 
 == DEPENDENCIES:
 
-* Graphviz (http://www.graphviz.org/)
+* Graphviz (http://www.graphviz.org)
 
 == TODO:
 

data/lib/graphviz_r.rb

@@ -1,8 +1,122 @@
+# GraphvizR is graphviz adapter for Ruby, and it can:
+# * generate a graphviz dot file, and
+# * generate an image file directly.
+#
+# A sample code to generate dot file is:
+#
+#   gvr = GraphvizR.new 'sample'
+#   gvr.graph [:label => 'example', :size => '1.5, 2.5'] 
+#   gvr.alpha >> gvr.beta
+#   gvr.beta >> gvr.delta
+#   gvr.delta >> gvr.gamma
+#   gvr.to_dot
+#
+# The code generates a dot file look like:
+#
+#   digraph sample {
+#     graph [label = "example", size = "1.5, 2.5"];
+#     beta [shape = box];
+#     alpha -> beta;
+#     beta -> delta;
+#     delta -> gamma;
+#   }
+#
+# == Node
+#
+# A node can be created by method calling or array accessing to GraphvizR instance. In short,
+# both <tt>gvr.abc</tt> and <tt>gvr[:abc]</tt> generate the <tt>abc</tt> node in dot file.
+#
+# == Edge
+#
+# An edge is generated by <tt>&gt;&gt;</tt> of <tt>-</tt> method calling to a node; the former
+# generate a directed graph while the latter a undirected one. For example,
+#   gvr = GraphvizR.new 'sample'
+#   gvr.alpha >> gvr.beta
+# generates
+#   diagraph sample {
+#     alpla -> beta
+#   }
+# while
+#   gvr = GraphvizR.new 'sample'
+#   gvr.alpha - gvr.beta
+# generates
+#   graph sample {
+#     alpla -- beta
+#   }
+#
+# == Graph Attributes
+# 
+# Attributes are specified by Hash in []. Thus, to set the fillcolor of a node abc, one would use
+#   gvr = GraphvizR.new 'sample'
+#   gvr.abc [:fillcolor => :red]
+#
+# Similarly, to set the arrowhead style of an edge abc -> def, one would use
+#   (gvr.abc >> gvr.def) [:arrowhead => :diamond]
+#
+# As you can expect, to set graph attributes, one would use
+#   gvr.graph [:label => 'example', :size => '1.5, 2.5'] 
+#
+# == Record
+#
+# To set a record label on a node, you can use ordinary [] method.
+#   gvr.node1 [:label => "<p_left> left|<p_center>center|<p_right> right"]
+#
+# To access a record in a node, you can use method calling whose argumemts is the name of a record.
+#   gvr.node1(:p_left) >> gvr.node2
+#
+# Accordingly, a full example looks like:
+#   gvr = GraphvizR.new 'sample'
+#   gvr.node [:shape => :record]
+#   gvr.node1 [:label => "<p_left> left|<p_center>center|<p_right> right"]
+#   gvr.node2
+#   gvr.node1(:p_left) >> gvr.node2
+#   gvr.node2 >> gvr.node1(:p_center)
+#   (gvr.node2 >> gvr.node1(:p_right)) [:label => 'record']
+#   gvr.to_dot
+#
+# == Subgraph
+#
+# Subgraph is a way to construct hierarchical graph in graphviz. GraphvizR allows you to use 
+# subgraphs by means of method calling with a block which has one argument. For example,
+#   gvr = GraphvizR.new 'sample'
+#   gvr.cluster0 do |c0|
+#     c0.graph [:color => :blue, :label => 'area 0', :style => :bold]
+#     c0.a >> c0.b
+#     c0.a >> c0.c
+#   end
+#   gvr.cluster1 do |c1|
+#     c1.graph [:fillcolor => '#cc9966', :label => 'area 1', :style => :filled]
+#     c1.d >> c1.e
+#     c1.d >> c1.f
+#   end
+#   (gvr.a >> gvr.f) [:lhead => :cluster1, :ltail => :cluster0]
+#   gvr.b >> gvr.d
+#   (gvr.c >> gvr.d) [:ltail => :cluster0]
+#   (gvr.c >> gvr.f) [:lhead => :cluster1]
+#   gvr.to_dot
+# generates
+#   digraph sample {
+#     subgraph cluster0 {
+#       graph [color = blue, label ="area 0", style = bold];
+#       a -> b;
+#       a -> c;
+#     }
+#     subgraph cluster1 {
+#       graph [fillcolor = "#cc9966", label = "area 1", style = filled];
+#       d -> e;
+#       d -> f;
+#     }
+#     a -> f [lhead = cluster1, ltail = cluster0];
+#     b -> d;
+#     c -> d [ltail = cluster0];
+#     c -> f [lhead = cluster1];
+#
 class GraphvizR
-  VERSION = '0.3.1'
+  VERSION = '0.3.2'
   INDENT_UNIT = '  '
 
-  class Attributes
+  # This represents graphviz attributes.
+  class Attributes 
     def initialize(name, dot)
       @name = name
       @dot = dot
@@ -13,6 +127,7 @@ class GraphvizR
     end
   end
 
+  # This represents graphviz node.
   class Node
     attr_reader :prop, :name
 
@@ -27,11 +142,13 @@ class GraphvizR
       end
     end
 
+    # This generates a directed edge from this node to given node.
     def >>(node)
       @dot.directed!
       add_edge_on_dot node
     end
 
+    # This generates a undirected edge from this node to given node.
     def -(node)
       @dot.undirected!
       add_edge_on_dot node
@@ -65,6 +182,7 @@ class GraphvizR
     end
   end
 
+  # This represents a graphviz edge.
   class Edge
     def initialize(from, to, dot, prop={})
       @from = from
@@ -92,10 +210,65 @@ class GraphvizR
     end
   end
 
+  # This returns dot formatted string from given properties. To know more about <tt>prop</tt>,
+  # please see GraphvizR.new .
   def self.dot(name, prop)
     GraphvizR.new(name, prop).to_dot
   end
 
+  # This initialzes a GraphvizR instance.
+  # +name+:: the name of the graph
+  # +prop+:: <b>!deprecated!</b> all properties for a graph can be given as a hash instance.
+  #          Please guess the contents of the hash from the test or examples below:
+  #            gvr = GraphvizR.dot(:sample, 
+  #              :graph => {:size => "1.5, 2.5"},
+  #              :label => 'example',
+  #              :node_properties => {
+  #                :beta => {:shape => :box},
+  #              },
+  #              :alpha => :beta,
+  #              {:alpha => :gamma} => {:label => 'label1'},
+  #              :beta => :delta,
+  #              :delta => 'size'
+  #            )
+  #
+  #      gvr = GraphvizR.dot(:sample, 
+  #              :graph => {:size => "1.5, 2.5"},
+  #              :node => {:shape => :record},
+  #              :node_properties => {
+  #                :node1 => {:label => "<p_left> left|<p_center>center|<p_right> right"},
+  #                :node2 => {:label => "left|center|right"}
+  #              },
+  #              :node1 => :node2,
+  #              [:node1, :p_left] => :node2,
+  #              :node2 => [:node1, :p_center],
+  #              {:node2 => [:node1, :p_right]} => {:label => 'record'}
+  #            )
+  #
+  #      gvr = GraphvizR.dot(:sample, 
+  #              :subgraphs => {
+  #                :cluster0 => {
+  #                  :color => :blue,
+  #                  :style => :bold,
+  #                  :label => "area 0",
+  #                  {:a => :b} => {},
+  #                  :a => :c
+  #                },
+  #                :cluster1 => {
+  #                  :fillcolor => "#cc9966",
+  #                  :style => :filled,
+  #                  :label => "area 1",
+  #                  [:d] => :e,
+  #                  :d => :f
+  #                }
+  #              },
+  #              :b => :d,
+  #              {:c => :d} => {:ltail => :cluster0},
+  #              {:c => :f} => {:lhead => :cluster1},
+  #              {:a => :f} => {:ltail => :cluster0, :lhead => :cluster1}
+  #            )
+  # +parent+:: a parent graph is given when this graph is a subgraph.
+  # +indent+:: indent level when this instance is converted to rdot.
   def initialize(name, prop={}, parent=nil, indent=0)
     if name.is_a? Array
       initialize(*name)
@@ -113,7 +286,7 @@ class GraphvizR
     end
   end
 
-  def interprete(prop)
+  def interprete(prop) #:nodoc:
     prop.each do |k, v|
       case k
       when :node_property, :node_properties
@@ -132,10 +305,12 @@ class GraphvizR
     end
   end
 
+  # add properties for nodes
   def add_node_properties(props)
     @node_properties = props
   end
 
+  # add an edge to the graph
   def add_edge(from, to=nil)
     if from.is_a? Hash
       f = from.keys[0]
@@ -150,16 +325,19 @@ class GraphvizR
     end
   end
 
+  # add subgraph
   def add_subgraph(graphs)
     graphs.to_a.sort.each do |key_prop|
       @subgraphs << self.class.new(key_prop[0], key_prop[1], self, @indent)
     end
   end
   
+  # is this graph subgraph or not.
   def subgraph?
     not @parent.nil?
   end
 
+  # make this graph directed
   def directed!
     if subgraph?
       @parent.directed!
@@ -168,6 +346,7 @@ class GraphvizR
     end
   end
 
+  # make this graph undirected
   def undirected!
     if subgraph?
       @parent.undirected!
@@ -176,6 +355,7 @@ class GraphvizR
     end
   end
 
+  # is this graph directed?
   def directed?
     if subgraph?
       @parent.directed?
@@ -184,6 +364,7 @@ class GraphvizR
     end
   end
 
+  # is this graph undirected?
   def undirected?
     if subgraph?
       @parent.undirected?
@@ -192,6 +373,7 @@ class GraphvizR
     end
   end
 
+  # When block is given, create new subgraph. Otherwise, create new node.
   def [](key, *args, &block)
     if block
       subgraph = self.class.new key, {}, self, @indent
@@ -202,6 +384,7 @@ class GraphvizR
     end
   end
 
+  # set properties for a node
   def []=(key, *args, &block)
     @node_properties[key] = args[0]
   end
@@ -212,6 +395,7 @@ class GraphvizR
     end
   end
 
+  # set graph properties
   def graph(*args)
     if args.empty?
       Attributes.new :graph, self
@@ -220,21 +404,16 @@ class GraphvizR
     end
   end
 
+  # set graph properties
   def graph=(prop)
     @graph_properties.merge! prop
   end
 
+  # convert this instance to dot
   def to_dot
-    graph_type = if subgraph?
-                   'subgraph'
-                 elsif directed?
-                   'digraph'
-                 else
-                   'graph'
-                 end
+    graph_type = if subgraph?; 'subgraph'elsif directed?; 'digraph' else 'graph' end
     dot = indent_enter("#{graph_type} #{@name} {", true)
     dot += indent_enter("graph #{@graph_properties.to_dot};") unless @graph_properties.empty?
-    #dot += indent_enter(@subgraphs.map{|e| e.to_dot}.join("\n")) unless @subgraphs.empty?
     dot += @subgraphs.map{|e| e.to_dot}.join('') unless @subgraphs.empty?
     dot += properties_to_dot(@default_node_properties) unless @default_node_properties.empty?
     dot += properties_to_dot(@node_properties) unless @node_properties.empty?
@@ -243,10 +422,13 @@ class GraphvizR
     dot
   end
 
-  def indent_enter(str, is_first=false)
+  def indent_enter(str, is_first=false) #:nodoc:
     "#{INDENT_UNIT * (@indent - (is_first ? 1 : 0))}#{str}\n"
   end
 
+  # If <tt>format</tt> is 'dot', a dot string is generated. Otherwise, this generates image file
+  # in the given format, such as 'png', 'gif', 'jpg', and so on. To know correctly, please see 
+  # the specification of graphviz: http://www.graphviz.org/doc/info/output.html
   def data(format='png')
     format = format.to_s
     if format == 'dot'
@@ -263,6 +445,7 @@ class GraphvizR
     end
   end
 
+  # store image data created from this instance to given file.
   def output(filename=nil, format='png')
     img = data(format)
     File.open(filename || "#{@name}.#{format || 'png'}", "w+") do |file|
@@ -270,7 +453,7 @@ class GraphvizR
     end
   end
 
-  def method_missing(name, *args, &block)
+  def method_missing(name, *args, &block) #:nodoc:
     method = 
     if name.to_s =~ /=$/
       name = name.to_s[0..-2].to_sym
@@ -283,24 +466,24 @@ class GraphvizR
 
 protected
 
-  def properties_to_dot(hash)
+  def properties_to_dot(hash) #:nodoc:
     hash.to_a.sort.map{|e| indent_enter "#{e[0]} #{e[1].to_dot};"}.join()
   end
 end
 
-class Number
+class Number #:nodoc:
   def to_dot
     to_s
   end
 end
 
-class String
+class String #:nodoc:
   def to_dot
     inspect
   end
 end
 
-class Symbol
+class Symbol #:nodoc:
   def to_dot
     to_s
   end
@@ -310,7 +493,7 @@ class Symbol
   end
 end
 
-class Hash
+class Hash #:nodoc:
   def to_dot
     "[#{to_a.sort.map{|e| "#{e[0].to_dot} = #{e[1].to_dot}"}.join(', ')}]"
   end

data/vendor/plugins/rdot/lib/rdot.rb

@@ -1,7 +1,7 @@
 require 'graphviz_r'
 
 class ActionController::Base
-  def render_with_rdot(options = nil, deprecated_status = nil, &block)
+  def render_with_rdot(options = nil, deprecated_status = nil, &block) #:nodoc:
     if options == :rdot
       render_rdot deprecated_status, &block
     else
@@ -11,7 +11,35 @@ class ActionController::Base
   #alias_method_chain :render, :rdot
   alias_method :render_without_rdot, :render
   alias_method :render, :render_with_rdot
-  
+
+  # render rdot. <tt>options</tt> hash can have <tt>:format</tt> and <tt>:disposition</tt>,
+  # and their default values are 'png' and 'inline' respectively.
+  #
+  # rdot is directed in given block and the block can have zero or one argument.
+  # If any argument is not given, only local variables can be refered in the block.
+  # Otherwise, not only local variables but also instance one can be refered.
+  #
+  #   class RdotGenController < ApplicationController
+  #     def index
+  #       graph_size_directed_as_local_variable = '1.5, 2.5'
+  #
+  #       render :rdot do
+  #         graph [:size => graph_size_directed_as_local_variable]
+  #         node1 >> node2
+  #       end
+  #     end
+  #   end
+  #
+  #   class RdotGenController < ApplicationController
+  #     def index
+  #       @graph_size_directed_as_instance_variable = '1.5, 2.5'
+  #
+  #       render :rdot do |gvr|
+  #         gvr.graph [:size => @graph_size_directed_as_instance_variable]
+  #         gvr.node1 >> gvr.node2
+  #       end
+  #     end
+  #   end
   def render_rdot(options=nil, &block)
     options ||= {}
     format = options[:format] || 'png'
@@ -37,7 +65,7 @@ class ActionController::Base
 
 private
 
-  def copy_instance_variables(from_block, to_obj)
+  def copy_instance_variables(from_block, to_obj) #:nodoc:
     block_instance_variables = eval 'instance_variables', from_block.binding
     block_instance_variables.each do |name|
       to_obj.instance_variable_set name.to_sym, eval(name, from_block.binding)

data/vendor/plugins/rdot/lib/rdot_template.rb

@@ -1,8 +1,30 @@
+# Process rdot template.
+#
+# == Rdot Template Example
+#   class RdotGenController < ApplicationController
+#     def index
+#       @label1 = "<p_left> left|<p_center>center|<p_right> right"
+#       @label2 = "left|center|right"
+#     end
+#   end
+#   
+#   # view/rdot_gen/index.rdot
+#   graph [:size => '1.5, 2.5']
+#   node [:shape => :record]
+#   node1 [:label => @label1]
+#   node2 [:label => @label2]
+#   node1 >> node2
+#   node1(:p_left) >> node2
+#   node2 >> node1(:p_center)
+#   (node2 >> node1(:p_right)) [:label => 'record']
+#
+# To know more about rdot, please see the documents for GraphvizR.
 class RdotTemplate
   def initialize(view)
     @view = view
   end
 
+  # render rdot template
   def render(template, local_assigns)
     params = @view.assigns['params']
     format = params['format'] || 'png'

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: GraphvizR
 version: !ruby/object:Gem::Version 
-  version: 0.3.1
-date: 2007-02-19 00:00:00 +09:00
+  version: 0.3.2
+date: 2007-02-21 00:00:00 +09:00
 summary: Graphviz wrapper for Ruby and Rails
 require_paths: 
   - lib
@@ -23,20 +23,20 @@ description: "Graphviz wrapper for Ruby. This can be used as a common library, a
   gvr.gamma gvr.to_dot  replies the dot code:  digraph sample { graph [label =
   \"example\", size = \"1.5, 2.5\"]; beta [shape = box]; alpha -> beta; beta ->
   delta [label = \"label1\"]; delta -> gamma; }  To know more detail, please see
-  test/test_graphviz_r.rb  === On Rails :  *use _render :rdot_ in controller*  def
-  show_graph render :rdot do graph [:size => '1.5, 2.5'] node [:shape => :record]
-  node1 [:label => \"<p_left> left|<p_center>center|<p_right> right\"] node2
-  [:label => \"left|center|right\"] node1 >> node2 node1(:p_left) >> node2 node2
-  >> node1(:p_center) (node2 >> node1(:p_right)) [:label => 'record'] end end 
-  *use rdot view template*  class RdotGenController < ApplicationController def
-  index @label1 = \"<p_left> left|<p_center>center|<p_right> right\" @label2 =
-  \"left|center|right\" end end  # view/rdot_gen/index.rdot graph [:size => '1.5,
-  2.5'] node [:shape => :record] node1 [:label => @label1] node2 [:label =>
-  @label2] node1 >> node2 node1(:p_left) >> node2 node2 >> node1(:p_center) (node2
-  >> node1(:p_right)) [:label => 'record']  == DEPENDENCIES:  * Graphviz
-  (http://www.graphviz.org/)  == TODO:  * cover all specification for graphviz  ==
-  INSTALL:  * sudo gem install graphviz_r * if you want to use this in ruby on
-  rails * script/plugin install
+  test/test_graphviz_r.rb  === On Rails :  <b>use _render :rdot_ in controller</b>
+  def show_graph render :rdot do graph [:size => '1.5, 2.5'] node [:shape =>
+  :record] node1 [:label => \"<p_left> left|<p_center>center|<p_right> right\"]
+  node2 [:label => \"left|center|right\"] node1 >> node2 node1(:p_left) >> node2
+  node2 >> node1(:p_center) (node2 >> node1(:p_right)) [:label => 'record'] end
+  end  <b>use rdot view template</b>  class RdotGenController <
+  ApplicationController def index @label1 = \"<p_left>
+  left|<p_center>center|<p_right> right\" @label2 = \"left|center|right\" end end 
+  # view/rdot_gen/index.rdot graph [:size => '1.5, 2.5'] node [:shape => :record]
+  node1 [:label => @label1] node2 [:label => @label2] node1 >> node2
+  node1(:p_left) >> node2 node2 >> node1(:p_center) (node2 >> node1(:p_right))
+  [:label => 'record']  == DEPENDENCIES:  * Graphviz (http://www.graphviz.org)  ==
+  TODO:  * cover all specification for graphviz  == INSTALL:  * sudo gem install
+  graphviz_r * if you want to use this in ruby on rails * script/plugin install
   http://technohippy.net/svn/repos/graphviz_r/trunk/vendor/plugins/rdot   ==
   LICENSE:  (The MIT License)"
 autorequire: