New <field.h> header: positional parameter utils.

1 files changed, 188 insertions, 0 deletions

diff --git a/cppawk-field.1 b/cppawk-field.1
new file mode 100644
index 0000000..6389540
--- /dev/null
+++ b/cppawk-field.1
@@ -0,0 +1,188 @@
+.\" cppawk: C preprocessor wrapper around awk
+.\" Copyright 2022 Kaz Kylheku <kaz@kylheku.com>
+.\"
+.\" BSD-2 License
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright notice,
+.\"    this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright notice,
+.\"    this list of conditions and the following disclaimer in the documentation
+.\"    and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.de bk
+.IP " "
+.PP
+..
+.TH CPPAWK-FIELD 1 "19 April 2022" "cppawk Libraries" "Field Utilities"
+
+.SH NAME
+.I field
+\- utilities for working with positional parameters ("fields")
+
+.SH SYNOPSIS
+.ft B
+  #include <field.h>
+
+  delf(\fIi\fP[, \fIn\fP])      \fI// delete n fields starting with i.\fP
+  insf(\fIi\fP, ...)      \fI// insert one or more fields at position i.\fP
+.ft R
+
+.SH DESCRIPTION
+.bk
+The
+.I <field.h>
+header provides utilities for performing bulk operations on Awk positional
+parameters, also referred to as fields.
+
+.SS Function \fIdelf\fP
+.bk
+.B Syntax:
+
+.ft B
+  delf(\fIi\fP[ ,\fIn\fP])
+.ft R
+
+.B Description:
+
+The
+.B delf
+function deletes
+.I n
+fields starting at field
+.IR i .
+
+If
+.I i
+exceeds
+.B NF
+or is less than
+.BR 1 ,
+or if
+.I n
+is less than 1, the function has no effect.
+
+If
+.I n
+is omitted, it defaults to 1: one field is deleted.
+
+If there are fields after the deleted fields, they are relocated so
+that they start at position
+.I i
+and
+.B NF
+is adjusted accordingly.
+
+If there are are only
+.B n
+or fewer fields starting at position
+.BR i ,
+then no fields have to be moved. In this case,
+.B NF
+is simply adjusted to the value of
+.I i
+.B "- 1"
+to trim the fields away.
+
+In all cases when
+.B NF
+is adjusted or fields are moved, the record
+.B $0
+is re-calculated in accordance with the Awk semantics for field manipulation.
+
+.SS Macro \fIinsf\fP
+.bk
+.B Syntax:
+
+.ft B
+  insf(\fIi\fP, ...)
+.ft R
+
+.B Description:
+
+The
+.B insf
+macro expands to a statement which inserts one or more fields at position
+.IR i .
+The number of fields inserted is determined by the number of variable
+arguments after
+.IR i ,
+of which there must be between 1 and 32. These are the
+.IR "field arguments" .
+
+If
+.I i
+is less than 1, there is no effect. In that case, the argument expressions
+which give the inserted field values are also not evaluated.
+
+Let
+.I n
+be the number of field arguments being inserted.
+
+The
+.I i
+argument may be greater than
+.BR NF ,
+in which case the specified fields are created, and
+.B NF
+is adjusted to include all of them in the position parameter array;
+.B NF
+will take on the value
+.I i
+.B +
+.IR n .
+
+If
+.I i
+is between 1 and
+.BR NF ,
+then the existing fields from
+.I i
+to
+.B NF
+move to higher positions to create a space for the inserted fields.
+Field
+.BI $ i
+moves to
+.BI $( i " + " n )
+and so forth. Then the
+.I n
+field parameters are assigned into the positions
+.BI $ i \fR,\fP
+.BI $( i " + 1)" \fR,\fP
+\fR...,\fP
+.BI $( i " + " n " - 1)" \fR.\fP
+
+In all cases when
+.B NF
+is adjusted and fields are assigned or moved, the record
+.B $0
+is re-calculated in accordance with the Awk semantics for field manipulation.
+
+.SH SEE ALSO
+cppawk(1), cppawk-cons(1)
+
+.SH BUGS
+The
+.B insf
+function is limited to 32 variadic arguments.
+
+.SH AUTHOR
+Kaz Kylheku <kaz@kylheku.com>
+
+.SH COPYRIGHT
+Copyright 2022, BSD2 License.