<commit_before>.TH GVPR 1 "1 November 2005"
.SH NAME
gvpr \- graph pattern scanning and processing language
.br
( previously known as
.B gpr
)
.SH SYNOPSIS
.B gvpr
[\fB\-icV?\fP]
[
.BI \-o
.I outfile
]
[
.BI \-a
.I args
]
[
.I 'prog'
|
.BI \-f
.I progfile
]
[ 
.I files 
]
.SH DESCRIPTION
.B gvpr
is a graph stream editor inspired by \fBawk\fP.
It copies input graphs to its
output, possibly transforming their structure and attributes,
creating new graphs, or printing arbitrary information.
The graph model is that provided by
.IR libagraph (3).
In particular, \fBgvpr\fP reads and writes graphs using the
dot language.
.PP
Basically,
.B gvpr
traverses each input graph, denoted by \fB$G\fP, visiting each node and edge,
matching it with the predicate\(hyaction rules supplied in the input program.
The rules are evaluated in order.
For each predicate evaluating to true, the corresponding 
action is performed. 
During the traversal, the current node or edge being visited
is denoted by \fB$\fP.
.PP
For each input graph, there is a target subgraph, denoted by
\fB$T\fP, initially empty and used to accumulate
chosen entities, and an output graph, \fB$O\fP, used for final processing
and then written to output. 
By default, the output graph is the target graph.
The output graph can be set in the program or, in a limited sense,
on the command line.
.SH OPTIONS
The following options are supported:
.TP
.BI \-a " args"
The string \fIargs\fP is split into whitespace\(hyseparated tokens, 
with the individual tokens
available as strings in the \fBgvpr\fP program 
as \fBARGV[\fI0\fP],...,ARGV[ARGC\-1]\fR.
Whitespace characters within single or double quoted substrings, or
preceded by a backslash, are ignored as separators. 
In general, a backslash character turns off any special meaning of the
following character.
Note that the tokens derived from multiple \fB\-a\fP flags are concatenated.
.TP
.B \-c
Use the source graph as the output graph.
.TP
.B \-i
Derive the node\(hyinduced subgraph extension of the output graph in the context 
of its root graph.
.TP
.BI \-o " outfile"
Causes the output stream to be written to the specified file; by default,
output is written to \fBstdout\fP.
.TP
.BI \-f " progfile"
Use the contents of the specified file as the program to execute
on the input. If \fIprogfile\fP contains a slash character, the name is taken
as the pathname of the file. Otherwise, \fBgvpr\fP will use the
directories specified in the environment variable \fBGPRPATH\fP to look
for the file. If 
.B \-f
is not given,
.B gvpr
will use the first non\(hyoption argument as the program.
.TP
.B \-V
Causes the program to print version information and exit.
.TP
.B \-?
Causes the program to print usage information and exit.
.SH OPERANDS
The following operand is supported:
.TP 8
.I files
Names of files containing 1 or more graphs in the dot language.
If no
.B \-f
option is given, the first name is removed from the list and used 
as the input program. If the list of files is empty, \fBstdin\fP will be used.
.SH PROGRAMS
A
.B gvpr
program consists of a list of predicate\(hyaction clauses, having one
of the forms:
.IP
.BI "BEGIN { "  action " }"
.IP
.BI "BEG_G { "  action " }"
.IP
.BI "N [ " predicate " ] { " action " }
.IP
.BI "E [ " predicate " ] { " action " }
.IP
.BI "END_G { "  action " }"
.IP
.BI "END { "  action " }"
.PP
A program can contain at most one of each of the \fBBEGIN\fP, \fBBEG_G\fP,
\fBEND_G\fP and \fBEND\fP clauses. 
There can be any number of \fBN\fP and \fBE\fP statements,
the first applied to nodes, the second to edges.
The top\(hylevel semantics of a \fBgvpr\fP program are:
.PP
.ta \w'\f(CWdelete array[expression]'u
.RS
.nf
Evaluate the \fBBEGIN\fP clause, if any.
For each input graph \fIG\fP {
    Set \fIG\fP as the current graph and current object.
    Evaluate the \fBBEG_G\fP clause, if any.
    For each node and edge in \fIG\fP {
      Set the node or edge as the current object.
      Evaluate the \fBN\fP or \fBE\fP clauses, as appropriate.
    } 
    Set \fIG\fP as the current object.
    Evaluate the \fBEND_G\fP clause, if any.
} 
Evaluate the \fBEND\fP clause, if any.
.fi
.RE
.DT
.PP
The actions of the \fBBEGIN\fP, \fBBEG_G\fP, \fBEND_G\fP and \fBEND\fP clauses
are performed when the clauses are evaluated.
For \fBN\fP or \fBE\fP clauses,
either the predicate or action may be omitted. 
If there is no predicate with an action, the action is 
performed on every node or edge, as appropriate.
If there is no action and the predicate evaluates to true,
the associated node or edge is added to the target graph. 
.PP
Predicates and actions are sequences of statements in the C dialect 
supported by the
.IR libexpr (3)
library.
The only difference between predicates and actions is that the former
must have a type that may interpreted as either true or false.
Here the usual C convention is followed, in which a non\(hyzero value is
considered true. This would include non\(hyempty strings and non\(hyempty
references to nodes, edges, etc. However, if a string can be 
converted to an integer, this value is used.
.PP
In addition to the usual C base types
(\fbvoid\fP, \fbint\fP, \fbchar\fP, \fbfloat\fP, \fblong\fP, 
\fbunsigned\fP and \fbdouble\fP), 
\fBgvpr\fP \fRprovides \fbstring\fP as a synonym for \fbchar*\fP, and 
the graph\(hybased types \fbnode_t\fP,
\fbedge_t\fP, \fbgraph_t\fP and \fbobj_t\fP.
The \fbobj_t\fP type can be viewed as a supertype of the other 3 concrete types;
the correct base type is maintained dynamically.
Besides these base types, the only other supported type expressions
are (associative) arrays. 
.PP
Constants follow C syntax, but strings may be quoted with either
\fB"..."\fP or \fB'...'\fP. In certain contexts, string values are
interpreted as patterns for the purpose of regular expression matching.
Patterns use<commit_msg>change \fb  to  \fB   to suppress warnings about missing font "b"<commit_after>.TH GVPR 1 "1 November 2005"
.SH NAME
gvpr \- graph pattern scanning and processing language
.br
( previously known as
.B gpr
)
.SH SYNOPSIS
.B gvpr
[\fB\-icV?\fP]
[
.BI \-o
.I outfile
]
[
.BI \-a
.I args
]
[
.I 'prog'
|
.BI \-f
.I progfile
]
[ 
.I files 
]
.SH DESCRIPTION
.B gvpr
is a graph stream editor inspired by \fBawk\fP.
It copies input graphs to its
output, possibly transforming their structure and attributes,
creating new graphs, or printing arbitrary information.
The graph model is that provided by
.IR libagraph (3).
In particular, \fBgvpr\fP reads and writes graphs using the
dot language.
.PP
Basically,
.B gvpr
traverses each input graph, denoted by \fB$G\fP, visiting each node and edge,
matching it with the predicate\(hyaction rules supplied in the input program.
The rules are evaluated in order.
For each predicate evaluating to true, the corresponding 
action is performed. 
During the traversal, the current node or edge being visited
is denoted by \fB$\fP.
.PP
For each input graph, there is a target subgraph, denoted by
\fB$T\fP, initially empty and used to accumulate
chosen entities, and an output graph, \fB$O\fP, used for final processing
and then written to output. 
By default, the output graph is the target graph.
The output graph can be set in the program or, in a limited sense,
on the command line.
.SH OPTIONS
The following options are supported:
.TP
.BI \-a " args"
The string \fIargs\fP is split into whitespace\(hyseparated tokens, 
with the individual tokens
available as strings in the \fBgvpr\fP program 
as \fBARGV[\fI0\fP],...,ARGV[ARGC\-1]\fR.
Whitespace characters within single or double quoted substrings, or
preceded by a backslash, are ignored as separators. 
In general, a backslash character turns off any special meaning of the
following character.
Note that the tokens derived from multiple \fB\-a\fP flags are concatenated.
.TP
.B \-c
Use the source graph as the output graph.
.TP
.B \-i
Derive the node\(hyinduced subgraph extension of the output graph in the context 
of its root graph.
.TP
.BI \-o " outfile"
Causes the output stream to be written to the specified file; by default,
output is written to \fBstdout\fP.
.TP
.BI \-f " progfile"
Use the contents of the specified file as the program to execute
on the input. If \fIprogfile\fP contains a slash character, the name is taken
as the pathname of the file. Otherwise, \fBgvpr\fP will use the
directories specified in the environment variable \fBGPRPATH\fP to look
for the file. If 
.B \-f
is not given,
.B gvpr
will use the first non\(hyoption argument as the program.
.TP
.B \-V
Causes the program to print version information and exit.
.TP
.B \-?
Causes the program to print usage information and exit.
.SH OPERANDS
The following operand is supported:
.TP 8
.I files
Names of files containing 1 or more graphs in the dot language.
If no
.B \-f
option is given, the first name is removed from the list and used 
as the input program. If the list of files is empty, \fBstdin\fP will be used.
.SH PROGRAMS
A
.B gvpr
program consists of a list of predicate\(hyaction clauses, having one
of the forms:
.IP
.BI "BEGIN { "  action " }"
.IP
.BI "BEG_G { "  action " }"
.IP
.BI "N [ " predicate " ] { " action " }
.IP
.BI "E [ " predicate " ] { " action " }
.IP
.BI "END_G { "  action " }"
.IP
.BI "END { "  action " }"
.PP
A program can contain at most one of each of the \fBBEGIN\fP, \fBBEG_G\fP,
\fBEND_G\fP and \fBEND\fP clauses. 
There can be any number of \fBN\fP and \fBE\fP statements,
the first applied to nodes, the second to edges.
The top\(hylevel semantics of a \fBgvpr\fP program are:
.PP
.ta \w'\f(CWdelete array[expression]'u
.RS
.nf
Evaluate the \fBBEGIN\fP clause, if any.
For each input graph \fIG\fP {
    Set \fIG\fP as the current graph and current object.
    Evaluate the \fBBEG_G\fP clause, if any.
    For each node and edge in \fIG\fP {
      Set the node or edge as the current object.
      Evaluate the \fBN\fP or \fBE\fP clauses, as appropriate.
    } 
    Set \fIG\fP as the current object.
    Evaluate the \fBEND_G\fP clause, if any.
} 
Evaluate the \fBEND\fP clause, if any.
.fi
.RE
.DT
.PP
The actions of the \fBBEGIN\fP, \fBBEG_G\fP, \fBEND_G\fP and \fBEND\fP clauses
are performed when the clauses are evaluated.
For \fBN\fP or \fBE\fP clauses,
either the predicate or action may be omitted. 
If there is no predicate with an action, the action is 
performed on every node or edge, as appropriate.
If there is no action and the predicate evaluates to true,
the associated node or edge is added to the target graph. 
.PP
Predicates and actions are sequences of statements in the C dialect 
supported by the
.IR libexpr (3)
library.
The only difference between predicates and actions is that the former
must have a type that may interpreted as either true or false.
Here the usual C convention is followed, in which a non\(hyzero value is
considered true. This would include non\(hyempty strings and non\(hyempty
references to nodes, edges, etc. However, if a string can be 
converted to an integer, this value is used.
.PP
In addition to the usual C base types
(\fBvoid\fP, \fBint\fP, \fBchar\fP, \fBfloat\fP, \fBlong\fP, 
\fBunsigned\fP and \fBdouble\fP), 
\fBgvpr\fP \fRprovides \fBstring\fP as a synonym for \fBchar*\fP, and 
the graph\(hybased types \fBnode_t\fP,
\fBedge_t\fP, \fBgraph_t\fP and \fBobj_t\fP.
The \fBobj_t\fP type can be viewed as a supertype of the other 3 concrete types;
the correct base type is maintained dynamically.
Besides these base types, the only other supported type expressions
are (associative) arrays. 
.PP
Constants follow C syntax, but strings may be quoted with either
\fB"..."\fP or \fB'...'\fP. In certain contexts, string values are
interpreted as patterns for the purpose of regular expression matching.
Patterns use
{'fraction_non_alphanumeric': 0.08002047432178809, 'fraction_numerical': 0.002218051527043167, 'mean_word_length': 3.4388489208633093, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7341856', 'n_tokens_mistral': 4008, 'n_tokens_neox': 3810, 'n_words': 1831}