Document <case.h> with own man page; bump date.

1 files changed, 158 insertions, 0 deletions

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.