Graph : Graphes.

1 Graphdot01.

1.1 Introduction.

Graphdot01 est un outil très simple permettant d'obtenir une image à partir d'une description d'un graphe orienté.
Il est constitué de classes Ruby et d'1 programme Ruby permettant d'y accéder, il n'est pas nécessaire de connaître Ruby pour utiliser ce programme.

A partir de fichiers définissant les sommets et les arcs du graphe, graphdot01 construit un fichier au format .dot qui peut être utilisé par Graphviz pour construire une image de ce graphe.

Sur ce diagramme, les fichiers sont représentés par des ellipses et les programmes par des rectangles.

1.2 API.

Seul l'utilisation du programme graphdot01.rb est documentée, l'API des classes qu'il utilise étant destinée à changer.

1.2.1 Le programme graphdot01.rb.

Il construit un fichier .dot qui peut être exploité par un des programmes de Graphviz comme le programme dot.
il permet de représenter des graphes comprenant des sous-graphes encore appelés clusters.
Ces sous-graphes sont des regroupement de sommets connexes ou non qui seront visualisés dans un même ensemble.

1.2.1.1 Les fichiers en entrée.

Ce sont des fichiers texte dont chaque ligne est formée d'un nombre fixe de champs séparés par des espaces.
Ce format a été choisi parce qu'il est facile à générer à partir de scripts extrayant des informations de fichiers texte ou de tables de SGBDR.

1.2.1.1.1 Le fichier nodes.

Il associe à chaque sous-graphe les sommets qu'il contient.
Un sommet est identifié de manière unique par la concaténation du nom du sous-graphe et du nom du sommet, 2 sommets de même nom dans deux sous-graphes différents seront deux smmets différents, cela signifie aussi que les sous-graphes sont disjoints.

Format d'une ligne définissant un couple (sous-graphe, sommet) :
<sous-graphe> <sommet>
où <sous-graphe> et <sommet> sont des noms séparés par des espaces.

Les lignes du fichier peuvent apparaître dans n'importe quel ordre, cependant cet ordre peut dans certains cas avoir une incidence sur la disposition des sommets dans un sous-graphe.

1.2.1.1.2 Le fichier edges.

Il définit un ensemble de relations entre 2 couples (sous-graphe, sommet).

Format d'une ligne définissant cette relation :
<sous-graphe 1> <sommet 1> <sous-graphe 2> <sommet 2>
Elle correpond à 2 lignes jointes et séparées par des espaces du fichier nodes. L'ordre dans lequel apparaissent ces 2 couples déterminera l'emplacement de la pointe de la flêche dans l'arc qui relie 2 sommets.
Par défaut, 1 --> 2.

Les lignes du fichier peuvent apparaître dans n'importe quel ordre.

1.2.1.2 Le fichier en sortie.

Il s'agit d'un fichier au format dot tel que défini dans la documentation de Graphviz.

Ce fichier traité par un utilitaire de Graphviz tel que dot produit une image. On peut choisir parmi un assez grand nombre le format de cette imaage.

1.2.1.3 Exemple.

Il s'agit du graphe d'appel des fonctions d'un programme C plausible. Voici en fin de chaîne le fichier .png produit par Graphviz :

Les sous-graphes correspondent au sources .c et les sommets aux fonctions déclarées dans ces sources.

On peut remarquer que le sous-graphe correspondant au source baz.c est présenté un peu différemment, il est entouré de bleu. Il s'agit du sous-graphe que l'on a indiqué à graphdot01.rb comme étant le sous-graphe ayant le focus.
la fonction main, elle aussi présentée différemment, correspond au sommet qui a le focus.

baz.c main
baz.c baz
foobar.c bar
foobar.c foo
util.c xmalloc

baz.c main baz.c baz
baz.c baz util.c xmalloc
baz.c baz foobar.c foo
baz.c baz foobar.c bar
foobar.c foo foobar.c bar
foobar.c foo foobar.c foo
foobar.c bar util.c xmalloc

1.2.1.4 Invocation de graphdot01.rb.

Usage   : grfdot01.rb [--config [arg]] [--graph [arg]] 
		[--fcluster arg] [--fnode arg] 
		--nodefile arg --edgefile arg 
		[--outfile [arg]] [--verbose [arg]] 
		[--help] [--version] 
Options :
	--config -c [arg] (default <rubrix/dot01conf.rb>)
		Optional: Configuration ruby file.
	--graph -g [arg] (default <>)
		Optional: Graph name.
	--fcluster -f arg (default <>)
		Optional: Focused cluster.
	--fnode -j arg (default <>)
		Optional: Focused node.
	--nodefile -n arg (default <>)
		Required: Nodes input file.
	--edgefile -e arg (default <>)
		Required: edges input file.
	--outfile -o [arg] (default <$stdout>)
		Optional: dot output file.
	--verbose [arg] (default <0>)
		Optional: Specify verbosity level (0..4)
	[arg ...]
		Arguments.
	Or
	--help -h 
		Display these informations and exit successfully.
	Or
	--version -V 
		Display program version and exit successfully.

Nous allons l'étudier en nous basant sur le script de l'exemple du chapitre précédant :

graphdot01.rb -g baz --fcluster baz.c --fnode main\
        -n nodes02 -e edges02 -o graph02.dot
dot -Tpng -o graph02.png graph02.dot

'--config' fait l'objet du paragraphe suivant.
'-g baz' indique le nom du graphe tel qu'on veut le voir apparaitre au bas de l'image.
'-fcluster baz.c' et '--fnode main' indique le sous-graphe et le sommet qui auront le focus.
'-n' et '-e' indiquent les fichiers nodes et edges.
'-o' indique le fichier en sortie en format dot.

La dernière ligne est l'invocation du programme dot de graphviz.

1.2.1.5 Configuration de graphdot01.rb.

il est possible que vous n'aimiez pas les couleurs du graphe ou la forme des sommets et des flêches. Il est possible de configurer tout cela ainsi que d'autres paramètres de présentation des graphes.

Le fichier de configuration est un peu rudimentaire, il s'agit d'affectation de strings à des variables d'instance dans une fonction d'un module.
La configuration par défaut est installée dans la lib ruby sous rubrix/dot01conf.rb, vous pouvez facilement la copier et la modifier et indiquer le fichier résultant à graphdot01.rb par l'argument --config file.

Référez-vous à la documentation de Graphviz pour connaitre les différents attributs que vous pouvez renseigner.
Cependant, si vous ne modifiez que les couleurs, vous n'avez pas besoin de vous y référer, la liste des couleurs disponibles sur un système Unix doit se trouver ans /etc/X11/rgb.txt ou quelque chose comme ça.

En changeant quelques lignes de la configuration, voici ce à quoi le graphe de l'exemple peut resembler :

Il est également possible d'utiliser d'autres utilitaires que dot, le graphe suivant a été construit par fdp de Graphviz

1.3 Limitations.

Le programme graphdot01.rb souffre de sérieuses limitations, il n'est notamment pas possible de typer les sous-graphes, sommets et arcs de manière à les faire apparaitre de manières différentes.
Sa configuration est également un peu frustre.

Il est cependant utilisable tel quel pour visualiser des graphes simples. Il sera peu modifié, un autre programme sera écrit pour permettre plus de souplesse dans la représentation de graphes.

2 Informations légales.

Graph is copyrighted : Copyright (c) 2006 Patrick Davalan. All rights reserved.
Graph is free software, it may be used, modified and distributed under the same terms as Ruby.
See the file COPYING in the Ruby distribution.

Graph is provided "as is" without any expressed or implied warranty, including, but not limited to, any warranty you might dream of.

3 Download, install and use.

Graph needs Ruby to install and to work and Opthash to run. It recommends some tool like Graphviz to produce an image from a dot file.

Download the latest version in the Download page

Unzip the tarball with tar xzvf graph-version.tar.gz, it ceates the graph-version directory, then read the README file in that directory.

In order to not pollute your Ruby libraries directory , Graph as well as some other projects of my own installs its libraries into the subdirectory 'rubrix'.

4 Bugs and deficiencies.

Send bug reports to : almazz at wanadoo dot fr

Graph, its installation procedures and test suite are designed to work on any platform where Ruby works, but they have only been tested on a Debian GNU/Linux system.
Graph had been developped using Ruby 1.8, but it may work on previous versions of Ruby.