gvpr

gvpr [options] [-f scriptfile | scriptstring] [files...]
Example:
gvpr -f myscript.gvpr input.dot -o output.dot
gvpr 'N[color=="red"]{$.color="blue"}' input.dot

-f scriptfile
    Specifies a file containing the gvpr script to be executed.

scriptstring
    A gvpr script provided directly on the command line, enclosed in quotes.

-o outfile
    Writes the output graph to the specified outfile instead of standard output.

-a
    If set, the output will only contain graph attributes, not the graph structure.

-c
    When a node or edge is copied from one graph to another, its attributes are also copied. If an attribute has already been defined in the target graph, it is normally left unchanged. If the -c flag is set, the input attribute will overwrite any pre-existing attribute.

-e
    Exits on the first semantic error encountered during script execution.

-l
    When processing subgraphs, generates the boolean variable l_g for internal use.

-m
    When processing subgraphs, generates the boolean variable m_g for internal use.

-r
    Operates on the reverse graph. This means edges are traversed in the opposite direction for processing.

-U
    Enforces strict graphs, meaning multiple edges between the same two nodes are treated as a single edge.

-v
    Enables verbose output, printing information about script execution and graph processing.

-V N
    Sets the verbosity level to N (0-5). Higher values provide more detailed output.

-?
    Prints a usage message and exits.

gvpr is a powerful, AWK-like processor designed for manipulating and analyzing graphs specified in the Graphviz DOT language. It acts as a graph stream editor, allowing users to apply sophisticated scripts to filter, transform, or extract information from graph data. Inspired by the awk utility, gvpr operates on graphs by executing user-defined actions when specific graph elements (nodes, edges, or the graph itself) match certain patterns.

A gvpr script typically consists of blocks such as BEGIN, NODE, EDGE, GRAPH, and END, each with a pattern (optional) and an associated action. When gvpr processes an input graph, it sequentially evaluates these blocks. For instance, an EDGE block's action will execute for every edge in the graph that satisfies its pattern. This allows for fine-grained control over graph elements, enabling tasks like modifying attributes, adding or deleting nodes/edges, computing graph metrics, or generating subgraphs based on complex criteria. It's an essential tool for advanced graph processing within the Graphviz ecosystem.

gvpr's power comes with a learning curve. Users need a solid understanding of the DOT language and basic graph theory concepts. The scripting language itself, while AWK-like, introduces graph-specific patterns and actions, requiring familiarity with its unique syntax and built-in functions. Debugging complex gvpr scripts can also be challenging due to the intricate interactions between patterns and graph elements. Incorrectly written scripts can lead to unexpected graph modifications or performance issues on large datasets.

A gvpr script is composed of BEGIN, NODE, EDGE, GRAPH, and END blocks, each optionally containing a pattern and an action.

BEGIN { actions }: Executed once before any graphs are processed. Ideal for initialization.
NODE [pattern] { actions }: Executed for every node that matches the optional pattern.
EDGE [pattern] { actions }: Executed for every edge that matches the optional pattern.
GRAPH [pattern] { actions }: Executed for every graph (or subgraph) that matches the optional pattern.
END { actions }: Executed once after all graphs have been processed. Ideal for final reporting or cleanup.

gvpr provides several built-in variables to access properties of the current graph element (node, edge, or graph):

$: The current graph element (node, edge, or graph).
$.name: The name of the current node or graph.
$.head: The head node of the current edge.
$.tail: The tail node of the current edge.
$.type: The type of the current element (e.g., N_node, N_edge, N_graph).
$.indegree, $.outdegree, $.degree: In-degree, out-degree, and total degree of the current node.
$.n_nodes, $.n_edges: Number of nodes and edges in the current graph.
Attributes of the current element can be accessed directly, e.g., $.color, $.label.

gvpr offers various built-in functions for graph manipulation and queries:

subg(graph, nodes, edges): Returns a subgraph induced by a set of nodes and/or edges.
clone(element): Creates a copy of a graph element.
delete(element): Removes a graph element from its graph.
print(value): Prints a value to standard output.
sprintf(format, ...): Formats and returns a string (like C's sprintf).
isdirected(graph): Returns true if the graph is directed.
issubg(graph): Returns true if the graph is a subgraph.

gvpr originated as part of the Graphviz project, developed primarily by AT&T Labs Research. Its creation addressed the need for a programmatic way to manipulate and query graph structures defined in the DOT language, going beyond simple attribute modifications. The design was heavily influenced by the awk utility, aiming to bring its powerful pattern-action processing model to the domain of graph data. This allowed Graphviz users to perform complex graph transformations, filtering, and analysis tasks that would otherwise require writing custom programs in general-purpose languages. Over time, gvpr has evolved as a robust and integral component of the Graphviz ecosystem, enabling more sophisticated graph visualization and analysis workflows.

dot(1), awk(1), sed(1), grep(1)