diff options
| -rw-r--r-- | Makefile.am | 2 | ||||
| -rw-r--r-- | configure.ac | 3 | ||||
| -rw-r--r-- | doc/Makefile.am | 17 | ||||
| -rw-r--r-- | doc/cfpeek.1 | 459 | ||||
| m--------- | grecs | 0 | ||||
| -rw-r--r-- | src/cfpeek.c | 2 | ||||
| -rw-r--r-- | src/cmdline.opt | 2 |
7 files changed, 482 insertions, 3 deletions
diff --git a/Makefile.am b/Makefile.am index ef32b59..cdc0c53 100644 --- a/Makefile.am +++ b/Makefile.am @@ -16,7 +16,7 @@ ACLOCAL_AMFLAGS = -I grecs/am -I gint -SUBDIRS = grecs gint src +SUBDIRS = grecs gint src doc .PHONY: ChangeLog ChangeLog: diff --git a/configure.ac b/configure.ac index ba288e8..dd7b09e 100644 --- a/configure.ac +++ b/configure.ac @@ -52,6 +52,7 @@ dnl AM_MISSING_PROG([AUTOM4TE], [autom4te]) AC_CONFIG_FILES([Makefile gint/Makefile - src/Makefile]) + src/Makefile + doc/Makefile]) AC_OUTPUT diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..84cd73a --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,17 @@ +# This file is part of cfpeek +# Copyright (C) 2011 Sergey Poznyakoff +# +# Cfpeek is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3, or (at your option) +# any later version. +# +# Cfpeek is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with cfpeek. If not, see <http://www.gnu.org/licenses/>. + +dist_man_MANS = cfpeek.1 diff --git a/doc/cfpeek.1 b/doc/cfpeek.1 new file mode 100644 index 0000000..40c377b --- /dev/null +++ b/doc/cfpeek.1 @@ -0,0 +1,459 @@ +.\" This file is part of cfpeek -*- nroff -*- +.\" Copyright (C) 2011 Sergey Poznyakoff +.\" +.\" Cfpeek is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 3, or (at your option) +.\" any later version. +.\" +.\" Cfpeek is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with cfpeek. If not, see <http://www.gnu.org/licenses/>. +.\" +.TH CFPEEK 1 "May 23, 2011" "CFPEEK" "Cfpeek User Reference" +.SH NAME +cfpeek \- retrieve values from a structured configuration file +.SH SYNOPSIS +.B cfpeek +[\fIOPTION\fR]... \fIFILE \fR[\fIPATH\fR...] +.SH DESCRIPTION +Structured configuration files keep program configuration values in a +hierarchical structure. Examples of such files are +.BR mailutils.conf , +used by \fBGNU Mailutils\fR, +.BR named.conf , +used by \fBnamed\fR, +or +.BR ~/.gitconfig , +used by \fBGIT\fR. +.PP +These files, although differing in syntax, keep the information in a +hierarchical structure. +.PP +.B Cfpeek +provides a uniform and consistent command line interface for various +operations over such files. It can be used to retrieve configuration +values, both by literal keyword matches and by using wildcard +patterns, to reformat the files in arbitrary way, and to apply an +external script to each statement in the file. +.PP +This manpage is a short description of \fBcfpeek\fR. +For a detailed discussion, including examples of the configuration and +usage recommendation, refer to the \fBCfpeek User Manual\fR available in +Texinfo format. To access it, run: +.PP + \fBinfo cfpeek\fR +.PP +Should any discrepancies occur between this manpage and the +\fBCfpeek User Manual\fR, the later shall be considered the authoritative +source. +.SS Input formats +.B Cfpeek +is able to handle input files in several formats: +.TP +.B GRECS +The default input format. This format is used, +e.g., by \fBGNU Dico\fR, \fBGNU Mailutils\fR, \fBMailfromd\fR and +others. The following is a short description. See +.BR grecs_config (5), +for a detailed discussion of the format and its features. +.sp +The \fBGRECS\fR input file consists of +.I simple +and +.B block +statements. Simple statements consist of a keyword and value, +separated by any amount of whitespace. Simple statements are +terminated with a semicolon, e.g.: +.sp +.nf +.in +2 +wakeup 15; +.in +.fi +.sp +A value can be either a single scalar value, as in the example above, +or several values, separated by whitespace, or a \fIlist of values\fR: +a comma-separated list, enclosed in a pair of braces, e.g.: +.sp +.nf +.in +2 +path ("/usr","/usr/bin"); +.in +.fi +.sp +Block statements are used for logical grouping of other +statements. A block statement consists of a keyword, optionally +followed by a value, and a set of other statements, enclosed in a pair +of curly brackets, e.g.: +.sp +.nf +.in +2 +syslog { + facility local1; + tag foo; +} +.in +.fi +.sp +A semicolon may follow the closing \fB}\fR, although this is not +required. +.sp +The whitespace (i.e. space characters, tabs and newlines) has +no special syntactical meaning, except that it serves to separate +otherwise adjacent tokens. +.sp +Several types of comments are supported. A single-line comment +starts with a \fB#\fR or \fB//\fR and continues to the end of the line. A +multi-line comment starts with the two characters \fB/*\fR +(slash, star) and continues until the first occurrence of \fB*/\fR (star, +slash). Whatever comment type are used, they are removed from the +configuration prior to parsing it. +.sp +After comment removal, the Grecs configuration is normally +preprocessed using \fBm4\fR. +.TP +.B PATH +A line-oriented \*(lqkeyword path\*(rq format. It is similar to +X-resource format, used by \fBX\fR window system configuration files. +Each line consists of a keyword pathname, followed by a semicolon, a +single space character and the value of that keyword. +.sp +Comments (introduced with a \fB#\fR character) and empty lines are +ignored. +.sp +This format is used by default in \fBcfpeek\fR output. +.TP +.B BIND +The format used by \fBnamed\fR DNS daemon. It is similar to +\fBGRECS\fR, except that it requires the use of semicolon after block +statements, does not support list values and here-document syntax, etc. +See +.BR named.conf (5), +for a detailed description. +.TP +.B META1 +The format used by \fBMeTA1\fR configuration file. Similar to +\fBGRECS\fR, in some aspects. The most prominent differences are: +the use of the equals sign between the keyword and its value and +the use of curly brackets to enclose list values. Only one-line +comments are allowed, the \fB#\fR serves as a comment starter. +See +.B http://www.meta1.org, +for a detailed description. +.TP +.B GIT +The format used by \fBgit\fR configuration files. See the section +\fBCONFIGURATION FILE\fR in +.BR git-config (1). +.SH OPTIONS +.SS Output control +.TP +\fB\-H\fR, \fB\-\-format\fR=\fIFLAGS\fR +Sets output format flags. \fIFLAGS\fR is a comma-separated list of +one or more of the following: +.sp +.RS +.PD 0 +.TP +\fBparent\fR=\fINAME\fR +Search for a parent node with the given \fINAME\fR and print it. +.TP +\fBup\fR=\fIN\fR +Print \fIN\fRth parent node. +.TP +\fBdelim\fR=\fICHAR\fR +Use \fICHAR\fR as path component delimiter, instead of the default dot. +.TP +.B [no]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. +.TP +.B [no]path +Print the statement \fIpath\fR. See +.BR grecs_stmt_path(5), +for a description. + +If printed, the path is separated from the rest of output on +its right by a semicolon and a space. +.TP +.B [no]value +Print the statement value. +.TP +.B [no]quote +Always quote values. By default, the value will be quoted +only when necessary, i.e. if it contains white space, quotes or +special characters. +.TP +.B [no]never\-quote +Never quote values. +.TP +.B [no]quote\-hex +Print non-printable characters as C hex escapets. This option +is ignored if \fBnoquote\fR is set. +.TP +.B [no]descend +Descend into subnodes. +.TP +.B [no]default +Set default options. This is equivalent to: +.sp +.ti +5 +delim=.,path,value,quote +.PD +.LP +.RE +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Suppress error diagnostics. +.SS Modifiers +.TP +\fB\-L\fR, \fB\-\-literal\fR +use literal matching +.TP +\fB\-S\fR, \fB\-\-sort\fR +sort parse tree lexicografically +.TP +\fB\-m\fR, \fB\-\-matches\fR=\fINUMBER\fR +output at most NUMBER matches +.TP +\fB\-p\fR, \fB\-\-parser\fR=\fITYPE\fR +Select input parser type. Valid values for \fITYPE\fR are: +.sp +.RS +.PD 0 +.TP +.B GRECS +File format used by the \fBGrecs\fR library. This format is used, +e.g., by \fBGNU Dico\fR, \fBGNU Mailutils\fR, \fBMailfromd\fR and +others. This is the default. See +.BR grecs_config (5), +for a detailed description. +.TP +.B META1 +Format used by \fBMeTA1\fR configuration file. See +.B http://www.meta1.org. +.TP +.B BIND +Format used by \fBnamed\fR. See +.BR named.conf (5) +.TP +.B GIT +Format used by \fBgit\fR configuration files. See the section +\fBCONFIGURATION FILE\fR in +.BR git-config (1). +.TP +.B PATH +Keyword path format. +.PD +.RE +.TP +\fB\-r\fR, \fB\-\-reduce\fR +Reduce the parse tree, so that each keyword occurs no more than once +at each tree level. +.TP +\fB\-s\fR, \fB\-\-set\fR=\fIPATH=VALUE\fR +Set a keyword \fIPATH\fR to \fIVALUE\fR. This will be reflected in +the output, +.SS Scripting +.TP +\fB\-e\fR, \fB\-\-expr\fR=\fIEXPRESSION\fR +Apply this Scheme expression to each node found. +.TP +\fB\-f\fR, \fB\-\-file\fR=\fIFILE\fR +Apply the Scheme script \fIFILE\fR to each node found. The script must +define the function \fB(cfpeek node)\fR. See the section +.B SCRIPTING, +for a detailed description. If both \fB\-\-file\fR and \fB\-\-expr\fR +are given, the file is loaded first, and expression is applied to each +node. +.TP +\fB\-l\fR, \fB\-\-lang\fR=\fINAME\fR +Select scripting language to use. This is reserved for future use. +.SS Preprocessor control +\fBGRECS\fR input files are preprocessed by default using \fBm4 -s\fR. +\fBBIND\fR input files are preprocessed only if the +\fB\-\-preprocessor\fR option (see below) is given, which specifies +the preprocessor binary to use. +.PP +Files in another input formats are never preprocessed. +.PP +The options below control the preprocessor invocation for those +formats that support it. +.TP +\fB\-D\fR, \fB\-\-define=SYMBOL\fR[=\fIVALUE\fR] +Define a preprocessor symbol. +.TP +\fB\-I\fR, \fB\-\-include\-directory\fR=\fIDIR\fR +Add \fIDIR\fR to the list of files searched for include files. +.TP +\fB\-\-no\-preprocessor\fR +Disable preprocessing. +.TP +\fB\-\-preprocessor\fR=\fICOMMAND\fR +Use \fICOMMAND\fR as a preprocessor, instead of the default \fBm4\fR. +.SS Debugging +.TP +\fB\-X\fR, \fB\-\-debug\-lexer\fR +Debug configuration file lexer. +.TP +\fB\-x\fR, \fB\-\-debug\-parser\fR +Debug configuration file parser. +.SS Other options +.TP +\fB\-V\fR, \fB\-\-version\fR +Print program version. +.TP +\fB\-h\fR, \fB\-\-help\fR +Print a short option summary. +.TP +\fB\-\-usage\fR +Print a short usage message and a list of available options. +.SH SCRIPTING +.SH EXAMPLES +.SS 1. +The following prints the entire contents of the +.BR /etc/dico.conf : +.P +.nf +.B $ cfpeek /etc/dico.conf +.fi +.SS 2. +The following prints the contents of +.BR /etc/named.conf : +.P +.nf +.B $ cfpeek --parser=bind /etc/named.conf +.fi +.SS 3. +This will print the value of the \fBpid-file\fR keyword from the +\fBoptions\fR section of +.BR /etc/named.conf : +.P +.nf +.B $ cfpeek --parser=bind /etc/named.conf .options.pid-file +.fi +.P +The output will look like: +.P +.nf + .options.pid-file: /var/run/named.pid +.fi +.P +To make it output only the value, without the keyword path, use the +.B \-\-format +option: +.P +.nf +.B $ cfpeek --parser=bind --format=value /etc/named.conf .options.pid-file +.fi +.SS 4. +Use of the above in a startup/shutdown script to brind \fBnamed\fR +down: +.P +.in +5 +.nf +PIDFILE=`cfpeek --parser=bind --format=value \\ + /etc/named.conf .options.pid-file` +if [ -R $PIDFILE ] +then + kill -TERM `head -1 $PIDFILE` +fi +.fi +.in +.SS 5. +Find and print every occurrence of \fBfacility\fR keyword in +.BR /etc/mailutils.rc : +.P +.nf +.B $ cfpeek /etc/mailutils.rc .*.facility +.fi +.SS 6. +The same, but print only the locations where the keyword occurred: +.P +.nf +.B $ cfpeek --format=locus /etc/mailutils.rc .*.facility +.fi +.SS 7. +Apply the script \fBmaster-zone.scm\fR to each statement from the file +.BR /etc/named.conf: +.P +.nf +.B $ cfpeek --parser=bind --script=master-zone.scm /etc/named.conf . +.fi +.P +Notice the final dot, which refers to the root of the parse tree. +.SS 8. +Apply the script \fBmaster-zone.scm\fR to each \fBzone\fR statement +which occurs within the \fBview \(dqexternal\(dq\fR section: +.P +.nf +.B $ cfpeek --parser=bind --script=master-zone.scm /etc/named.conf \\\\ +.ti +2 +.B .view=external.zone +.fi +.SS 9. +Print the file name of each master zone in the +.B /etc/named.conf +file: +.P +.nf +.B $ cfpeek --parser=bind -e ' +.ti +3 +.B (if (and (string=? (grecs-node-ident node) \(dqtype\(dq) +.ti +12 +.B (string=? (grecs-node-value node) \(dqmaster\(dq)) +.ti +7 +.B (format #t \(dq~A~%\(dq (grecs-node-value (grecs-find-node +.ti +24 +.B (grecs-node-head node) \(dqfile\(dq))))' \\\\ +.ti +10 +.B /etc/named.conf + +.SH "SEE ALSO" +.BR grecs_stmt_path (5), +.BR grecs_config (5), +.BR m4 (1). +.PP +The full documentation for +.B cfpeek +is maintained as a Texinfo manual. If the +.B info +and +.B cfpeek +programs are properly installed at your site, the command +.IP +.B info cfpeek +.PP +should give you access to the complete manual. +.PP +An online copy of the latest +.B cfpeek +documentation is available from <http://www.gnu.org.ua/software/cfpeek>. +.SH AUTHORS +Sergey Poznyakoff +.SH "BUG REPORTS" +Report bugs to <gray+cfpeek@gnu.org.ua>. +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> +.br +.ad +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.\" Local variables: +.\" eval: (add-hook 'write-file-hooks 'time-stamp) +.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \"" +.\" time-stamp-format: "%:B %:d, %:y" +.\" time-stamp-end: "\"" +.\" time-stamp-line-limit: 20 +.\" end: + diff --git a/grecs b/grecs -Subproject 24f55db22433621dc80a068583b4bf8886ae260 +Subproject 63da417be1dfe1366a4a8984770c06cbbadcda3 diff --git a/src/cfpeek.c b/src/cfpeek.c index 7b8bfee..148ce79 100644 --- a/src/cfpeek.c +++ b/src/cfpeek.c @@ -18,7 +18,7 @@ #include "cfpeek.h" int file_index; -int flags = GRECS_NODE_FLAG_PATH|GRECS_NODE_FLAG_VALUE; +int flags; int quiet_option; int reduce_option; int sort_option; diff --git a/src/cmdline.opt b/src/cmdline.opt index df897e0..d4e329b 100644 --- a/src/cmdline.opt +++ b/src/cmdline.opt @@ -341,6 +341,8 @@ parse_options(int argc, char *argv[]) program_name = argv[0]; print_help_hook = flags_help; GETOPT(argc, argv, file_index, exit(EX_USAGE)) + if (!flags) + flags = GRECS_NODE_FLAG_PATH|GRECS_NODE_FLAG_VALUE; if (preproc_settings == PREPROC_DEFAULT) grecs_preprocessor = DEFAULT_PREPROCESSOR; if (pp_cmd_acc && grecs_preprocessor) { |