GRAPH-EASY(1p)

💅 graph-easy 💅

okay so bestie, welcome to the manual page for graph-easy — that's GRAPH-EASY(1p), filed under User Contributed Perl Documentation, and it's genuinely one of my fave little tools ever. it renders graphs, it converts graphs, it does the absolute most. let's go 🦋

---

✨ NAME ✨

graph-easy — render/convert graphs in/from various formats 💖

---

🎀 SYNOPSIS 🎀

convert between graph formats and layout/render graphs, like:

graph-easy [options] [inputfile [outputfile]]

echo "[ Bonn ] - car -> [ Berlin ]" | graph-easy
graph-easy --input=graph.dot --as_ascii
graph-easy --html --output=mygraph.html graph.txt
graph-easy graph.txt graph.svg
graph-easy graph.txt --as_dot | dot -Tpng -o graph.png
graph-easy graph.txt --png
graph-easy graph.vcg --dot
graph-easy graph.dot --gdl
graph-easy graph.dot --graphml

no cap, that's the whole vibe. one line in, pretty picture out. ✨

---

🌸 ARGUMENTS 🌸

ok so here are the most important options — there's more in the full docs, this is the highlight reel:

• --help — prints the whole full documentation, not just this little short overview. like, the deluxe version. 💖
• --input — says which input file to read. example:

graph-easy --input=input.txt

the format gets auto-detected, and if you wanna override that, hit it with --from.

• --output — says which output file to write. example:

graph-easy --output=output.txt input.txt

• --as — says which output format you want. example:

graph-easy --as=ascii input.txt

valid formats are:

ascii       ASCII art rendering
boxart      Unicode Boxart rendering
html        HTML
svg         Scalable Vector Graphics
graphviz    the DOT language
dot         alias for "graphviz"
txt         Graph::Easy text
vcg         VCG (Visualizing Compiler Graphs - a subset of GDL) text
gdl         GDL (Graph Description Language) text
graphml     GraphML

and in addition, these next ones are understood and piped through whatever program you named with the --renderer option (default: dot):

bmp         Windows bitmap
gif         GIF
hpgl        HP-GL/2 vector graphic
jpg         JPEG
pcl         PCL printer language
pdf         PDF
png         PNG
ps          Postscript
ps2         Postscript with PDF notations (see graphviz documentation)
tga         Targa bitmap
tif         TIFF bitmap

the default format is decided by the output filename extension, and it's "ascii" if no output filename was set. 👑

you can also use ONE argument of the form --as_ascii or --ascii.

• --from — says which input format it is. valid formats are:

graphviz    the DOT language
txt         Graph::Easy text
vcg         VCG text
gdl         GDL (Graph Description Language) text

if you don't say, the input format gets auto-detected. 🧚

you can also use ONE argument of the form --from_dot, etc.

• --renderer — the external program (default: "dot") used to render output formats like "png", "jpg" etc. some choices are "neato", "twopi", "fdp" or "circo".
• --parse — input gets only parsed, with zero output generation. super useful in combination with --debug=1 or --stats. example:

graph-easy input.txt --parse --debug=1

• --stats — writes various statistics about the input graph to STDERR. best used in combination with --parse:

graph-easy input.txt --parse --stats

• --timeout — sets the timeout in seconds for the Graph::Easy layouter that generates ASCII, HTML, SVG or boxart output. if the layout does not finish in this time, it gets aborted. example:

graph-easy input.txt --timeout=500

conversion to DOT, VCG/GDL, GraphML or plain text ignores the timeout.

the default is 240 seconds (4 minutes). ⏰

• --verbose — writes info regarding the conversion process to STDERR.

---

🦋 DESCRIPTION 🦋

"graph-easy" reads a description of a graph (a connected network of nodes and edges, not a pie chart :-) ) and then converts this to the desired output format.

by default, the input gets read from STDIN, and the output goes to STDOUT. the input is expected to be encoded in UTF-8, and the output will also be UTF-8. 💜

it understands the following formats as input:

Graph::Easy  http://bloodgate.com/perl/graph/manual/
DOT          http://www.graphviz.org/
VCG          http://rw4.cs.uni-sb.de/~sander/html/gsvcg1.html
GDL          http://www.aisee.com/

the formats are automatically detected, regardless of the input file name, but you can also explicitly declare your input to be in one specific format. 💅

the output can be a dump of the graph in one of the following formats:

Graph::Easy  http://bloodgate.com/perl/graph/manual/
DOT          http://www.graphviz.org/
VCG          http://rw4.cs.uni-sb.de/~sander/html/gsvcg1.html
GDL          http://www.aisee.com/
GraphML      http://graphml.graphdrawing.org/

and on top of that, "Graph::Easy" can also create layouts of graphs in one of the following output formats:

HTML   SVG   ASCII   BOXART

note that for SVG output, you need to install the module Graph::Easy::As_svg first. don't skip this step bestie, it will simply not work. 😭

as a shortcut, you can also specify the output format as 'png' — this causes "graph-easy" to pipe the input in graphviz format to the "dot" program to create a PNG file in one step. these following two examples are equivalent:

graph-easy graph.txt --dot | dot -Tpng -o graph.png
graph-easy graph.txt --png

literally the same thing, one's just lazier and we love her for it. 🔥

---

👑 OTHER ARGUMENTS 👑

"graph-easy" supports a few more arguments in addition to the ones from above:

• --version — write version info and exit.
• --debug=N — set the debug level (1..3).

warning: this will generate huge amounts of hard to understand output on STDERR. like, an alarming amount. example:

graph-easy input.txt --output=test.html --debug=1

• --png, --dot, --vcg, --gdl, --txt, --ascii, --boxart, --html, --svg — given exactly ONE of these options, produces the desired output format. one. exactly one. don't get greedy. 💅

---

🌈 EXAMPLES 🌈

💖 ASCII output

echo "[ Bonn ] -- car --> [ Berlin ], [ Ulm ]" | graph-easy

+--------+  car   +-----+
|  Bonn  | -----> | Ulm |
+--------+        +-----+
  |
  | car
  v
+--------+
| Berlin |
+--------+

⭐ Graphviz example output

echo "[ Bonn ] -- car --> [ Berlin ], [ Ulm ]" | graph-easy --dot
digraph GRAPH_0 {

  edge [ arrowhead=open ];
  graph [ rankdir=LR ];
  node [
    fontsize=11,
    fillcolor=white,
    style=filled,
    shape=box ];

  Bonn -> Ulm [ label=car ]
  Bonn -> Berlin [ label=car ]

}

🎀 VCG example output

echo "[ Bonn ] -- car --> [ Berlin ], [ Ulm ]" | graph-easy --vcg
graph: {
  title: "Untitled graph"

  node: { title: "Berlin" }
  node: { title: "Bonn" }
  node: { title: "Ulm" }

  edge:  { label: "car" sourcename: "Bonn" targetname: "Ulm" }
  edge:  { label: "car" sourcename: "Bonn" targetname: "Berlin" }

}

🧚 GDL example output

GDL (Graph Description Language) is a superset of VCG, and thus the output will look almost the same as VCG:

echo "[ Bonn ] -- car --> [ Berlin ], [ Ulm ]" | graph-easy --gdl
graph: {
  title: "Untitled graph"

  node: { title: "Berlin" }
  node: { title: "Bonn" }
  node: { title: "Ulm" }

  edge:  { label: "car" source: "Bonn" target: "Ulm" }
  edge:  { label: "car" source: "Bonn" target: "Berlin" }

}

🦋 GraphML example output

GraphML is XML:

echo "[ Bonn ] -- car --> [ Berlin ], [ Ulm ]" | graph-easy --graphml
<?xml version="1.0" encoding="UTF-8"?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns
     http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">

  <!-- Created by Graph::Easy v0.58 at Mon Aug 20 00:01:25 2007 -->

  <key id="d0" for="edge" attr.name="label" attr.type="string"/>

  <graph id="G" edgedefault="directed">
    <node id="Berlin">
</node>
    <node id="Bonn">
</node>
    <node id="Ulm">
</node>
    <edge source="Bonn" target="Berlin">
      <data key="d0">car</data>
</edge>
    <edge source="Bonn" target="Ulm">
      <data key="d0">car</data>
</edge>
  </graph>
<graphml>

---

💀 CAVEATS 💀

please note that it is impossible to convert 100% from one format to another format since every graph language out there has features that are unique to only this language. that's just how it is, bestie. 😭

in addition, the conversion process always converts the input first into an Graph::Easy graph, and then to the desired output format.

this means that only features and attributes that are actually valid in Graph::Easy are supported yet. work in making Graph::Easy an universal format supporting as much as possible is still in progress. it's giving ✨in development✨.

attributes that are not yet supported natively by Graph::Easy are converted to custom attributes with a prefixed "x-format-", f.i. "x-dot-". upon output to the same format, these are converted back, but conversion to a different format will lose these attributes. so heads up. 🫶

for a list of what problems still remain, please see the TODO file in the "Graph::Easy" distribution on CPAN:

<http://search.cpan.org/~tels/Graph-Easy/>

if you notice anything wrong, or miss attributes, please file a bug report on

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Graph-Easy>

so we can fix it and include the missing things into Graph::Easy! 🥺 do it, they literally asked.

---

📜 LICENSE 📜

this library is free software; you can redistribute it and/or modify it under the terms of the GPL.

see the LICENSE file of Graph::Easy for a copy of the GPL.

this product includes color specifications and designs developed by Cynthia Brewer (<http://colorbrewer.org/>). see the LICENSE file for the full license text that applies to these color schemes. 🎨

---

🌟 AUTHOR 🌟

copyright (C) 2004 - 2008 by Tels <http://bloodgate.com>

💖 SEE ALSO 💖

ok so if you want EVEN MORE lore, the online manual of Graph::Easy has you covered, bestie:

<http://bloodgate.com/perl/graph/manual/>

it's literally the mothership of graph knowledge ✨

---

Also go peek at these icons while you're at it:

• Graph::Easy — the main character herself 👑
• Graph::Easy::Manual — the deep-dive lore drop 🧚

---

and that's a wrap on the whole page, fr fr 🫶 This lil masterpiece ships with perl v5.36.0, dated 2022-11-20, and lives under the name GRAPH-EASY(1p) 💅 no cap, go make some iconic graphs, you ate 💖✨🌸