>From 079f3409b60782d5a4b1da678fa5831ea9c8a01f Mon Sep 17 00:00:00 2001
From: Assaf Gordon <address@hidden>
Date: Wed, 25 Jan 2017 03:41:59 +0000
Subject: [PATCH] doc: new 'multiple commands syntax' section

Explain which commands can be separated by semicolon and which require
newlines. Requested by Ori Avtalion in https://bugs.gnu.org/21845 .

* doc/sed.texi (Multiple commands syntax): New section in "sed scripts"
chapter.
---
 doc/sed.texi | 235 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 232 insertions(+), 3 deletions(-)

diff --git a/doc/sed.texi b/doc/sed.texi
index c45b150..36953a3 100644
--- a/doc/sed.texi
+++ b/doc/sed.texi
@@ -484,6 +484,7 @@ $ echo | sed 'Q42' ; echo $?
 * Other Commands::           Less frequently used commands
 * Programming Commands::     Commands for @command{sed} gurus
 * Extended Commands::        Commands specific of @value{SSED}
+* Multiple commands syntax:: Extnesion for easier scripting
 @end menu
 
 @node sed script overview
@@ -586,6 +587,7 @@ thus should be terminated
 with newlines or be placed at the end of a @var{script} or @var{script-file}.
 Commands can also be preceded with optional non-significant
 whitespace characters.
address@hidden commands syntax}.
 
 
 
@@ -903,12 +905,12 @@ while in general flags for the @code{s} command show their
 effect just once.  This behavior, although documented, might
 change in future versions.
 
address@hidden w @var{file-name}
address@hidden w @var{filename}
 @cindex Text, writing to a file after substitution
 @cindex @value{SSEDEXT}, @file{/dev/stdout} file
 @cindex @value{SSEDEXT}, @file{/dev/stderr} file
 If the substitution was made, then write out the result to the named file.
-As a @value{SSED} extension, two special values of @var{file-name} are
+As a @value{SSED} extension, two special values of @var{filename} are
 supported: @file{/dev/stderr}, which writes the result to the standard
 error, and @file{/dev/stdout}, which writes to the standard
 address@hidden is equivalent to @code{p} unless the @option{-i}
@@ -1464,7 +1466,7 @@ file will then be reread and inserted on each of the addressed lines.
 @cindex @value{SSEDEXT}, @file{/dev/stdout} file
 @cindex @value{SSEDEXT}, @file{/dev/stderr} file
 Write the pattern space to @var{filename}.
-As a @value{SSED} extension, two special values of @var{file-name} are
+As a @value{SSED} extension, two special values of @var{filename} are
 supported: @file{/dev/stderr}, which writes the result to the standard
 error, and @file{/dev/stdout}, which writes to the standard
 address@hidden is equivalent to @code{p} unless the @option{-i}
@@ -1706,7 +1708,234 @@ script in most multibyte locales (including UTF-8 locales).
 @end table
 
 
address@hidden Multiple commands syntax
address@hidden Multiple commands syntax
+
address@hidden POSIX says:
address@hidden   Editing commands other than {...}, a, b, c, i, r, t, w, :, and #
address@hidden   can be followed by a <semicolon>, optional <blank> characters, and
address@hidden   another editing command. However, when an s editing command is used
address@hidden   with the w flag, following it with another command in this manner
address@hidden   produces undefined results.
+
+There are several methods to specify multiple commands in a @command{sed}
+program.
+
+Using newlines is most natural when running sed script from a file
+(using @option{-f} option).
+
+On the command line, all @command{sed} commands can be separated by a
+newline, or with multiple @option{-e} parameters:
+
address@hidden on
address@hidden on
address@hidden
address@hidden
+$ seq 6 | sed '1d
+3d
+5d'
+2
+4
+6
 
+$ seq 6 | sed -e 1d -e 3d -e 5d
+2
+4
+6
address@hidden group
address@hidden example
address@hidden off
address@hidden off
+
+Most simple commands can be separated by a semicolon (@samp{;}):
+
address@hidden on
address@hidden on
address@hidden
address@hidden
+$ seq 6 | sed '1d;3d;5d'
+2
+4
+6
address@hidden group
address@hidden example
address@hidden off
address@hidden off
+
+The @address@hidden,@address@hidden,@code{b},@code{t},@code{T},@code{:} commands can
+be separated with a semicolon (this is a non-portable @value{SSED} extension).
+
address@hidden on
address@hidden on
address@hidden
address@hidden
+$ seq 4 | sed '@{1d;address@hidden'
+2
+4
+
+$ seq 6 | sed '@{1d;address@hidden;5d'
+2
+4
+6
address@hidden group
address@hidden example
address@hidden off
address@hidden off
+
+Labels used in @code{b},@code{t},@code{T},@code{:} commands are read
+until the semicolon. Leading and trailing whitespaces are ignored.  In
+the examples below the label is @samp{x}.  The first example works
+with @value{SSED}. The second is a portable equivalent.  For more
+information about branching and labels @pxref{Branching and flow
+control}.
+
address@hidden on
address@hidden on
address@hidden
address@hidden
+$ seq 3 | sed '/1/b x ; s/^/=/ ; :x ; 3d'
+1
+=2
+
+$ seq 3 | sed -e '/1/bx' -e 's/^/=/' -e ':x' -e '3d'
+1
+=2
address@hidden group
address@hidden example
address@hidden off
address@hidden off
+
+
+
address@hidden Commands Requiring a newline
+
+The following commands cannot be separated by a semicolon and
+require a newline:
+
address@hidden @asis
+
address@hidden @code{a},@code{c},@code{i} (append/change/insert)
+
+All characters following @code{a},@code{c},@code{i} commands are taken
+as the text to append/change/insert. Using a semicolon leads to
+undesirable results:
+
address@hidden on
address@hidden on
address@hidden
address@hidden
+$ seq 2 | sed '1aHello ; 2d'
+1
+Hello ; 2d
+2
address@hidden group
address@hidden example
address@hidden off
address@hidden off
+
+Separate the commands using @option{-e} or a newline:
+
address@hidden on
address@hidden on
address@hidden
address@hidden
+$ seq 2 | sed -e 1aHello -e 2d
+1
+Hello
+
+$ seq 2 | sed '1aHello
+2d'
+1
+Hello
address@hidden group
address@hidden example
address@hidden off
address@hidden off
+
+Note that specifing the text to add (@samp{Hello}) immediately
+after @code{a},@code{c},@code{i} is itself a @value{SSED} extension.
+A portable, POSIX-compliant alternative is:
+
address@hidden on
address@hidden on
address@hidden
address@hidden
+$ seq 2 | sed '1a\
+Hello
+2d'
+1
+Hello
address@hidden group
address@hidden example
address@hidden off
address@hidden off
+
address@hidden @code{#} (comment)
+
+All characters following @samp{#} until the next newline are ignored.
+
address@hidden on
address@hidden on
address@hidden
address@hidden
+$ seq 3 | sed '# this is a comment ; 2d'
+1
+2
+3
+
+
+$ seq 3 | sed '# this is a comment
+2d'
+1
+3
address@hidden group
address@hidden example
address@hidden off
address@hidden off
+
address@hidden @code{r},@code{R},@code{w},@code{W} (reading and writing files)
+
+The @code{r},@code{R},@code{w},@code{W} commands parse the filename
+until end of the line. If whitespace or semicolons are found, they will
+be included in the filename, leading to unexpected results:
+
address@hidden on
address@hidden on
address@hidden
address@hidden
+$ seq 2 | sed '1w hello.txt ; 2d'
+1
+2
+
+$ ls -log
+total 4
+-rw-rw-r-- 1 2 Jan 23 23:03 hello.txt ; 2d
+
+$ cat 'hello.txt ; 2d'
+1
address@hidden group
address@hidden example
address@hidden off
address@hidden off
+
+Note that @command{sed} silently ignores read/write errors in
address@hidden,@code{R},@code{w},@code{W} commands (such as missing files).
+In the following example, @command{sed} tries to read a file named
address@hidden@file{hello.txt ; N}}. The file is missing, and the error is silently ignored:
+
address@hidden on
address@hidden on
address@hidden
address@hidden
+$ echo x | sed '1rhello.txt ; N'
+x
address@hidden group
address@hidden example
address@hidden off
address@hidden off
+
+
address@hidden table
 
 
 @node sed addresses
-- 
1.9.0