Permalink
Browse files

README improved.

  • Loading branch information...
1 parent 10c2810 commit 8df1a97b3c1435dc5eb4780e5a7d60c774dd3fae @bfontaine committed Feb 12, 2013
Showing with 50 additions and 72 deletions.
  1. +50 −72 README.md
View
122 README.md
@@ -1,5 +1,4 @@
-Graphs.rb
-=========
+# Graphs.rb
[![Build Status](https://travis-ci.org/bfontaine/Graphs.rb.png)](https://travis-ci.org/bfontaine/Graphs.rb)
@@ -10,8 +9,7 @@ Note: some of the examples below are outdated, since before the 0.1.5 version,
nodes & edges were represented as hashes, and now they are `Node` & `Edge`
objects, respectively. However, the principles stay the sames.
-Install
--------
+## Install
The best way is to use the `graphs` gem:
@@ -25,109 +23,89 @@ install it:
gem build graphs.gemspec
gem install ./graphs-*.gem # you may want to use sudo
-Tests
------
+## Tests
To perform the tests, clone this repo, then go into `tests` repertory, and
-execute `tests.rb`:
+execute `tests.rb` (you need Ruby ≥1.9.x):
git clone git://github.com/bfontaine/Graphs.rb.git
cd Graphs.rb/tests
ruby tests.rb
Make sure you have the latest version.
-Graph Class
-===========
+## Docs
The `Graph` class is a simple graph with nodes and edges. It provides three
read-write attributes: `nodes`, `edges`, and `attr` (attributes of the graph,
like author or description). It can be written in a file using `Graph#write`
method.
-Example
--------
+`Node` and `Edge` are special classes which inherit from `Hash`. A graph object
+provide two important attributes:
- irb> require 'graph'
- => true
- irb> nodes = [{'name'=>'me'}, {'name'=>'you'}]
- => [{'name'=>'me'}, {'name'=>'you'}]
- irb> edges = [{'node1'=>'you', 'node2'=>'me', 'directed'=>true},
- {'node1'=>'you', 'node2'=>'me', 'directed'=>true}]
- => [{'node1'=>'you', 'node2'=>'me', 'directed'=>true}, {'node1'=>'you', 'node2'=>'me', 'directed'=>true}]
- irb> g = Graph.new(nodes, edges)
- => #<Graph:0x9e08e3c @nodes=[{"name"=>"me"}, {"name"=>"you"}], @edges=[{"node1"=>"you", "node2"=>"me", "directed"=>true}, {"node1"=>"you", "node2"=>"me", "directed"=>true}]>
+* `nodes`: A `NodeArray` object (`Array`-like)
+* `edges`: An `EdgeArray` object (`Array`-like, too)
-You can perform some operations on graphes using the `|`, `&`, `^`, `+` or `-`
-operators. See the [documentation](http://rubydoc.info/gems/graphs/frames) for
-more informations.
-
-GDF Module
-==========
+For backward compatibility, you can create nodes and edges both with `Node` and
+`Edge` objects, and `Hash` ones, e.g.:
-The GDF module is used to parse
-[GDF](http://guess.wikispot.org/The_GUESS_.gdf_format) files using the unique method
-`GDF::load(filename)` which returns a Graph object.
+```ruby
+require 'graph'
-Example
--------
+nodes = [ {:label => 'foo'}, {:label => 'bar'} ]
-Imagine we have a file as below:
+g = Graph.new nodes
- $ cat trips.gdf
- nodedef> name VARCHAR,country VARCHAR
- Foo,England
- Bar,India
- edgedef> node1,node2,day INT,duration INT
- Bar,Foo,62,14
- Foo,Bar,154,7
-Then, using `irb`, we use the `GDF` module:
+nodes2 = nodes.map { |n| Graph::Node.new n }
+g2 = Graph.new nodes2
- $ irb
- irb> require 'graphs/gdf'
- => true
- irb> g = GDF::load 'trips.gdf'
+g == g2 # true
+```
-We can now access nodes
+You can perform some operations on graphes using the `|`, `&`, `^`, `+` or `-`
+operators. See the [documentation](http://rubydoc.info/gems/graphs/frames) for
+more informations.
- irb> g.nodes
- => [{'name'=>'Foo', 'country'=>'England'}, {'name'=>'Bar', 'country'=>'India'}]
-
-and edges
+### Import/Export
- irb> g.edges
- => [{'node1'=>'Bar', 'node2'=>'Foo', 'day'=>62, 'duration'=>14},
- {'node1'=>'Foo', 'node2'=>'Bar', 'day'=>154, 'duration'=>7}]
+The library currently support JSON and [GDF](http://guess.wikispot.org/The_GUESS_.gdf_format)
+formats.
-now, we can add a node and an edge
+You can read from files using the `::load` methods of each module:
- irb> g.nodes.push {'name'=>'John', country=>'USA'}
- irb> g.edges.push {'node1'=>'John', 'node2'=>'Foo', 'day'=>42, 'duration'=>12}
+```ruby
+require 'graph'
+require 'graphs/gdf'
+require 'graphs/json'
-but we forgot that all edges are directed ones. That's ok, just use
-the `set_default` method:
+g1 = GDF::load('myGraph.gdf')
+g2 = JSONGraph::load('myGraph.json')
+```
- irb> g.edges.set_default 'directed' => true
- irb> g.edges
- => [{'node1'=>'Bar', 'node2'=>'Foo', …, 'directed'=>true},
- {'node1'=>'Foo', 'node2'=>'Bar', …, 'directed'=>true},
- {'node1'=>'John', 'node2'=>'Foo', …, 'directed'=>true}]
+You can also export a graph using the `.write` method. It guesses the format
+using the file extension.
-Note that the `set_default` method is defined for `edges` and `nodes`. It
-accepts multiple arguments, and you only need to call it once, it will work for
-every new node or edge (just use `.push` method to add new ones).
+```ruby
+require 'graph'
+require 'graphs/gdf'
+require 'graphs/json'
-then, we can save our new graph in a new file
+g = Graph.new
- irb> g.write('new_trips.gdf')
+g.write('myGraph.gdf')
+g.write('myGraph.json')
+```
-Note to [Gephi](https://github.com/gephi/gephi) users: You can add the `:gephi`
-option to `g.write(…)` if you have big numbers. `Graph#write` method use
-`BIGINT` type for big numbers, but Gephi does not support it and parses it as a
-string field. So using the following:
+Note to [Gephi](https://github.com/gephi/gephi) users who want to export in GDF:
+You can add the `:gephi` option to `g.write(…)` if you have big numbers.
+`Graph#write` method use `BIGINT` type for big numbers, but Gephi does not
+support it and parses it as a string field. So using the following:
- irb> g.write('new_trips.gdf', {:gephi=>true})
+```ruby
+g.write('new_trips.gdf', {:gephi=>true})
+```
make sure that `INT` is used for all `BIGINT` fields.

0 comments on commit 8df1a97

Please sign in to comment.