gvprss - the gvpr stylesheet processor

gvprss implements a CSS-like stylesheet processor for gvpr, the "graph pattern recognizer" bundled with Graphviz.

Installing

gvprss is implemented in Node.js (server-side JavaScript). Instructions for install Node.js can be found at nodejs.org/.

Once Node.js is installed, gvprss can be installed using npm, the Node Package Manager that is bundled with Node.js.

To install gvprss with npm, simply run:

npm install -g gvprss

(Assuming ~/.npm is in your $PATH), you can then invoke gvprss as described below.

Using

gvprss transforms a "stylesheet" into a gvpr-compatible program. For example:

echo "N #foo { fontsize = 24; }" | gvprss

generates a gvpr scripts that includes the rule:

N {if(str_equals($.name,"foo")) { fontsize = 24; }}

which (when processed with gvpr) will fire for every node in the input graph and set the fontsize attribute to 24 on any node named foo.

Command Line Parameters

The script generated by gvprss is defined by three command line parameters:

• -S [FILENAME] instructs gvprss to process the specified file as a gvrpss stylesheet (described below). Rules defined in the stylesheet will be transformed into gvpr-compatible rules in the generated script.

• -G [FILENAME] indicates a file containing a gvpr program (or program fragment) to be appended to the end of the generated script. This is used to inject custom rules or processing that isn't easily expressed within a gvprss stylesheet.

• -B [FILENAME] indicates a files containing a gvpr program fragment to be injected into the BEGIN section of the generated script. (gvpr only allows one BEGIN rule in the entire program. gvprss uses BEGIN to define some utility functions. The -B allows one to add custom code to that BEGIN section.)

These parameters can occur in any order and can be repeated multiple times to specify multiple files of the given type.

When [FILENAME] is - the content is read from stdin (rather than a file).

• If -O [FILENAME] is provided, gvprss will write the generated program to the specified file. When [FILENAME] is - the program will be written to stdout (the default).

As seen above, when no other command line parameter is specified, gvprss reads a stylesheet from stdin and writes the generated program to stdout.

• When any other parameter provided, rather than printing the generated program to stdout or a file, gvprss will immediately invoke gvpr on the program (by writing it to a temporary file and using the -f option). All other parameters (i.e., everything other than -S, -G, -B and -O) will be passed on to gvpr.

For example:

echo "N #foo { fontsize = 24; }" | gvprss -S - -c mygraph.gv

will run the generated program on the graph specified in mygraph.gv, passing the -c parameter to gvpr in the process.

The Stylesheet Syntax

gvprss supports a CSS-inspired language for defining gvpr processing rules.

Every gvprss rule is composed of two parts:

1. A selector (or list of selectors).

2. An action to perform on the selected elements.

For example, in the snippet:

N #foo { fontsize = 24; }

the N #foo is the selector part and { fontsize = 24; } is the action part.

The action part appears within curly-brackets and is passed as-is to gvpr.

The selector part is composed of one or more of the follow selectors:

• N - the node selector (matches all nodes in the input graph)
• E - the edge selector (matches all edges in the input graph)
• G - the graph selector (matches all graphs and sub-graphs in the input graph)
• #foo - the "name" selector (matches all objects with the specified name)
• .bar - the "class" selector (matches all objects with a class attribute that, when parsed as a comma or whitespace delimited list, includes the specified value)
• [attr] - the "attribute exists" selector (matches all objects with an attribute with the given name)
• [attr==val] - the "attribute value" selector (matches all objects with an attribute with the given name whose value matches the specified value)
• [attr=val] - an alternative syntax for [attr==val], for compatibility with gvpr.
• [attr*=val] - the "attribute contains" selector (matches all objects with an attribute with the given name whose value contains the specified value)
• [attr^=val] - the "attribute starts with" selector (matches all objects with an attribute with the given name whose value starts with the specified value)
• [attr$=val] - the "attribute ends with" selector (matches all objects with an attribute with the given name whose value ends with the specified value)
• [attr~=val] - the "attribute list includes" selector (matches all objects with an attribute with the given name whose value, when parsed as a comma or whitespace delimited list, includes the specified value). (Note that .foo is equivalent to [class~=foo].)

At most one of N, E and G can appear in a selector list and, when present, it must be the first element in the list.

When multiple selectors are specified, the corresponding action will apply to elements that meet all of the selectors' conditions. (I.e., selectors are "and-ed" together.) White space between selectors is optional. E.g., the rule:

N #foo .bar .anotherclass [attr] [attr2=value2] { color = "red"; }

could also be written:

N#foo.bar.anotherclass[attr][attr2=value2]{ color = "red"; }

Note that the word following #, . or = can be any valid Grapvhiz identifier, including numeric values and quoted strings. E.g., the selector:

#007 ."3.14149" ."another class"

matches elements (nodes, edges or graphs) with the name 007 that includes the classes 3.14159 and another class.