diff options
| -rwxr-xr-x | cppawk | 2 | ||||
| -rw-r--r-- | cppawk-case.1 | 158 | ||||
| -rw-r--r-- | cppawk.1 | 17 |
3 files changed, 173 insertions, 4 deletions
@@ -33,7 +33,7 @@ incopt=-iquote # GNU extension: must be changed to -I for traditional cpp dumpopt=-dM # GNU cpp option to dump macros stdopt=-std=c99 # GNU cpp option for standard conformance awk=gawk -prepro_opts="-D__gawk__=1 -D__cppawk_ver=20220325 $stdopt" +prepro_opts="-D__gawk__=1 -D__cppawk_ver=20220328 $stdopt" # globals bash=${BASH_VERSION+y} diff --git a/cppawk-case.1 b/cppawk-case.1 new file mode 100644 index 0000000..c542dc7 --- /dev/null +++ b/cppawk-case.1 @@ -0,0 +1,158 @@ +.TH CPPAWK-CASE 1 "28 March 2022" "cppawk Libraries" "Case Macro" + +.SH NAME +case \- macro for portable switch statement + +.SH SYNOPSIS + #include <case.h> + + case (expr) { + of ("abc") + print "single key abc case" + cbreak + + of (1, 2, 3) + print "multi-key 1, 2, 3 case" + cfall # fall through + + matching (/regex1/, /regex2/, /regex3/) + print "regex case" + cbreak + + otherwise + print "default case" + } + +.SH DESCRIPTION +The +.BI case +macro provides syntax which +.B cppawk +translates very directly to the GNU Awk +.BI switch +statement, or else to alternative code which works with other Awk implementations. + +The purpose of the macro is easy conversion of +.BI switch +code; therefore, it has the same semantics with regard to fall through between +cases, requiring an explicit break. + +The clauses of +.BI case +are labeled with the identifiers +.BI of +and +.BI matching, +which take arguments, and are followed by one or more statements. The last one +of those statements must always be a +.BI cbreak, +.BI cfall +or +.BI cret +statement, described below. + +Regular expression keys must use the +.BI matching +label; ordinary keys compared for equality must use the +.BI of +label. + +The +.BI of +and +.BI matching +macros take variable arguments. Multiple matching keys or regular expressions +are specified as multiple arguments, rather than by repetition of the +construct: + + of (3) of (4) print "3 or 4"; cbreak // incorrect + + of (3, 4) print "3 or 4"; cbreak // correct + +Each clause must specify how it terminates: whether it breaks out of the +.BI case +statement, "falls through" to the next case, or returns from the surrounding +function. The macros +.BI cbreak, +.BI cfall +and +.BI cret +must be used for this purpose. The +.BI cret +macro takes exactly one argument, the expression whose value is to be +returned from the surrounding function: + + function f(input, + case_temps) + { + case (input) { + match (/abc/) + print "match on regex /abc/" + cret(1) + + otherwise + cbreak + } + + // other logic + return 0 + } + +When +.BI case +is transformed into portable code rather than +.BI switch, +that code depends on hidden state variables. +If +.BI case +is used in a top-level +.BI BEGIN, +.BI END +or Awk action, those variables will be global. +They will also be global if +.BI case +is used in a function, unless defined as local variables in the parameter list. + +Defining the temporary variables as local is done using the provided +.BI case_temps +macro: + + #include <case.h> + + function fun(x, y, z, # arguments + a, b, # locals + case_temps) # locals for case + { + case (x) { + of (42) { + ... + } + ... + } + } + +.BI case_temps +does not have to be in the last argument position. It is guaranteed to expand to one or +more identifiers separated by commas, with no leading or trailing comma. When the target +is GNU Awk, +.BI case_temps +expands to an unspecified identifier in the +.BI __[a-z] +reserved namespace. + +.SH "SEE ALSO" + +cppawk(1) + +.SH BUGS +The +.BI cond +macro does not currently safely nest with itself. + +Forgetting to declare the temporary variables is a programmer pitfall. + +.SH AUTHOR +Kaz Kylheku <kaz@kylheku.com> + +.SH COPYRIGHT +Copyright 2022, BSD2 License. @@ -1,4 +1,4 @@ -.TH CPPAWK 1 "25 March 2022" "Utility Commands" "Awk With C Preprocessing" +.TH CPPAWK 1 "28 March 2022" "Utility Commands" "Awk With C Preprocessing" .SH NAME cppawk \- wrapper for awk, with C preprocessing @@ -187,8 +187,19 @@ assumes at least version 4.0. .B cppawk points the preprocessor to look for .BI "#include <...>" -files in its own directory. There are currently no files -in this directory. +files in its own directory, which contains a library of header files that accompany +.BR cppawk . + +.IR <case.h> +This header provides macros for writing a +.BI 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 +manual page. .SH EXAMPLES Print the larger of field 1 or 2: |