From 5293e86e5185b959a442633c93445ecfde107d1e Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Sun, 17 Jul 2022 18:55:55 -0700
Subject: Implement -E option and <safearg.h> header.

The -E option is not passed through to the Awk implementation
any more, which is not particularly useful, because the option
resembles -f, and its argument requires likewise handling.

We achieve the semantics that -E <name> is equivalent to
-f <name> --.

From the GNU Awk user's perspective, this is a regression
in the semantics of -E which also has the effect of suppressing
the processing of arguments which look like variable assignments.
To make up for that, we provide the <safearg.h> header which
suppresses all implicit treatment of the remaining arguments.
---
 cppawk.1 | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 64 insertions(+), 1 deletion(-)

(limited to 'cppawk.1')

diff --git a/cppawk.1 b/cppawk.1
index 3416fc4..33627e6 100644
--- a/cppawk.1
+++ b/cppawk.1
@@ -110,6 +110,69 @@ is then invoked on this file. The file is deleted when
 .I awk
 terminates.
 
+.IP "\fB\-E\fR \fIfilename\fR"
+The
+.B -E
+option is inspired by that of GNU Awk;
+.B cppawk
+implements a form of this option itself, for all Awk back-ends,
+and does not pass it through to GNU Awk.
+This option combines the semantics of the
+.B -f
+and
+.B --
+options. Arrangements are made for the awk program to be read from
+a file exactly as described above for the
+.B -f
+option. Then, no more options are processed.  Any remaining option-like
+arguments are ordinary arguments.
+
+Note that unlike GNU Awk's
+.B -E
+options,
+.BR cppawk 's
+.B -E
+option doesn't suppress the processing of arguments which look like
+variable assignments.
+
+Instead, the program may specify the following preprocessing directive, outside
+of any Awk block or function:
+
+.ft B
+  #include <safearg.h>
+.ft R
+
+this directive produces a
+.B BEGIN
+clause which prepares an associate array named
+.B argv
+that contains the same key/value pairs as the standard
+.BR ARGV .
+The
+.B ARGV
+array is then deleted. Consequently, Awk will not process
+and perform the command line variable assignments, which normally
+occurs after the
+.B BEGIN
+clauses are processed.
+The effects of
+.B "<safearg.h>" are not visible to
+.B BEGIN
+clauses which are placed earlier than the inclusion of
+.BR "<safearg.h>" .
+Those earlier clauses have access to the original
+.B ARGV
+array.
+
+However, the combination of
+.B -E
+option and
+.B "<safearg.h>"
+is still not equivalent to GNU Awk's
+.B -E
+option, because no filename arguments are available for implicit
+use in the Awk pattern processing loop.
+
 .IP "\fB--nobash\fR"
 Pretend that the shell which executes
 .I cppawk
@@ -148,7 +211,7 @@ message and failed termination. The intent is that the
 family of options that are supported by GNU cpp are not supported by
 .IR cppawk .
 
-.IP "\fB-F\fR, \fB-v\fR, \fB-E\fR, \fB-i\fR, \fB-l\fR, \fB-L\fR"
+.IP "\fB-F\fR, \fB-v\fR, \fB-i\fR, \fB-l\fR, \fB-L\fR"
 These standard and GNU Awk options are recognized by
 .I cppawk
 as requiring an argument. They are validated for the presence of the
-- 
cgit v1.2.3