diff options
Diffstat (limited to 'cppawk.1')
| -rw-r--r-- | cppawk.1 | 146 |
1 files changed, 73 insertions, 73 deletions
@@ -9,69 +9,69 @@ cppawk [cpp, awk and cppawk options] [awk arguments] cppawk --prepro-only [cpp, awk and cppawk options] .SH DESCRIPTION -.B cppawk +.I cppawk is a shell script which passes awk code through the standalone C preprocessor, and then invokes awk on the preprocessed code. This allows Awk code to be written which uses C preprocessor -.BI #define +.B #define macros, -.BI #include +.B #include C comments, trigraphs (though perish the thought) and backslash continuation. -.B cppawk +.I cppawk deliberately has an invocation syntax similar to Awk, and understands certain Awk options such as -.BI -f +.B -f and also understands -.B cpp +.I cpp options, such as -.BI -Dfoo=bar +.BI -Dfoo= bar for pre-defining a macro. Just like with -.BR awk , +.IR awk , code is specified either directly as the first non-option argument, or via the -.BI -f +.B -f option which indicates a file. In either situation, -.B cppawk +.I cppawk preprocesses the code and places the result in a temporary file which is then executed as -.B awk +.I awk code. .SH OPTIONS Any option not described here is assumed to be an Awk option which takes no argument, and is consequently passed through to the -.B awk +.I awk program. -.IP "\fB\-\-\fR" +.IP "\fB--\fR" End of options: any subsequent argument is the first non-option argument, even if it looks like an option. -.IP "\fB\-\-prepro\-only\fR" +.IP "\fB--prepro-only\fR" Do not run the preprocessed Awk program; dump the preprocessed code to standard output. -.IP "\fB\-\-awk=\fR\fIpath\fR" +.IP "\fB--awk=\fR\fIpath\fR" Specify alternative Awk implementation. If it contains no slashes, then -.BI PATH +.B PATH is searched to find the program. If the base name of the program is -.BI gawk +.I gawk or -.BI mawk, +.I mawk, then, respectively, one of the preprocessor symbols -.BI __gawk__ +.B __gawk__ or -.BI __mawk__ +.B __mawk__ is predefined, with a value of 1. This happens immediately when this option is processed, so can be counter-acted by a subsequent -.BI -U +.B -U option. .IP "\fB\-\-prepro=\fR\fIpath\fR" Specify alternative preprocessor. If it contains no slashes, then -.BI PATH +.B PATH is searched to find the program. .IP "\fB\-f\fR \fIfilename\fR" @@ -79,76 +79,76 @@ Read the awk program from .I filename rather than processing awk code from the first non-option command-line argument. The program is preprocessed to a temporary file, and -.B awk +.I awk is then invoked on this file. The file is deleted when -.B awk +.I awk terminates. -.IP "\fB\-\-nobash\fR" +.IP "\fB--nobash\fR" Pretend that the shell which executes -.B cppawk +.I cppawk isn't GNU Bash, even if it is. This has the effect of disabling the use of process substitution in favor of the use of a temporary file. -.IP "\fB\-\-dump-macros\fR" +.IP "\fB-\dump-macros\fR" Instruct the preprocessor to dump all of the -.BI #define +.B #define directives instead of the preprocessed output. Since this is only useful with -.BI --prepro-only +.B --prepro-only that option is implied. .IP "\fB\-M\fR, \fB\--bignum\fR" These two equivalent GNU Awk options are passed through to -.BR awk , +.I awk , which will understand them if it is GNU Awk. Using either of them causes the preprocessor symbol -.BI __bignum__ +.B __bignum__ to be defined with the value 1. .IP "\fB\-P\fR, \fB\--posix\fR" These two equivalent GNU Awk options are passed through to -.BR awk , +.I awk , which will understand them if it is GNU Awk. Using either of them causes the preprocessor symbol -.BI __posix__ +.B __posix__ to be defined with the value 1. .IP "\fB\-M...\fR Any optional argument beginning with -.BI -M +.B -M and followed by one or more characters results in a diagnostic message and failed termination. The intent is that the -.BI -M +.B -M family of options that are supported by GNU cpp are not supported by -.BR cppawk . +.IR cppawk . .IP "\fB-F\fR, \fB-v\fR, \fB-E\fR, \fB-i\fR, \fB-l\fR, \fB-L\fR" -These standard and GNU Awk options are recognizes by -.B cppawk +These standard and GNU Awk options are recognized by +.I cppawk as requiring an argument. They are validated for the presence of the required argument, and passed to -.BR awk . +.IR awk . .IP "\fB-U...\fR, \fB-D...\fR, \fB-I...\fR, \fB-iquote...\fR" Options which match these patterns are passed to the -.B cpp +.I cpp program instead of -.BR awk . +.IR awk . .SH PREDEFINED SYMBOLS .IP \fB__gawk__\fR When -.B cppawk +.I cppawk installation is configured to use GNU Awk, which is the default, the preprocessor symbol -.BI __gawk__ +.I __gawk__ is predefined with a value of 1. See the -.BI --awk +.I --awk option. .IP \fB__cppawk_ver\fR This preprocessor symbol gives the version of -.BR cppawk . +.IR cppawk . Its value is a is an eight digit decimal integer the form .IR YYYYMMDD , such as 20220321. @@ -156,18 +156,18 @@ such as 20220321. .SH CONFIGURATION SYMBOLS .IP \fB__gawk_ver\fR Certain -.B cppawk +.I cppawk header files may have functionality that depends on GNU Awk. The -.BI __gawk_ver +.B __gawk_ver variable may be set by the application to indicate which version of GNU Awk should be assumed by those library headers. The headers will avoid generating code that doesn't work with later versions than this. This variable should be set before including any header files, or using the -.BI -D +.B -D option on the command line. The variable should be a decimal integer, whose last four digits encode the minor @@ -184,27 +184,27 @@ Lower values than 40000 are not supported; code that requires GNU Awk assumes at least version 4.0. .SH STANDARD HEADERS -.B cppawk +.I cppawk points the preprocessor to look for -.BI "#include <...>" +.B "#include <...>" files in its own directory, which contains a library of header files that accompany -.BR cppawk . +.IR cppawk . -.IR <narg.h> +.IP \fB<narg.h>\fR This header provides macros which make it easy to write variable-argument macros with complex expansions. This is documented in the -.B cppawk-narg +.I cppawk-narg manual page. -.IR <case.h> +.IP \fB<case.h>\fR This header provides macros for writing a -.BI case +.B case statement. The case statement syntax is designed so that a GNU Awk switch statement is easily converted to it. The preprocessor translates it back to a clean GNU Awk switch statement, or to portable Awk code that runs on other Awks. The contents of this header are documented by the -.B cppawk-case +.I cppawk-case manual page. .SH EXAMPLES @@ -212,7 +212,7 @@ Print the larger of field 1 or 2: cppawk '// C comment #define max(a, b) ((a) > (b) ? (a) : (b)) - { print max($1, $2) /* C comment */ } #awk comment' + { print max($1, $2) /* C comment */ } #awk comment' Implement awk-like processing loop within function, to process /proc/mounts: @@ -232,7 +232,7 @@ Implement awk-like processing loop within function, to process } Where -.BI awkloop.h +.B awkloop.h contains: #define awkloop(file) for (; getline < file || (close(file) && 0); ) @@ -244,35 +244,35 @@ awk(1), cpp(6) .SH BUGS The -.BI -f +.B -f option can be given only once, whereas -.B awk +.I awk accepts multiple -.BI -f +.B -f options, and executes each of the indicated files. Awk error messages are reported against the preprocessed text. Awk -.BI # +.B # comments cannot be used at the start of a line because -.BI # +.B # begins a preprocessing directive. They also cannot be used inside a preprocessing directive, such as a macro definition, because -.BI # +.B # is an operator in the preprocessor language. It may be a good idea to avoid -.BI # +.B # comments entirely in -.B cppawk +.I cppawk source, and use only C comments. The -.B cpp +.I cpp program tokenizes text using C preprocessor rules. Because Awk is "C-like", there is a lot of compatibility between that and Awk syntax, which is why -.B cppawk +.I cppawk works at all; however, there may be corner cases where some issue arises because of this. One example is that double quote characters may be used in Awk regular expressions such as @@ -291,16 +291,16 @@ original file. Although the preprocessed output indicates source file and line number information, Awks do not understand this. The default choices of -.B gawk +.I gawk and -.B cpp +.I cpp are fixed in the source code; users must edit -.B cppawk +.I cppawk to select alternative implementations or locations of these tools, if they don't wish to use the -.BI --awk +.B --awk and -.BI --prepro +.B --prepro command line options. .SH AUTHOR |