gv 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: df3b4f9e7e9dc7a1bb1c3f9fc0442c5032772570
-  data.tar.gz: d74223b0a785b75df5aa6ada63c8eaf10b66a2cd
+  metadata.gz: 17e83e14df49d9b53bb2d2d32106be45b59bcfde
+  data.tar.gz: 71612086bd7676a972c8f2de30e7017024694d5d
 SHA512:
-  metadata.gz: 61070b8eac8e61b06d970495df79d49efb46f6612e425228d02ed5c364effb5e0fc9b64f22ac0915db171478f8b86e355f326eadb03e85670fcecdac3d8c24a2
-  data.tar.gz: 8ddeec3c092d86be9f144fa83926a1251456ac7536d1d308e4638c387ef77925001226e3ef7d5ab90b18bfa1609118f5c3cf761e86c48b31f791ac54397e261f
+  metadata.gz: 721459c62dd6543cc5a8510bcfc08c1abe87232dbaa621417537646d5f4b3196164b03027345b2580e00814d2a9d2dc4b5bb62812ede5fc9394023c07f67d962
+  data.tar.gz: fc708e42515acb0102f8ab9bd4d6ebea51d5bd02c8069000b1345b4ecc9e175098d9355b067aa491ac6b8f1900dc046cde4d71ca3db7ee14095cbd1be7be7b34

data/.gemrelease

@@ -0,0 +1,2 @@
+release:
+  tag: true

data/.travis.yml

@@ -0,0 +1,8 @@
+before_install:
+  - sudo add-apt-repository ppa:gviz-adm/graphviz-dev -y
+  - sudo apt-get -qq update
+  - sudo apt-get install -y libgraphviz-dev graphviz libgraphviz4
+language: ruby
+rvm:
+  - 2.3.1
+  - jruby-9.0.5.0

data/README.md

@@ -1,3 +1,7 @@
+[![Gem Version](https://badge.fury.io/rb/gv.svg)](https://badge.fury.io/rb/gv)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/furunkel/gv/master/frames)
+[![Build Status](https://travis-ci.org/furunkel/gv.svg?branch=master)](https://travis-ci.org/furunkel/gv)
+
 # GV
 
 Ruby bindings for libgvc (Graphviz) using FFI.
@@ -25,8 +29,7 @@ Or install it yourself as:
 require 'gv'
 
 graph = GV::Graph.open 'g'
-graph.edge 'e', graph.node('A'), graph.node('B', shape: 'polygon')
-
+graph.edge 'e', graph.node('A'), graph.node('B', shape: 'polygon', label: graph.html('<b>bold</b>'))
 # render to string
 graph.render 'png'
 
@@ -35,7 +38,7 @@ graph.write 'result.png'
 ```
 
 #### Result 
-![resilt](/spec/render.png)
+![Result](https://raw.githubusercontent.com/furunkel/gv/master/spec/render.png)
   
 ### Load existing graph from `.dot` file:
 ```ruby

data/Rakefile

@@ -1,7 +1,14 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
+require 'yard'
 
 Rake::TestTask.new do |t|
   t.libs.push 'lib'
   t.pattern = "spec/*_spec.rb"
-end
+end
+
+
+YARD::Rake::YardocTask.new
+
+
+task :default => :test

data/gv.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.7"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "minitest"
+  spec.add_development_dependency "yard"
 
   spec.add_dependency "ffi"
 end

data/lib/gv.rb

@@ -3,45 +3,34 @@ require 'ffi'
 
 module GV
 
-  module FFI
-    extend ::FFI::Library
+  module LibCGraph
+    extend FFI::Library
 
-    ffi_lib 'gvc', 'cgraph', 'cgraph'
-
-    class AGraph < ::FFI::ManagedStruct
-      # dummy layout, only ever used by reference
-      layout :_1, :int,
-             :_2, :int
+    ffi_lib 'cgraph'
 
+    class AGraph < FFI::AutoPointer
       def self.release(ptr)
-        FFI.agclose(ptr) unless ptr.null?
+        LibCGraph.agclose(ptr) unless ptr.null?
       end
     end
 
-    typedef :pointer, :gvc
+
     typedef :pointer, :ag_node
     typedef :pointer, :ag_edge
 
-    attach_function :gvContext, [], :pointer
-    attach_function :gvFreeLayout, [:gvc, AGraph.by_ref], :int
-    attach_function :gvLayout, [:gvc, AGraph.by_ref, :string], :int
-
-    attach_function :gvRenderFilename, [:gvc, AGraph.by_ref, :string, :string], :int
-    attach_function :gvRenderData, [:gvc, AGraph.by_ref, :string, :pointer, :pointer], :int
-    attach_function :gvFreeRenderData, [:pointer], :void
 
-    attach_function :agmemread, [:string], AGraph.by_ref
-    attach_function :agopen, [:string, :long, :pointer], AGraph.by_ref
-    attach_function :agclose, [AGraph.by_ref], :int
+    attach_function :agmemread, [:string], AGraph
+    attach_function :agopen, [:string, :long, :pointer], AGraph
+    attach_function :agclose, [AGraph], :int
 
     attach_variable :Agundirected, :long
     attach_variable :Agstrictundirected, :long
     attach_variable :Agdirected, :long
     attach_variable :Agstrictdirected, :long
 
-    attach_function :agnode, [AGraph.by_ref, :string, :int], :ag_node
-    attach_function :agedge, [AGraph.by_ref, :ag_node, :ag_node, :string, :int], :ag_edge
-    attach_function :agsubg, [AGraph.by_ref, :string, :int], :pointer
+    attach_function :agnode, [AGraph, :string, :int], :ag_node
+    attach_function :agedge, [AGraph, :ag_node, :ag_node, :string, :int], :ag_edge
+    attach_function :agsubg, [AGraph, :string, :int], :pointer
 
     attach_function :agnameof, [:pointer], :string
     attach_function :agraphof, [:pointer], :pointer
@@ -51,22 +40,44 @@ module GV
     attach_function :agget, [:pointer, :string], :string
 
     attach_function :agsafeset, [:pointer, :string, :string, :string], :pointer
-    attach_function :agstrdup_html, [AGraph.by_ref, :string], :pointer
-    attach_function :agstrfree, [AGraph.by_ref, :pointer], :int
+    attach_function :agstrdup_html, [AGraph, :string], :pointer
+    attach_function :agstrfree, [AGraph, :pointer], :int
 
-    attach_function :agisdirected, [AGraph.by_ref], :int
-    attach_function :agisstrict, [AGraph.by_ref], :int
+    attach_function :agisdirected, [AGraph], :int
+    attach_function :agisstrict, [AGraph], :int
   end
+  private_constant :LibCGraph
+
+  module LibGVC
+    extend FFI::Library
+    ffi_lib 'gvc'
+
+    typedef :pointer, :gvc
+
+    attach_function :gvContext, [], :pointer
+    attach_function :gvFreeLayout, [:gvc, LibCGraph::AGraph], :int
+    attach_function :gvLayout, [:gvc, LibCGraph::AGraph, :string], :int
+
+    attach_function :gvRenderFilename, [:gvc, LibCGraph::AGraph, :string, :string], :int
+    attach_function :gvRenderData, [:gvc, LibCGraph::AGraph, :string, :pointer, :pointer], :int
+    attach_function :gvFreeRenderData, [:pointer], :void
+  end
+  private_constant :LibGVC
 
   class Component
-    @@gvc = FFI.gvContext()
+    # @!visibility private
+    @@gvc = LibGVC.gvContext()
 
+    # @return [Graph, SubGraph] the graph this component belongs to
     attr_reader :graph
 
+    # Creates an HTML label
+    # @param string [String] the HTML to parse
+    # @return [Object] a HTML label
     def html(string)
-      ptr = FFI.agstrdup_html(graph.ptr, string)
+      ptr = LibCGraph.agstrdup_html(graph.ptr, string)
       string = ptr.read_string
-      FFI.agstrfree graph.ptr, ptr
+      LibCGraph.agstrfree graph.ptr, ptr
 
       string
     end
@@ -81,16 +92,25 @@ module GV
 
     alias :eql? :== 
 
+    # @return [String] the component's name
     def name
-      FFI.agnameof ptr
+      LibCGraph.agnameof ptr
     end
 
+    # Sets an attribute
+    # @param attr [Symbol, String] attribute name
+    # @see http://www.graphviz.org/doc/info/attrs.html Node, Edge and Graph Attributes
+    # @param value [Object] attribute value
     def []=(attr, value)
-      FFI.agsafeset(ptr, attr.to_s, value.to_s, "")
+      LibCGraph.agsafeset(ptr, attr.to_s, value.to_s, "")
     end
 
+    # Retrieves the value of an attribute
+    # @param attr [Symbol, String] attribute name
+    # @see http://www.graphviz.org/doc/info/attrs.html Node, Edge and Graph Attributes
+    # @return [Object] the attribute value
     def [](attr)
-      FFI.agget(ptr, attr.to_s)
+      LibCGraph.agget(ptr, attr.to_s)
     end
 
     protected
@@ -102,7 +122,7 @@ module GV
       @graph = graph
       case name_or_ptr
       when String
-        @ptr = FFI.agnode(graph.ptr, name_or_ptr, 1)
+        @ptr = LibCGraph.agnode(graph.ptr, name_or_ptr, 1)
       else
         @ptr = name_or_ptr
       end
@@ -113,28 +133,50 @@ module GV
     def initialize(graph, name, tail, head)
       @graph = graph
 
-      @ptr = FFI.agedge(graph.ptr, tail.ptr, head.ptr, name, 1)
+      @ptr = LibCGraph.agedge(graph.ptr, tail.ptr, head.ptr, name, 1)
     end
 
+    # @return [Node] the head node of the edge
     def head
-      Node.new @graph, FFI.aghead(ptr)
+      Node.new @graph, LibCGraph.aghead(ptr)
     end
 
+    # @return [Node] the tail node of the edge
     def tail
-      Node.new @graph, FFI.agtail(ptr)
+      Node.new @graph, LibCGraph.agtail(ptr)
     end
   end
 
   class BaseGraph < Component
 
+    # Creates a new node
+    # @param name [String] the name (identifier) of the node
+    # @param attrs [Hash{String, Symbol => Object}] the attributes 
+    # to associate with this node
+    # @see http://www.graphviz.org/doc/info/attrs.html Node, Edge and Graph Attributes
+    # @return [Node] the newly created node
     def node(name, attrs = {})
       component Node, [name], attrs
     end
 
+    # Creates a new edge
+    # @param name [String] the name (identifier) of the edge
+    # @param tail [Node] the edge's tail node
+    # @param head [Node] the edge's head node
+    # @param attrs [Hash{String, Symbol => Object}] the attributes
+    # to associate with this edge
+    # @see http://www.graphviz.org/doc/info/attrs.html Node, Edge and Graph Attributes
+    # @return [Edge] the newly created edge
     def edge(name, tail, head, attrs = {})
       component Edge, [name, tail, head], attrs
     end
 
+    # Creates a new sub-graph
+    # @param name [String] the name (identifier) of the sub-graph
+    # @param attrs [Hash{String, Symbol => Object}] the attributes
+    # to associate with this sub-graph
+    # @see http://www.graphviz.org/doc/info/attrs.html Node, Edge and Graph Attributes
+    # @return [SubGraph] the newly created sub-graph
     def sub_graph(name, attrs = {})
       graph = component SubGraph, [name], attrs
       yield graph if block_given?
@@ -142,12 +184,14 @@ module GV
       graph
     end
 
+    # @return whether this graph is directed
     def directed?
-      FFI.agisdirected(ptr) == 1
+      LibCGraph.agisdirected(ptr) == 1
     end
 
+    # @return whether this graph is strict
     def strict?
-      FFI.agisstrict(ptr) == 1
+      LibCGraph.agisstrict(ptr) == 1
     end
 
     private
@@ -166,7 +210,7 @@ module GV
   class SubGraph < BaseGraph
     def initialize(graph, name)
       @graph = graph
-      @ptr = FFI.agsubg(graph.ptr, name, 1)
+      @ptr = LibCGraph.agsubg(graph.ptr, name, 1)
     end
   end
 
@@ -174,17 +218,24 @@ module GV
 
     class << self
       private :new
-      def open(name, type = :directed, strict = :normal)
-        ag_type = case [type, strict]
-                    when [:directed, :normal] then FFI.Agdirected
-                    when [:undirected, :normal] then FFI.Agundirected
-                    when [:directed, :strict] then FFI.Agstrictdirected
-                    when [:undirected, :strict] then FFI.Agstrictundirected
+
+      # Creates a new graph
+      # @param type [:directed, :undirected] the graphs type
+      # @param strictness [:strict, :normal] the graphs strict type
+      # @see http://www.graphviz.org/doc/info/attrs.html Node, Edge and Graph Attributes
+      # @yieldparam graph [Graph] the newly created graph
+      # @return [Graph] the newly created graph
+      def open(name, type = :directed, strictness = :normal)
+        ag_type = case [type, strictness]
+                    when [:directed, :normal] then LibCGraph.Agdirected
+                    when [:undirected, :normal] then LibCGraph.Agundirected
+                    when [:directed, :strict] then LibCGraph.Agstrictdirected
+                    when [:undirected, :strict] then LibCGraph.Agstrictundirected
                     else
-                      raise ArgumentError, "invalid graph type #{[type, strict]}"
+                      raise ArgumentError, "invalid graph type #{[type, strictness]}"
                     end
 
-        graph = new(FFI.agopen(name, ag_type, ::FFI::Pointer::NULL))
+        graph = new(LibCGraph.agopen(name, ag_type, FFI::Pointer::NULL))
 
         if block_given?
           yield graph
@@ -193,13 +244,16 @@ module GV
         graph
       end
 
+      # Loads a graph from a string of file
+      # @param io [IO, String] the resource to load from
+      # @return the newly loaded graph
       def load(io)
         data = if io.is_a? String
           io
         else
           io.read
         end
-        new FFI.agmemread(data)
+        new LibCGraph.agmemread(data)
       end
     end
 
@@ -211,26 +265,37 @@ module GV
       self
     end
 
-    def write(filename, format = 'png', layout = 'dot')
-      FFI.gvLayout(@@gvc, ptr, layout.to_s)
-      FFI.gvRenderFilename(@@gvc, ptr, format.to_s, filename);
-      FFI.gvFreeLayout(@@gvc, ptr)
+    # Renders the graph to an images and saves the result to a file
+    # @param filename [String] the filename
+    # @param format [String] the image format to use, e.g. 'svg', 'pdf' etc.
+    # @param layout [String] the layout to use, e.g. 'dot' or 'neato' etc.
+    # @return [nil]
+    def save(filename, format = 'png', layout = 'dot')
+      LibGVC.gvLayout(@@gvc, ptr, layout.to_s)
+      LibGVC.gvRenderFilename(@@gvc, ptr, format.to_s, filename);
+      LibGVC.gvFreeLayout(@@gvc, ptr)
+
+      nil
     end
 
+    # Renders the graph to an image and returns the result as a string
+    # @param format [String] the image format to use, e.g. 'svg', 'pdf' etc.
+    # @param layout [String] the layout to use, e.g. 'dot' or 'neato' etc.
+    # @return [String] the rendered graph in the given format
     def render(format = 'png', layout = 'dot')
-      FFI.gvLayout(@@gvc, ptr, layout.to_s)
+      LibGVC.gvLayout(@@gvc, ptr, layout.to_s)
 
-      data_ptr = ::FFI::MemoryPointer.new(:pointer, 1)
-      len_ptr = ::FFI::MemoryPointer.new(:int, 1)
+      data_ptr = FFI::MemoryPointer.new(:pointer, 1)
+      len_ptr = FFI::MemoryPointer.new(:int, 1)
 
-      FFI.gvRenderData(@@gvc, ptr, format.to_s, data_ptr, len_ptr);
+      LibGVC.gvRenderData(@@gvc, ptr, format.to_s, data_ptr, len_ptr);
       len = len_ptr.read_uint
       data_ptr = data_ptr.read_pointer
       
-      data = data_ptr.read_string_length len
+      data = data_ptr.read_string len
 
-      FFI.gvFreeRenderData(data_ptr)
-      FFI.gvFreeLayout(@@gvc, ptr)
+      LibGVC.gvFreeRenderData(data_ptr)
+      LibGVC.gvFreeLayout(@@gvc, ptr)
 
       data
     end

data/lib/gv/version.rb

@@ -1,3 +1,3 @@
 module GV
-  VERSION = "0.0.3"
+  VERSION = "0.1.0"
 end

data/spec/graph_spec.rb

@@ -15,7 +15,7 @@ describe Graph do
     end
 
     it "takes a block" do
-      graph = Graph.open 'test' do |g|
+      Graph.open 'test' do |g|
         g.directed?.must_equal true
         g.strict?.must_equal false
       end
@@ -24,8 +24,8 @@ describe Graph do
 
   describe :load do
     it "loads graph from file" do
-      f = lambda do |f|
-        graph = Graph.load f
+      f = lambda do |filename|
+        graph = Graph.load filename
         graph.directed?.must_equal true
         graph.strict?.must_equal false
         graph.name.must_equal 'g'
@@ -92,12 +92,12 @@ describe Graph do
     end
   end
 
-  describe :write do
+  describe :save do
     it "renders the graph to the given filename" do
       graph = Graph.open 'test'
       graph.edge 'e', graph.node('A'), graph.node('B')
       filename = File.join Dir.tmpdir, Dir::Tmpname.make_tmpname(['gv_test', '.png'], nil)
-      graph.write filename
+      graph.save filename
       File.file?(filename).must_equal true 
       File.unlink filename
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gv
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - furunkel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-27 00:00:00.000000000 Z
+date: 2016-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: ffi
   requirement: !ruby/object:Gem::Requirement
@@ -73,7 +87,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gemrelease"
 - ".gitignore"
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -105,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Graphviz for Ruby, using libgvc via FFI
@@ -114,3 +130,4 @@ test_files:
 - spec/render.png
 - spec/simple_graph.dot
 - spec/spec_helper.rb
+has_rdoc: