Shaape processes ascii drawings of diagrams and converts them to pixel or vector graphics. The word Shaape itself is a neologism from shape and ascii art.
-
Shaape is consistent between ascii source code and the produced image, What-You-See-Is-What-You-Generate
-
Shaape supports a very natural form of ascii drawing (see the examples below) and attempts to keep the ascii source picture readable
-
Shaape has an extensive feature set while maintaining a small and natural syntax
-
arbitrary shapes (e.g. polygons, paths, planar graphs)
+-+ +-+ /\ \ \/ | + +- \ | | +---+ -+
-
arrows (that even can snap to target points)
+--> / /\ >---+---->+ + \/ -
extensive styles:
-
color
+---+ +---+ +---+ | a | | b | | c | +---+ +---+ +---+ options: - ".*" : {text : [[0,0,0,0]]} - "a" : {fill : [[1,0,0,1]]} - "b" : {fill : [[0,1,0,1]]} - "c" : {fill : [[0,0,1,1]]} -
gradients
+---+ | a | +---+ options: - ".*" : {text : [[0,0,0,0]]} - "a" : {fill : [[1,0,0,1], [0.2,0.5,0.7,1]]} -
shadows
+---+ +---+ | a | | b | +---+ +---+ options: - ".*" : {text : [[0,0,0,0]]} - "a" : {fill : [shadow]} - "b" : {fill : [no-shadow]} -
transparency
+---+ | a | +---+ options: - ".*" : {text : [[0,0,0,0]]} - "a" : {fill : [[1,0,0,0.5]]} -
line types: solid, dotted, dashed, dash-dotted
a------ b------ c------ d------ options: - ".*" : {text : [[0,0,0,0]], fill: [3]} - "a" : {fill : [solid]} - "b" : {fill : [dotted]} - "c" : {fill : [dashed]} - "d" : {fill : [dash-dotted]}
-
-
monospaced text in the whole drawing
+-----+ | abc | +-----+
-
all objects can be stacked or crossing, z-order is automatically determined
+--+ | | +-|--|---+ | | | | +-|--|---+ | | +--+
-
corners can be either miter or round (the * character)
*---+ | | *** * +---* * ***
-
renders to png, svg, eps(experimental), pdf(experimental)
+-------+ +-------+ +-------+ +-------+ | |\ | |\ | |\ | |\ | +-+ | +-+ | +-+ | +-+ | PNG | | SVG | | EPS | | PDF | | | | | | | | | | | | | | exp.| | exp.| +---------+ +---------+ +---------+ +---------+
-
md5sum generation/checking to prevent image generation on unchanged sources
'[changed]' +----------> regenerate >----+ / \ source >--+ +---> result \ / +---> use old image >--------+ '[unchanged]'
-
NetworkX python graph package
-
pycairo
-
pango
-
pangocairo
-
scipy
-
numpy
-
pyyaml
-
networkx
-
setuptools
-
additionally for development:
-
nose
-
coverage
-
mock
-
To run shaape after the installation:
$ shaape
You can also run shaape without any installation by using following line inside the root directory of your git clone:
$ shaape/run.py
Shaape uses an asciidoc block listing definition to integrate into asciidoc:
[shaape]
---------------------------------------------------------------------
+--------+ +-------------+
| | \ /
| Hello |---> \ Goodbye /
| ;) | / \
| | / \
+--------+ +-------------+
---------------------------------------------------------------------
The most basic elements of shaape are lines. There are 4 different line elements:
- | \ / -------- | \ / | \ / | \ / | \ /
renders:
- | \ / -------- | \ / | \ / | \ / | \ /
Text can be directly written into the diagram. Words that contain special characters need to be quoted.
+---------+
| foo bar | +------------+
+---------+ |'foo|=/baar'|
+------------+
renders:
+---------+
| foo bar | +------------+
+---------+ |'foo|=/baar'|
+------------+
There are 4 types of arrows supported:
< > ^ v
renders:
< > ^ v
Arrows can also be used in connection with lines
<-- --> ^ | >-- --< | v
| v ^ |
renders:
<-- --> ^ | >-- --< | v
| v ^ |
Arrows snap to corners, that are near where they are pointing to:
+---+ v < v
-->| | \ / >+<
-->+ | \ / ^
| | ^ >
+---+
renders:
+---+ v < v
-->| | \ / >+<
-->+ | \ / ^
| | ^ >
+---+
The + character is used to connect lines:
\|/ | --+-- +-- +--- ---+--- /|\ / |
renders:
\|/ | --+-- +-- +--- ---+--- /|\ / |
If you want to visually connect two lines, without actually connecting them
internally, to avoid closing a polygon, you can just directly connect
perpendicular lines without the +:
+----+ +----+ | |-----| | | |-----| | +----+ +----+
renders:
+----+ +----+ | |-----| | | |-----| | +----+ +----+
Bezier curves are drawn using the * character. Shaape tries to match the
drawn curve smoothly. Bezier curves can be connected to lines and connectors.
The * itself is a similar connector as + and thus can be used to create
junctions in special cases too.
** ** ** ---+ **** * ** \ * * +--**
renders:
** ** ** ---+ **** * ** \ * * +--**
Crossings are used to let lines go over or under each other without creating a junction between them. You can use brackets and braces to explicitly indicate these junctions via curved lines in the generated image or you can use normal line characters to draw straight crossing lines.
e.g.
| | | | | | +-]-[-(-)-|----+ | | | | | | | | | | | | | | +--|-- | | | | | +------- | | | | | | | +-+-+-+------~-- | | +--------------+
renders:
| | | | | | +-]-[-(-)-|----+ | | | | | | | | | | | | | | +--|-- | | | | | +------- | | | | | | | +-+-+-+------~-- | | +--------------+
Although I basically want to disencourage you using fancy colors and styles, there may be some use cases when you need it.
A style defines how an object is drawn. Styles can be defined in a special area below the diagram. This area starts with the identifier options:. On the next line the style description starts. The general syntax for the style description is YAML.
To apply a style to an element in the drawing, you need to give it a name. Polygons are named by writing the name into the polygon. Lines are named by writing the name next to them:
+----> +------+ / | box1 | -----+ +------+ line1
The actual style definition is a yaml list element consisting itself of a dictionary with one element. The key of this element represents the names of the shapes that it should be applied to. The key should always be quoted. It is interpreted as a regular expression and matched against the names of all polygons. Polygons with matching names get this style applied.
options:
- "box[0-9]": {fill: [red, no-shadow], frame: [blue, dashed]}
If a polygon matches multiple style definitions, then all matching styles are applied sequentially from top to bottom of the style definition. That way you can use a default style for some attributes and change specific attributes for some polygons:
options:
- ".*": {fill: [red, no-shadow], frame: [blue, dashed]}
<<<<<<< HEAD
- "boxname[0-9]": {fill: [blue]}
=======
- "box[0-9]": {fill: [blue]}
>>>>>>> develop
Every drawn element matches the regular expression ".*". Thus you can use this expression for the default style. To set the default style for arrows, use "arrow" as key and to set the default style for lines, use "line".
The style definition itself contains a yaml dictionary, that may have 3 keys:
fill-
defines style properties for filling a polygon, arrow or line
frame-
defines the style properties for the frame of a polygon or arrow
text-
defines the style properties for text
Fill may contain:
-
shadow/no-shadow: selects wether the object drops a shadow (default is shadow)Example: All shapes without shadow- ".*" : {fill : [no-shadow]} -
solid/dashed/dotted/dash-dotted: selects the line style (only applied to lines, default is solid)Example: All lines dotted- "_line_" : {fill : [dotted]} -
multiple color definitions, where a color is:
-
red/green/blue -
a list with three floats from
0.0to1.0, representing RGB (e.g.[0.5, 0.5, 0.5]) -
a list with four floats from
0.0to1.0, representing RGBA NOTE: If you provide more than one color, then the polygon will use a gradient for it’s fill.Example: Yellow flat fill color- ".*" : {fill : [[1, 1, 0]]}Example: Gradient from red to green- ".*" : {fill : [red, [0, 1, 0]]}
-
-
a number defining the width of the line, if the fill applies to a line
Example: Apply width 3.5 to all lines- "_line_" : {fill : [3.5]}
Frame may contain:
-
solid/dashed/dotted/dash-dotted: selects the line styleExample: All frames dotted- ".*" : {frame : [dotted]} -
a color definition, where a color is:
-
red/green/blue -
a list with three floats from
0.0to1.0, representing RGB (e.g.[0.5, 0.5, 0.5])Example: All frames blue- ".*" : {frame : [blue]}
-
-
a number defining the width of the frame line, if the fill applies to a polygon
Example: Apply width 3.5 to all frames- ".*" : {frame : [3.5]}
Text may contain:
-
a font family description in the pango.FontDescription format(see pygtk)
-
a color definition, where a color is:
-
red/green/blue -
a list with three floats from
0.0to1.0, representing RGB
-
-
shadow/no-shadow: selects wether the object drops a shadow (default is no-shadow)
- ".*" : {text : ["Courier italic 9", red, shadow]}
link:shaape/tests/input/example_1.shaape[role=include]
link:shaape/tests/input/example_2.shaape[role=include]
link:shaape/tests/input/example_3.shaape[role=include]
link:shaape/tests/input/feature_z_order2.shaape[role=include]
link:shaape/tests/input/feature_gradients.shaape[role=include]
link:shaape/tests/input/example_5.shaape[role=include]