diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/backtick.html | 6 | ||||
| -rw-r--r-- | doc/define.html | 2 | ||||
| -rw-r--r-- | doc/el_transform.html | 22 | ||||
| -rw-r--r-- | doc/forbacktickx.html | 34 | ||||
| -rw-r--r-- | doc/forstdin.html | 41 | ||||
| -rw-r--r-- | doc/importas.html | 2 | ||||
| -rw-r--r-- | doc/multidefine.html | 4 | ||||
| -rw-r--r-- | doc/multisubstitute.html | 4 | ||||
| -rw-r--r-- | doc/redirfd.html | 8 | ||||
| -rw-r--r-- | doc/upgrade.html | 7 | ||||
| -rw-r--r-- | doc/withstdinas.html | 5 |
11 files changed, 91 insertions, 44 deletions
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> : chomp an ending newline off <em>prog1...</em>'s -output. </li> + <li> <tt>-N</tt> : store <em>prog1...</em>'s output as is, including the last newline, if any. </li> + <li> <tt>-n</tt> : 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> : 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> <em>okcodes</em> : <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> : store the whole line in <em>variable</em>, +including the terminating newline (or other delimiter). </li> + <li> <tt>-n</tt> : 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> : 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> : do not crunch, call <em>loop</em> even if +the line is empty. This is the default. </li> + <li> <tt>-0</tt> : 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 <em>delim</em></tt> : 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> : 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> <em>okcodes</em> : <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> <em>firsteofcode</em> : if forstdin encounters -EOF on its first attempt to read data, exit <em>firsteofcode</em>. Default is 1. </li> - <li> <tt>-e</tt> <em>eofcode</em> : 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> : store the whole line in <em>variable</em>, +including the terminating newline (or other delimiter). </li> + <li> <tt>-n</tt> : 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> : 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> : do not crunch, call <em>loop</em> even if +the line is empty. This is the default. </li> + <li> <tt>-0</tt> : 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 <em>delim</em></tt> : 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> : open <em>file</em> for writing, truncating it if it already exists. </li> <li> <tt>-u</tt> : open <em>file</em> for reading and writing. </li> <li> <tt>-a</tt> : open <em>file</em> for appending, creating it if it doesn't exist. </li> - <li> <tt>-c</tt> : open <em>file</em> for appending. Do not create it if it doesn't exist. </li> <li> <tt>-x</tt> : open <em>file</em> for writing, creating it, failing if it already exists. </li> <li> <tt>-n</tt> : open <em>file</em> in non-blocking mode. </li> <li> <tt>-b</tt> : 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><><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>>><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> : chomp an ending newline off stdin. </li> + <li> <tt>-N</tt> : do not chomp an ending newline off stdin. </li> + <li> <tt>-n</tt> : chomp an ending newline off stdin. This is the default. </li> </ul> <p> |