RailRoad

Generador de diagramas para Ruby on Rails

RailRoad es un generador de diagramas de clases para aplicaciones desarrolladas con Ruby on Rails. Se trata de un script Ruby que carga las clases de la aplicación y analiza sus propiedades (atributos, métodos) y relaciones (herencia, asociaciones de modelos como has_many, etc.). Su salida es la descripción de un grafo en el lenguaje DOT, que puede ser manipulada con herramientas como Graphviz.

RailRoad puede generar:

• Diagramas de modelos, mostrando tanto la jerarquía de herencia como las asociaciones entre los mismos. Se puede elegir mostrar las "columnas de contenido" ("content columns") y sus tipos.
• Diagramas de controladores, mostrando la jerarquía de herencia. Pueden incluirse sus métodos, agrupados por su visibilidad (públicos, protegidos y privados).
• Diagramas de máquina de estados (para su uso con el plugin "acts_as_state_machine").

Nota del author: Esta no es una idea original.Rdoc genera diagramas DOT a partir de código Ruby, y existen otras herramientas que producen los mismos diagramas que RailRoad genera. Es sólo que ninguno de dichos programas se ajusta a mis necesidades, por lo que decidí desarrollar uno yo mismo (y jugar un poco más con las capacidades de introspección de Ruby).

Ejecute RailRoad en el directorio raíz de la aplicación Rails. Puede redirigir su salida hacia un archivo .dot o conectarla mediante un "pipe" con las utilidades dot o neato para producir un gráfico. Los diagramas de modelo son mejor procesados mediante dot, en tanto que para los diagramas de controladores se recomienda el uso de neato.

railroad [opciones] comando

Opciones comunes

• -b, --brief
  Genera un diagrama compacto (sin atributos o métodos)
• -e, --exclude file1[,fileN]
  Excluye los archivos enumerados
• -i, --inheritance
  Incluye las relaciones de herencia
• -l, --label
  Añade una etiqueta con información sobre el diagrama (tipo, fecha, migration, versión)
• -o, --output ARCHIVO
  Escribe el diagrama en el archivo ARCHIVO
• -r, --root PATH
  Fija PATH como la raíz de la aplicación
• -v, --verbose
  Muestra mensajes del proceso por STDOUT

Opciones de diagrama de modelos

• -a, --all
  Incluye todos los modelos (no solamente los derivados de ActiveRecord::Base)
• --hide-magic
  Oculta los nombre de campos mágicos
• --hide-types
  Oculta el tipo de los atributos
• -j, --join
  Concentra los vértices
• -m, --modules
  Incluye los módulos
• -p, --plugins-models
  Incluye los modelos de los plugins
• -t, --transitive
  Incluye asociaciones transitivas (a través de herencia)

Opciones de diagrama de controladores

• --hide-public
  Oculta los métodos públicos
• --hide-protected
  Oculta los métodos protegidos
• --hide-private
  Oculta los métodos privados

Otras opciones

• -h, --help
  Muestra la ayuda
• --version
  Muestra la versión y la nota de copyright

Comandos

(Debe indicar uno de ellos)

• -M, --models
  Genera un diagrama de modelos
• -C, --controllers
  Genera un diagrama de controladores
• -A, --aasm
  Genera un diagrama "acts_as_state_machine"

Ejemplos

• railroad -o modelos.dot -M
  Produce un diagrama de modelos en el archivo 'modelos.dot'
• railroad -a -i -o modelos_completo.dot -M
  Diagrama de modelos con todas las clases, mostrando relaciones de herencia
• railroad -M | dot -Tsvg > modelos.svg
  Diagrama de modelos en formato SVG
• railroad -C | neato -Tpng > controladores.png
  Diagrama de controladores en formato PNG
• railroad -h
  Muestra la ayuda

Procesando archivos DOT

Para producir un archivo PNG a partir de un diagrama de modelos generado por RailRoad, puede ejecutar el siguiente comando:

dot -Tpng modelos.dot > modelos.png

Para hacerlo con un diagrama de controladores, utilice neato en vez de dot:

neato -Tpng controladores.dot > controladores.png

Si desea producir un archivo SVG (vectorial, escalable, editable), puede hacer lo siguiente:

dot -Tsvg modelos.dot > modelos.svg
neato -Tsvg controladores.dot > controladores.svg

Importante: Existe un bug en las herramientes de Graphviz al generar archivos SVG que causa un desbordamiento de texto. Puede resolver este problema editando el archivo (con un editor de textos, no un editor gráfico de SVG) y reemplazando, alrededor de la línea 12, "font-size:14.00;" por "font-size:11.00;", o bien ejecutando el siguiente comando (ver "man sed"):

sed -i 's/font-size:14.00/font-size:11.00/g' diag.svg

Nota: Para visualizar y editar SVG hay una excelente herramienta libre llamada Inkscape (similar a Adobe Illustrator). Para procesar DOT también puede utilizar Omnigraffle (en Mac OS X).

Generación simple de SVG

En sistemas derivados de Unix, puede definir los siguientes scripts del shell:

models2svg

#!/bin/bash
railroad $* -M | \
dot -Tsvg | \
sed 's/font-size:14.00/font-size:11.00/g'

controllers2svg

#!/bin/bash
railroad $* -C | \
neato -Tsvg | \
sed 's/font-size:14.00/font-size:11.00/g'

Y luego generar archivos SVG ejecutando comandos como los siguientes:

models2svg -i -l -a -m  > modelos.svg
controllers2svg -i -l > controladores.svg

(Note que el comando, -M o -C, no es necesario.)

RailRoad como una tarea rake

(Gracias a Thomas Ritz por el código.)

En su aplicación Rails application, añada las siguientes tareas rake en 'lib/task/diagrams.rake':

namespace :doc do
  namespace :diagram do
    task :models do
      sh "railroad -i -l -a -m -M | dot -Tsvg | sed 's/font-size:14.00/font-size:11.00/g' > doc/models.svg"
    end

    task :controllers do
      sh "railroad -i -l -C | neato -Tsvg | sed 's/font-size:14.00/font-size:11.00/g' > doc/controllers.svg"
    end
  end

  task :diagrams => %w(diagram:models diagram:controllers)
end

Luego, 'rake doc:diagrams' generará 'doc/models.svg' y 'doc/controllers.svg'.

Requerimientos

RailRoad ha sido probado con Ruby 1.8.5 y aplicaciones Rails 1.1.6 a 1.2.3. No existen requerimientos adicionales (sin embargo, todos los requerimientos de su aplicación Rails deben estar instalados.

Para ver o exportar los diagramas DOT diagrams, necesitará las herramientas de procesamiento de Graphviz.

El desarrollo comenzó a finales de marzo de 2006. RailRoad ha sido probado en los dearrollos Rails personales del autor, como así también en varias aplicaciones Rails libres "grandes" (como Typo), con resultados satisfactorios.

Sin embargo, que la salida producida por RailRoad se ajuste a las necesidades de su autor no es garantía de que lo dejará conforme a usted. Si desea reportar un bug (o tiene algún tipo de sugerencia), por favor, visite la página del proyecto en RubyForge. Cualquier comentario será muy apreciado.

Estos son algunos diagramas de ejemplo producidos por RailRoad. (No necesariamente generados con la última versión.)

Nota del autor: Sé que estos diagramas no se parecen mucho a los diagramas UML, pero prefiero algo más cercano a BON.

Depot

La aplicación Depot es un ejemplo bien conocido del libro "Agile Web Development with Rails". (¿Qué mejor manera de comenzar a probar RailRoad?)

Diagrama de modelos También puede verlo en formato SVG.

Controllers diagram También puede verlo en formato SVG.

rTPlan

rTPlan es una aplicación para la planificación de tareas de proyectos. Su versión 0.4.0 tiene 6 modelos, 11 controladores y 550 líneas de LOC de código.

Diagrama de modelos También puede verlo en formato SVG.

Diagrama de controladores También puede verlo en formato SVG.

Typo

Typo es un sistema de weblog (una de las aplicaciones opensource más exitosas) desarrollado con Rails. Y también es un programa "grande": 26 controladores, 59 modelos and 5469 líneas de LOC de código, para la versión 4.1.

Los diagramas de modelos han sido generados sin la opción "--all", para omitir las clases que no sean derivadas de ActiveRecord::Base (sólo para obtener un diagrama más claro.)

Diagrama de modelos También puede verlo en formato SVG.

Diagrama de controladores También puede verlo en formato SVG.

Para sistemas complejos, RailRoad también puede generar diagramas breves.

Diagrama de modelos (versión breve)

Diagrama de controladores (versión breve)

Para diagramas de modelos complejos, también puede omitir las relaciones de herencia (no usando el modificador "--inheritance").

Diagrama de modelos (versión breve, sin herencia)

Si utiliza gem puede instalar RailRoad con el comando:

gem install railroad

También puede obtener el código fuente completo desde el repositorio del proyecto en RubyForge.

RailRoad es desarrollado por Javier Smaldone (como parte de sus experimentos con RoR).

Este programa es distribuido bajo la Licencia Pública General de GNU (como software libre).