From 49b387bb53e76eecd2b6cf4f89f3146fc2198bd3 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Tue, 24 Nov 2020 17:56:57 +0000
Subject:  Fix chomping: only make it default on line-processing binaries

---
 doc/backtick.html        |  6 +++---
 doc/define.html          |  2 +-
 doc/el_transform.html    | 22 +++++++++++++++-------
 doc/forbacktickx.html    | 34 +++++++++++++++++++++++++++-------
 doc/forstdin.html        | 41 ++++++++++++++++++++++++++++-------------
 doc/importas.html        |  2 +-
 doc/multidefine.html     |  4 +++-
 doc/multisubstitute.html |  4 ++--
 doc/redirfd.html         |  8 ++------
 doc/upgrade.html         |  7 ++++++-
 doc/withstdinas.html     |  5 +++--
 11 files changed, 91 insertions(+), 44 deletions(-)

(limited to 'doc')

diff --git a/doc/backtick.html b/doc/backtick.html
index b1e2870..1f77432 100644
--- a/doc/backtick.html
+++ b/doc/backtick.html
@@ -30,7 +30,7 @@ environment variable, then executes another program.
 </p>
 
 <pre>
-     backtick [ -i | -I | -D <em>default</em> ] [ -n ] <em>variable</em> { <em>prog1...</em> } <em>prog2...</em>
+     backtick [ -i | -I | -D <em>default</em> ] [ -N | -n ] <em>variable</em> { <em>prog1...</em> } <em>prog2...</em>
 </pre>
 
 <ul>
@@ -46,8 +46,8 @@ output as a value. </li>
 <h2> Options </h2>
 
 <ul>
- <li> <tt>-n</tt>&nbsp;: chomp an ending newline off <em>prog1...</em>'s
-output. </li>
+ <li> <tt>-N</tt>&nbsp;: store <em>prog1...</em>'s output as is, including the last newline, if any. </li>
+ <li> <tt>-n</tt>&nbsp;: chomp an ending newline off <em>prog1...</em>'s output. This is the default. </li>
 </ul>
 
 <p>
diff --git a/doc/define.html b/doc/define.html
index 4c09c4c..16bce61 100644
--- a/doc/define.html
+++ b/doc/define.html
@@ -26,7 +26,7 @@ another program.
 <h2> Interface </h2>
 
 <pre>
-     define [ -s ] [ -C | -c ] [ -n ] [ -d <em>delim</em> ] <em>variable</em> <em>value</em> <em>prog...</em>
+     define [ -s ] [ -C | -c ] [ -N | -n ] [ -d <em>delim</em> ] <em>variable</em> <em>value</em> <em>prog...</em>
 </pre>
 
 <ul>
diff --git a/doc/el_transform.html b/doc/el_transform.html
index cb163a8..e15ec69 100644
--- a/doc/el_transform.html
+++ b/doc/el_transform.html
@@ -41,6 +41,10 @@ is used, which means that the default delimiters are spaces, newlines,
 carriage returns and tabs.
 </p>
 
+<p>
+ (The <a href="forstdin.html">forstdin</a> command is a small exception:
+by default, it only recognizes newlines as delimiters.)
+</p>
 
 <a name="crunch">
 <h2> Crunching </h2>
@@ -53,6 +57,8 @@ three consecutive spaces, or a space and 4 tab characters, with a
 single space. This is called <em>crunching</em>, and it is done
 by giving the <tt>-C</tt> switch to the substitution command. The
 remaining delimiter will always be the first in the sequence.
+Chomping is <em>off</em> by default, or if you give the <tt>-c</tt>
+switch.
 </p>
 
 <p>
@@ -66,8 +72,10 @@ remaining delimiter will always be the first in the sequence.
 <p>
  Sometimes you don't want the last delimiter in a value.
  <em>Chomping</em> deletes the last character of a value if it is a
-delimiter. It can be requested by giving the <tt>-n</tt> switch to the
-substitution command. Note that chomping always happens <em>after</em>
+delimiter. It is requested by giving the <tt>-n</tt> switch to the
+substitution command. You can turn it off by giving the <tt>-N</tt>
+switch. It is off by default unless mentioned in the documentation
+page of specific binaries. Note that chomping always happens <em>after</em>
 crunching, which means you can use crunching+chomping to ignore, for
 instance, a set of trailing spaces.
 </p>
@@ -112,11 +120,11 @@ several advantages over the shell's:
 </p>
 
 <ul>
- <li> Splitting has to be explicitly requested, by specifying the
-<tt>-s</tt> option to commands that perform
-<a href="el_substitute.html">substitution</a>. By default,
-substitutions are performed as is, without interpreting the
-characters in the value. </li>
+ <li> Splitting is off by default, which means that substitutions
+are performed as is, without interpreting the characters in the
+value. In execline, splitting has to be explicitly requested
+by specifying the <tt>-s</tt> option to commands that perform
+<a href="el_substitute.html">substitution</a>. </li>
  <li> Positional parameters are never split, so that execline
 scripts can handle arguments the way the user intended to. To
 split <tt>$1</tt>, for instance, you have to ask for it
diff --git a/doc/forbacktickx.html b/doc/forbacktickx.html
index 9cbcd98..d28ad0b 100644
--- a/doc/forbacktickx.html
+++ b/doc/forbacktickx.html
@@ -30,7 +30,7 @@ run another program.
 </p>
 
 <pre>
-     forbacktickx [ -p | -o <em>okcodes</em> | -x <em>breakcodes</em> ] [ -n ] [ -C | -c ] [ -0 | -d <em>delim</em> ] <em>variable</em> { <em>gen...</em> } <em>loop...</em>
+     forbacktickx [ -p | -o <em>okcodes</em> | -x <em>breakcodes</em> ] [ -N | -n ] [ -C | -c ] [ -0 | -d <em>delim</em> ] <em>variable</em> { <em>gen...</em> } <em>loop...</em>
 </pre>
 
 <ul>
@@ -54,9 +54,6 @@ output must not contain a null character. </li>
 instance to finish before spawning the next one. <em>forbacktickx</em> will
 still wait for all instances of <em>loop</em> to terminate before
 exiting, though. </li>
- <li> <tt>-0</tt>&nbsp;: accept null characters from <em>gen</em>'s output,
-using them as delimiters. If this option and a <tt>-d</tt> option are
-used simultaneously, the rightmost one wins. </li>
  <li> <tt>-o</tt>&nbsp;<em>okcodes</em>&nbsp;: <em>okcodes</em> must
 be a comma-separated list of exit codes. If the <tt>-p</tt> flag
 hasn't been given and <em>loop</em> exits with one of the codes in
@@ -68,9 +65,32 @@ not listed in <em>okcodes</em>, forbacktickx will exit immediately with an
 option, but with inverted meaning - the listed exit codes are codes
 that will make forbacktickx break the loop and exit, and the unlisted exit
 codes will make it keep looping. </li>
- <li> Other options are used to <a href="el_transform.html">control
-the substitution mechanism</a> for every <em>x</em>. Of course, you can't
-split <em>x</em>. </li>
+</ul>
+
+<p>
+ Other options are similar (in name and functionality) to the switches
+passed to <a href="el_transform.html">control a substitution mechanism</a>,
+on purpose; however, <tt>forbacktickx</tt> does not call the substitution
+mechanism and has its own semantics for those options.
+</p>
+
+<ul>
+ <li> <tt>-N</tt>&nbsp;: store the whole line in <em>variable</em>,
+including the terminating newline (or other delimiter). </li>
+ <li> <tt>-n</tt>&nbsp;: chomp a terminating delimiter from the line from
+stdin before storing it into <em>variable</em>. This is the default. </li>
+ <li> <tt>-C</tt>&nbsp;: crunch. If there is an empty line (i.e. that
+only contains a delimiter), do not call <em>loop</em>. If this option is
+given, <em>and</em> chomping is active, <em>and</em> the last line of stdin
+is not terminated by a delimiter, then this last line will not be processed. </li>
+ <li> <tt>-c</tt>&nbsp;: do not crunch, call <em>loop</em> even if
+the line is empty. This is the default. </li>
+ <li> <tt>-0</tt>&nbsp;: accept null characters on its stdin,
+using them as delimiters. If this option and a <tt>-d</tt> option are
+used simultaneously, the rightmost one wins. </li>
+ <li> <tt>-d&nbsp;<em>delim</em></tt>&nbsp;: use the characters in string
+<em>delim</em> as delimiters for a line. Default is "<tt>\n</tt>", meaning
+the input is only split on newlines. </li>
 </ul>
 
 <h2> Notes </h2>
diff --git a/doc/forstdin.html b/doc/forstdin.html
index 44939fe..74644b4 100644
--- a/doc/forstdin.html
+++ b/doc/forstdin.html
@@ -30,7 +30,7 @@ run another program.
 </p>
 
 <pre>
-     forstdin [ -p | -o <em>okcodes</em> | -x <em>breakcodes</em> ] [ -E firsteofcode ] [ -e eofcode ] [ -n ] [ -C | -c ] [ -0 | -d <em>delim</em> ] <em>variable</em> <em>loop...</em>
+     forstdin [ -p | -o <em>okcodes</em> | -x <em>breakcodes</em> ] [ -N | -n ] [ -C | -c ] [ -0 | -d <em>delim</em> ] <em>variable</em> <em>loop...</em>
 </pre>
 
 <ul>
@@ -50,9 +50,6 @@ and 1 if it hasn't read anything. </li>
 instance to finish before spawning the next one. forstdin will
 still wait for all instances of <em>loop</em> to terminate before
 exiting, though. </li>
- <li> <tt>-0</tt>&nbsp;: accept null characters on its stdin,
-using them as delimiters. If this option and a <tt>-d</tt> option are
-used simultaneously, the rightmost one wins. </li>
  <li> <tt>-o</tt>&nbsp;<em>okcodes</em>&nbsp;: <em>okcodes</em> must
 be a comma-separated list of exit codes. If the <tt>-p</tt> flag
 hasn't been given and <em>loop</em> exits with one of the codes in
@@ -64,15 +61,33 @@ not listed in <em>okcodes</em>, forstdin will exit immediately with an
 option, but with inverted meaning - the listed exit codes are codes
 that will make forstdin break the loop and exit, and the unlisted exit
 codes will make it keep looping. </li>
- <li> <tt>-E</tt>&nbsp;<em>firsteofcode</em>&nbsp;: if forstdin encounters
-EOF on its first attempt to read data, exit <em>firsteofcode</em>. Default is 1. </li>
- <li> <tt>-e</tt>&nbsp;<em>eofcode</em>&nbsp;: if forstdin has already
-read data, and encounters EOF, exit <em>eofcode</em>. Default is 0. </li>
- <li> Other options are used to <a href="el_transform.html">control
-the substitution mechanism</a> for every <em>x</em>. Of course, you can't
-split <em>x</em>. The default delimiter for <tt>forstdin</tt> is a
-newline; you need a <tt>-d</tt> option to split <em>x</em> around
-other values. </li>
+</ul>
+
+<p>
+ Other options are similar (in name and functionality) to the switches
+passed to <a href="el_transform.html">control a substitution mechanism</a>,
+on purpose; however, <tt>forstdin</tt> does not call the substitution
+mechanism and has its own semantics for those options.
+</p>
+
+<ul>
+ <li> <tt>-N</tt>&nbsp;: store the whole line in <em>variable</em>,
+including the terminating newline (or other delimiter). </li>
+ <li> <tt>-n</tt>&nbsp;: chomp a terminating delimiter from the line from
+stdin before storing it into <em>variable</em>. This is the default. </li>
+ <li> <tt>-C</tt>&nbsp;: crunch. If there is an empty line (i.e. that
+only contains a delimiter), do not call <em>loop</em>. If this option is
+given, <em>and</em> chomping is active, <em>and</em> the last line of stdin
+is not terminated by a delimiter, then this last line will not be processed. </li>
+ <li> <tt>-c</tt>&nbsp;: do not crunch, call <em>loop</em> even if
+the line is empty. This is the default. </li>
+ <li> <tt>-0</tt>&nbsp;: accept null characters on its stdin,
+using them as delimiters. If this option and a <tt>-d</tt> option are
+used simultaneously, the rightmost one wins. </li>
+ <li> <tt>-d&nbsp;<em>delim</em></tt>&nbsp;: use the characters in string
+<em>delim</em> as delimiters for a line. Default is "<tt>\n</tt>", meaning
+the input is only split on newlines. </li>
+ <li>
 </ul>
 
 <h2> Notes </h2>
diff --git a/doc/importas.html b/doc/importas.html
index 4ac4a98..ac95e87 100644
--- a/doc/importas.html
+++ b/doc/importas.html
@@ -26,7 +26,7 @@ environment variable, then executes another program.
 <h2> Interface </h2>
 
 <pre>
-     importas [ -i | -D default ] [ -u ] [ -s ] [ -C | -c ] [ -n ] [ -d <em>delim</em> ] <em>variable</em> <em>envvar</em> <em>prog...</em>
+     importas [ -i | -D default ] [ -u ] [ -s ] [ -C | -c ] [ -N | -n ] [ -d <em>delim</em> ] <em>variable</em> <em>envvar</em> <em>prog...</em>
 </pre>
 
 <ul>
diff --git a/doc/multidefine.html b/doc/multidefine.html
index f3909a2..69ad388 100644
--- a/doc/multidefine.html
+++ b/doc/multidefine.html
@@ -30,7 +30,7 @@ then executes another program.
 </p>
 
 <pre>
-     multidefine [ -0 ] [ -r ] [ -C | -c ] [ -n ] [ -d <em>delim</em> ] <em>value</em> { <em>variables...</em> } <em>prog...</em>
+     multidefine [ -0 ] [ -r ] [ -C | -c ] [ -N | -n ] [ -d <em>delim</em> ] <em>value</em> { <em>variables...</em> } <em>prog...</em>
 </pre>
 
 <ul>
@@ -64,6 +64,8 @@ If there are more words in the split <em>value</em> than there are
 <em>variables</em> in the block, the last variable will be replaced with all
 the remaining words (and will be split). Without this option, the last variable
 is replaced with a single word, and the excess words are lost. </li>
+ <li> Other options are used to <a href="el_transform.html">control</a> the
+substitution mechanism. Note that the value is always split. </li>
 </ul>
 
 </body>
diff --git a/doc/multisubstitute.html b/doc/multisubstitute.html
index aebdde8..2cb38ee 100644
--- a/doc/multisubstitute.html
+++ b/doc/multisubstitute.html
@@ -32,8 +32,8 @@ its <em>argv</em>, then executes another program.
 <pre>
      multisubstitute
      {
-       [ <a href="define.html">define</a> [ -n ] [ -s ] [ -C | -c ] [ -d <em>delim</em> ] <em>variable</em> <em>value</em> ]
-       [ <a href="importas.html">importas</a> [ -i | -D <em>default</em> ] [ -n ] [ -s ] [ -C | -c ] [ -d <em>delim</em> ] <em>variable</em> <em>envvar</em> ]
+       [ <a href="define.html">define</a> [ -N | -n ] [ -s ] [ -C | -c ] [ -d <em>delim</em> ] <em>variable</em> <em>value</em> ]
+       [ <a href="importas.html">importas</a> [ -i | -D <em>default</em> ] [ -N | -n ] [ -s ] [ -C | -c ] [ -d <em>delim</em> ] <em>variable</em> <em>envvar</em> ]
        [ <a href="elglob.html">elglob</a> [ -v ] [ -w ] [ -s ] [ -m ] [ -e ] [ -0 ] <em>variable</em> <em>pattern</em> ]
        [ <a href="elgetpositionals.html">elgetpositionals</a> [ -P <em>sharp</em> ] ]
        [ <a href="multidefine.html">multidefine</a> <em>value</em> { <em>variable...</em> } ]
diff --git a/doc/redirfd.html b/doc/redirfd.html
index bb5a5fb..9dbe409 100644
--- a/doc/redirfd.html
+++ b/doc/redirfd.html
@@ -26,7 +26,7 @@ executes a program.
 <h2> Interface </h2>
 
 <pre>
-     redirfd [ -r | -w | -u | -a | -c | -x ] [ -n ] [ -b ] <em>fd</em> <em>file</em> <em>prog...</em>
+     redirfd [ -r | -w | -u | -a | -x ] [ -n ] [ -b ] <em>fd</em> <em>file</em> <em>prog...</em>
 </pre>
 
 <p>
@@ -37,7 +37,7 @@ to <em>file</em>, then execs into <em>prog...</em>.
 <h2> Options </h2>
 
 <p>
- One and only one of the -r, -w, -u, -a, -c, or -x options must be given;
+ One and only one of the -r, -w, -u, -a, or -x options must be given;
 the -n and -b options may be added in any case.
 </p>
 
@@ -46,7 +46,6 @@ the -n and -b options may be added in any case.
  <li> <tt>-w</tt>&nbsp;: open <em>file</em> for writing, truncating it if it already exists. </li>
  <li> <tt>-u</tt>&nbsp;: open <em>file</em> for reading and writing. </li>
  <li> <tt>-a</tt>&nbsp;: open <em>file</em> for appending, creating it if it doesn't exist. </li>
- <li> <tt>-c</tt>&nbsp;: open <em>file</em> for appending. Do not create it if it doesn't exist. </li>
  <li> <tt>-x</tt>&nbsp;: open <em>file</em> for writing, creating it, failing if it already exists. </li>
  <li> <tt>-n</tt>&nbsp;: open <em>file</em> in non-blocking mode. </li>
  <li> <tt>-b</tt>&nbsp;: change mode of <em>file</em> after opening it:
@@ -65,9 +64,6 @@ to blocking mode if it was. </li>
 <tt>sh -c 'exec prog... <em>n</em>&lt;&gt;<em>file</em>'</tt></li>
  <li> <tt>redirfd -a <em>n</em> <em>file</em> prog...</tt> is roughly equivalent to
 <tt>sh -c 'exec prog... <em>n</em>&gt;&gt;<em>file</em>'</tt></li>
- <li> <tt>redirfd -c <em>n</em> <em>file</em> prog...</tt> has no portable
-shell equivalent. Some shells provide the <em>noclobber</em> option for
-a similar feature. </li>
  <li> <tt>redirfd -x <em>n</em> <em>file</em> prog...</tt> has no portable
 shell equivalent. </li>
 </ul>
diff --git a/doc/upgrade.html b/doc/upgrade.html
index d12b051..2d6172c 100644
--- a/doc/upgrade.html
+++ b/doc/upgrade.html
@@ -24,7 +24,12 @@
  <li> <a href="//skarnet.org/software/skalibs/">skalibs</a>
 dependency bumped to 2.9.4.0. </li>
  <li> <a href="forstdin.html">forstdin</a> now exits 1 on immediate EOF,
-and only splits on newlines by default.  </li>
+and only splits on newlines by default. </li>
+ <li> <a href="forbacktickx.html">forbacktickx</a>, which is a wrapper
+around <a href="forstdin.html">forstdin</a>, gets the same changes. </li>
+ <li> Input-processing binaries (<em>not</em> substitution binaries!)
+now chomp by default. </li>
+ <li> New <tt>-N</tt> option to deactivate chomping. </li>
  <li> New <tt>default</tt> directive to <a href="trap.html">trap</a>,
 replacing the <tt>timeout</tt> one, which was ill-suited to that program. </li>
 </ul>
diff --git a/doc/withstdinas.html b/doc/withstdinas.html
index f0db24a..ccd69d7 100644
--- a/doc/withstdinas.html
+++ b/doc/withstdinas.html
@@ -31,7 +31,7 @@ environment variable.
 </p>
 
 <pre>
-     withstdinas [ -i | -I | -D <em>default</em> ] [ -n ] <em>variable</em> <em>prog...</em>
+     withstdinas [ -i | -I | -D <em>default</em> ] [ -N | -n ] <em>variable</em> <em>prog...</em>
 </pre>
 
 <ul>
@@ -44,7 +44,8 @@ environment variable.
 <h2> Options </h2>
 
 <ul>
- <li> <tt>-n</tt>&nbsp;: chomp an ending newline off stdin. </li>
+ <li> <tt>-N</tt>&nbsp;: do not chomp an ending newline off stdin. </li>
+ <li> <tt>-n</tt>&nbsp;: chomp an ending newline off stdin. This is the default. </li>
 </ul>
 
 <p>
-- 
cgit v1.2.3