Cfpeek User Manual (split by chapter):   Section:   Chapter:FastBack: Formats   Up: Top   FastForward: Exit Codes   Contents: Table of ContentsIndex: Concept Index

5 Cfpeek Command Line Syntax

The format of cfpeek invocation is:

cfpeek options file [keys]

where options are command line options, file is the configuration file to operate upon, and optional keys are pathnames of the keywords to locate in that configuration file.

If keys are supplied, cfpeek, for each key, looks up in the parse tree for any nodes matching the key and prints them on the standard output. An error message is displayed for any key which has no matching statements in the input file. In this case, program continues iterating over the rest of keys. When the list is exhausted, cfpeek will exit with the status 1 (see Exit Codes).

If either -f (--file) or -e (--expression) has been given, a Scheme expression or the default cfpeek function is evaluated for each matching node. If -e (--expression) is given, the node is passed to it in the global ‘node’ variable. Otherwise, if -f (--file) is given, the node is passed as argument to cfpeek function.

If both --file=script and --expression=expression options are given, the script file script is loaded first, and the expression is evaluated for each matching node. The expression can then refer to any variables and call any functions defined in the script.

If no keys are supplied, the program operates as if given a single ‘.*’ key (see Patterns), which matches any node in the parse tree (i.e., it iterates over the entire parse tree).

5.1 Patterns

By default cfpeek treats keys as wildcard patterns. When matching statement identifiers (keywords), two characters have special meaning: ‘%’ and ‘*’.

A ‘%’ character in place of an identifier matches any single keyword. Thus, e.g.:

cfpeek file.conf .%.bar.baz

will match ‘.foo.bar.baz’, ‘.qux.bar.baz’, but will not match ‘.bar.baz’ or ‘.x.y.bar.baz’.

A single ‘*’ character in place of a keyword matches zero or more keywords appearing in its place, so that:

cfpeek file.conf .*.bar.baz

The tags in block statement are matched using the traditional globbing patterns. See http://www.manpagez.com/man/3/fnmatch.

For example, this:

cfpeek file.conf .*.program="mh-*"

will match any ‘program’ block statement whose tag begins with ‘mh-’.

5.2 Output Control

-H flags
--format=flags

Set output format flags. The argument is a comma-separated list of format flags and relative movement options. Relative movement options select another node, relative to the one found. They are:

parent=id

Find a parent of the matching node, which has id as its identifier.

child=id

Find a child of the matching node, which has id as its identifier.

child=id

Find a sibling of the matching node, which has id as its identifier.

up=n

Ascend n parent nodes and print the node at which the ascent stopped.

descend=n

Descend n child nodes.

Any number of relative movement options can be specified. They are executed in the order of their appearance in the --format statement. For example, --format=up=2,sibling=foo,child=bar means: ascend two levels of hierarchy, find a node named ‘foo’, look for a node named ‘bar’ among the children of that node and print the result.

If evaluation of the relative movement options results in an empty node (e.g. the ‘up’ option attempts to go past the root of the tree), nothing is output.

The delim flag controls how keyword paths is printed:

delim=char

Sets path component delimiter, instead of the default ‘.’.

The following flags control the amount of information printed for each node. These are boolean flags: when prefixed with ‘no’ they have the meaning opposite to the described.

locus

Print source location of each configuration statement. A location is printed as the file name, followed by a semicolon, followed by the line number and another semicolon. Locations are separated from the rest of output by a single space character.

path

Print statement paths.

value

Print statement values.

quote

Always quote string values.

never-quote

Never quote string values.

quote-hex

Print non-printable characters as C hex escapes. This option is ignored if ‘noquote’ is set.

descend

Descend into subnodes. Set default options.

The default format options are: ‘path,value,quote,descend’.

-q
--quiet

Suppress error diagnostics. See quiet.

5.3 Modifiers

The following options modify the way cfpeek processes the parse tree and search keys.

-L
--literal

Use literal matching, instead of pattern matching. See literal.

-S
--sort

Before further processing, sort parse tree lexicographically in ascending order.

-m
--matches=number

Output at most number matches for each key.

-p
--parser=type

Set parser type for the input file. The argument is one of: ‘grecs’, ‘path’, ‘meta1’, ‘bind’, ‘dhcpd’, and ‘git’ (case-insensitive). See Formats, for a description of each type.

-r
--reduce

Reduce the parse tree, so that each keyword occurs no more than once at each tree level.

-s path=val
--set=path=val

Set a keyword path to value. The produced parse tree node will be processed as usual.

5.4 Scripting Options

The following options control the scripting facility of cfpeek.

-e expression
--expression=expression

Apply this expression to each node found. The global variable node is set to the node being processed before evaluating. When used together with --file=script, the expression can refer to any variables and call any functions defined in the script file.

-f file
--file=file

Load the script file. Unless --expression is also given, the script must define the function named ‘cfpeek’ which takes a node as its only argument. This function will be called for each matching node.

If --expression is given, this behavior is suppressed. It is then the responsibility of the expression to call any functions defined in this file.

-i expr
--init=expr

The --init=expr (-i expr) option provides an initialization expression expr. This expression is evaluated once, after loading the script file, if one is specified, and before starting the main loop.

-l script-language
--lang=script-language

Select scripting language to use. This option is reserved for further use. As of version 1.2, the only possible value for script-language is ‘scheme’.

5.5 Preprocessor Control Options

The options described below control the preprocessor facility. They are meaningful only for ‘GRECS’ and ‘BIND’ configuration files. Preprocessor is not used for another configuration file formats.

-Dname[=value]
--define=name[=value]

Define the preprocessor symbol name as having value, or empty. See Preprocessor.

-I dir
--include-directory=dir

Add dir to include search path.

See #include.

-N
--no-preprocessor

Disable preprocessor. see Preprocessor.

-P command
--preprocessor=command

Use command instead of the default preprocessor. see Preprocessor.

5.6 Debugging Options

The options below enable trace output which helps understand how configuration parser works. They are mainly useful for cfpeek developers.

-X
--debug-lexer

Trace configuration file lexer.

-x
--debug-parser

Trace configuration file parser.

5.7 Informational Options

--help
-h

Print a concise usage summary and exit.

--usage

Print a summary of command line syntax and exit.

--version
-v

Print the program version and exit.

Cfpeek User Manual (split by chapter):   Section:   Chapter:FastBack: Invocation   Up: Invocation   FastForward: Exit Codes   Contents: Table of ContentsIndex: Concept Index