enable support for using `&' in the pattern substitution replacement string

2026-07-12 06:30:50 +02:00 · 2021-10-04 15:30:21 -04:00
parent 70d7c6430d
commit f188aa6a01
22 changed files with 518 additions and 209 deletions
@@ -1,10 +1,10 @@
-This is bashref.info, produced by makeinfo version 6.7 from
+This is bashref.info, produced by makeinfo version 6.8 from
 bashref.texi.

 This text is a brief description of the features that are present in the
-Bash shell (version 5.1, 23 August 2021).
+Bash shell (version 5.1, 1 October 2021).

-   This is Edition 5.1, last updated 23 August 2021, of 'The GNU Bash
+   This is Edition 5.1, last updated 1 October 2021, of 'The GNU Bash
 Reference Manual', for 'Bash', Version 5.1.

   Copyright (C) 1988-2021 Free Software Foundation, Inc.
@@ -27,10 +27,10 @@ Bash Features
 *************

 This text is a brief description of the features that are present in the
-Bash shell (version 5.1, 23 August 2021).  The Bash home page is
+Bash shell (version 5.1, 1 October 2021).  The Bash home page is
 <http://www.gnu.org/software/bash/>.

-   This is Edition 5.1, last updated 23 August 2021, of 'The GNU Bash
+   This is Edition 5.1, last updated 1 October 2021, of 'The GNU Bash
 Reference Manual', for 'Bash', Version 5.1.

   Bash contains features that appear in other popular shells, and some
@@ -1831,22 +1831,39 @@ omitted, the operator tests only for existence.
     If PARAMETER is unset or null, the expansion of WORD is
     substituted.  Otherwise, the value of PARAMETER is substituted.

+          $ v=123
+          $ echo ${v-unset}
+          123
+
 '${PARAMETER:=WORD}'
     If PARAMETER is unset or null, the expansion of WORD is assigned to
     PARAMETER.  The value of PARAMETER is then substituted.  Positional
     parameters and special parameters may not be assigned to in this
     way.

+          $ var=
+          $ : ${var:=DEFAULT}
+          $ echo $var
+          DEFAULT
+
 '${PARAMETER:?WORD}'
     If PARAMETER is null or unset, the expansion of WORD (or a message
     to that effect if WORD is not present) is written to the standard
     error and the shell, if it is not interactive, exits.  Otherwise,
     the value of PARAMETER is substituted.

+          $ var=
+          $ : ${var:?var is unset or null}
+          bash: var: var is unset or null
+
 '${PARAMETER:+WORD}'
     If PARAMETER is null or unset, nothing is substituted, otherwise
     the expansion of WORD is substituted.

+          $ var=123
+          $ echo ${var:+var is set and not null}
+          var is set and not null
+
 '${PARAMETER:OFFSET}'
 '${PARAMETER:OFFSET:LENGTH}'
     This is referred to as Substring Expansion.  It expands to up to
@@ -2037,26 +2054,66 @@ omitted, the operator tests only for existence.
     array in turn, and the expansion is the resultant list.

 '${PARAMETER/PATTERN/STRING}'
-
+'${PARAMETER//PATTERN/STRING}'
+'${PARAMETER/#PATTERN/STRING}'
+'${PARAMETER/%PATTERN/STRING}'
     The PATTERN is expanded to produce a pattern just as in filename
     expansion.  PARAMETER is expanded and the longest match of PATTERN
-     against its value is replaced with STRING.  The match is performed
-     according to the rules described below (*note Pattern Matching::).
-     If PATTERN begins with '/', all matches of PATTERN are replaced
-     with STRING.  Normally only the first match is replaced.  If
-     PATTERN begins with '#', it must match at the beginning of the
-     expanded value of PARAMETER.  If PATTERN begins with '%', it must
-     match at the end of the expanded value of PARAMETER.  If STRING is
-     null, matches of PATTERN are deleted and the '/' following PATTERN
-     may be omitted.  If the 'nocasematch' shell option (see the
-     description of 'shopt' in *note The Shopt Builtin::) is enabled,
-     the match is performed without regard to the case of alphabetic
-     characters.  If PARAMETER is '@' or '*', the substitution operation
-     is applied to each positional parameter in turn, and the expansion
-     is the resultant list.  If PARAMETER is an array variable
-     subscripted with '@' or '*', the substitution operation is applied
-     to each member of the array in turn, and the expansion is the
-     resultant list.
+     against its value is replaced with STRING.  STRING undergoes tilde
+     expansion, parameter and variable expansion, arithmetic expansion,
+     command and process substitution, and quote removal.  The match is
+     performed according to the rules described below (*note Pattern
+     Matching::).
+
+     In the first form above, only the first match is replaced.  If
+     there are two slashes separating PARAMETER and PATTERN (the second
+     form above), all matches of PATTERN are replaced with STRING.  If
+     PATTERN is preceded by '#' (the third form above), it must match at
+     the beginning of the expanded value of PARAMETER.  If PATTERN is
+     preceded by '%' (the fourth form above), it must match at the end
+     of the expanded value of PARAMETER.  If the expansion of STRING is
+     null, matches of PATTERN are deleted.  If STRING is null, matches
+     of PATTERN are deleted and the '/' following PATTERN may be
+     omitted.
+
+     Any unquoted instances of '&' in STRING are replaced with the
+     matching portion of PATTERN.  This is intended to duplicate a
+     common 'sed' idiom.  Backslash is used to quote '&' in STRING;
+     users should take care if STRING is double-quoted to avoid unwanted
+     interactions between the backslash and double-quoting.  For
+     instance,
+
+          var=abcdef
+          echo ${var/abc/& }
+          echo "${var/abc/& }"
+          echo ${var/abc/"& "}
+
+     will display three lines of "abc def", while
+
+          var=abcdef
+          echo ${var/abc/\& }
+          echo "${var/abc/\& }"
+          echo ${var/abc/"\& "}
+
+     will display two lines of "& def" and a third line of "\& def".
+     This is because '&' is not one of the characters for which
+     backslash is special in double quotes, and the expansion of STRING
+     is performed in a context that doesn't take the enclosing double
+     quotes into account.  It should rarely be necessary to enclose only
+     STRING in double quotes.
+
+     Pattern substitution performs the check for '&' before expanding
+     STRING to catch backslashes escaping the '&' before they are
+     removed by the expansion.
+
+     If the 'nocasematch' shell option (see the description of 'shopt'
+     in *note The Shopt Builtin::) is enabled, the match is performed
+     without regard to the case of alphabetic characters.  If PARAMETER
+     is '@' or '*', the substitution operation is applied to each
+     positional parameter in turn, and the expansion is the resultant
+     list.  If PARAMETER is an array variable subscripted with '@' or
+     '*', the substitution operation is applied to each member of the
+     array in turn, and the expansion is the resultant list.

 '${PARAMETER^PATTERN}'
 '${PARAMETER^^PATTERN}'
@@ -2067,18 +2124,22 @@ omitted, the operator tests only for existence.
     filename expansion.  Each character in the expanded value of
     PARAMETER is tested against PATTERN, and, if it matches the
     pattern, its case is converted.  The pattern should not attempt to
-     match more than one character.  The '^' operator converts lowercase
-     letters matching PATTERN to uppercase; the ',' operator converts
-     matching uppercase letters to lowercase.  The '^^' and ',,'
-     expansions convert each matched character in the expanded value;
-     the '^' and ',' expansions match and convert only the first
-     character in the expanded value.  If PATTERN is omitted, it is
-     treated like a '?', which matches every character.  If PARAMETER is
-     '@' or '*', the case modification operation is applied to each
-     positional parameter in turn, and the expansion is the resultant
-     list.  If PARAMETER is an array variable subscripted with '@' or
-     '*', the case modification operation is applied to each member of
-     the array in turn, and the expansion is the resultant list.
+     match more than one character.
+
+     The '^' operator converts lowercase letters matching PATTERN to
+     uppercase; the ',' operator converts matching uppercase letters to
+     lowercase.  The '^^' and ',,' expansions convert each matched
+     character in the expanded value; the '^' and ',' expansions match
+     and convert only the first character in the expanded value.  If
+     PATTERN is omitted, it is treated like a '?', which matches every
+     character.
+
+     If PARAMETER is '@' or '*', the case modification operation is
+     applied to each positional parameter in turn, and the expansion is
+     the resultant list.  If PARAMETER is an array variable subscripted
+     with '@' or '*', the case modification operation is applied to each
+     member of the array in turn, and the expansion is the resultant
+     list.

 '${PARAMETER@OPERATOR}'
     The expansion is either a transformation of the value of PARAMETER
@@ -2697,11 +2758,13 @@ following order.
     expansion, and quote removal before being assigned to the variable.

   If no command name results, the variable assignments affect the
-current shell environment.  Otherwise, the variables are added to the
-environment of the executed command and do not affect the current shell
-environment.  If any of the assignments attempts to assign a value to a
-readonly variable, an error occurs, and the command exits with a
-non-zero status.
+current shell environment.  In the case of such a command (one that
+consists only of assignment statements and redirections), assignment
+statements are performed before redirections.  Otherwise, the variables
+are added to the environment of the executed command and do not affect
+the current shell environment.  If any of the assignments attempts to
+assign a value to a readonly variable, an error occurs, and the command
+exits with a non-zero status.

   If no command name results, redirections are performed, but do not
 affect the current shell environment.  A redirection error causes the
@@ -12264,103 +12327,103 @@ Node: Shell Expansions69743
 Node: Brace Expansion71870
 Node: Tilde Expansion74604
 Node: Shell Parameter Expansion77225
-Node: Command Substitution92528
-Node: Arithmetic Expansion93883
-Node: Process Substitution94851
-Node: Word Splitting95971
-Node: Filename Expansion97915
-Node: Pattern Matching100515
-Node: Quote Removal105123
-Node: Redirections105418
-Node: Executing Commands115078
-Node: Simple Command Expansion115748
-Node: Command Search and Execution117702
-Node: Command Execution Environment120080
-Node: Environment123115
-Node: Exit Status124778
-Node: Signals126562
-Node: Shell Scripts128529
-Node: Shell Builtin Commands131556
-Node: Bourne Shell Builtins133594
-Node: Bash Builtins155055
-Node: Modifying Shell Behavior185872
-Node: The Set Builtin186217
-Node: The Shopt Builtin196630
-Node: Special Builtins212059
-Node: Shell Variables213038
-Node: Bourne Shell Variables213475
-Node: Bash Variables215579
-Node: Bash Features248394
-Node: Invoking Bash249407
-Node: Bash Startup Files255420
-Node: Interactive Shells260523
-Node: What is an Interactive Shell?260933
-Node: Is this Shell Interactive?261582
-Node: Interactive Shell Behavior262397
-Node: Bash Conditional Expressions265910
-Node: Shell Arithmetic270552
-Node: Aliases273496
-Node: Arrays276109
-Node: The Directory Stack282118
-Node: Directory Stack Builtins282902
-Node: Controlling the Prompt287162
-Node: The Restricted Shell290127
-Node: Bash POSIX Mode292724
-Node: Shell Compatibility Mode303997
-Node: Job Control310653
-Node: Job Control Basics311113
-Node: Job Control Builtins316115
-Node: Job Control Variables321515
-Node: Command Line Editing322671
-Node: Introduction and Notation324342
-Node: Readline Interaction325965
-Node: Readline Bare Essentials327156
-Node: Readline Movement Commands328939
-Node: Readline Killing Commands329899
-Node: Readline Arguments331817
-Node: Searching332861
-Node: Readline Init File335047
-Node: Readline Init File Syntax336308
-Node: Conditional Init Constructs357588
-Node: Sample Init File361784
-Node: Bindable Readline Commands364908
-Node: Commands For Moving366112
-Node: Commands For History368163
-Node: Commands For Text373157
-Node: Commands For Killing376806
-Node: Numeric Arguments379839
-Node: Commands For Completion380978
-Node: Keyboard Macros385169
-Node: Miscellaneous Commands385856
-Node: Readline vi Mode391795
-Node: Programmable Completion392702
-Node: Programmable Completion Builtins400482
-Node: A Programmable Completion Example411177
-Node: Using History Interactively416424
-Node: Bash History Facilities417108
-Node: Bash History Builtins420113
-Node: History Interaction425121
-Node: Event Designators428741
-Node: Word Designators430095
-Node: Modifiers431855
-Node: Installing Bash433666
-Node: Basic Installation434803
-Node: Compilers and Options438061
-Node: Compiling For Multiple Architectures438802
-Node: Installation Names440495
-Node: Specifying the System Type441313
-Node: Sharing Defaults442029
-Node: Operation Controls442702
-Node: Optional Features443660
-Node: Reporting Bugs454460
-Node: Major Differences From The Bourne Shell455735
-Node: GNU Free Documentation License472585
-Node: Indexes497762
-Node: Builtin Index498216
-Node: Reserved Word Index505043
-Node: Variable Index507491
-Node: Function Index523983
-Node: Concept Index537767
+Node: Command Substitution94537
+Node: Arithmetic Expansion95892
+Node: Process Substitution96860
+Node: Word Splitting97980
+Node: Filename Expansion99924
+Node: Pattern Matching102524
+Node: Quote Removal107132
+Node: Redirections107427
+Node: Executing Commands117087
+Node: Simple Command Expansion117757
+Node: Command Search and Execution119867
+Node: Command Execution Environment122245
+Node: Environment125280
+Node: Exit Status126943
+Node: Signals128727
+Node: Shell Scripts130694
+Node: Shell Builtin Commands133721
+Node: Bourne Shell Builtins135759
+Node: Bash Builtins157220
+Node: Modifying Shell Behavior188037
+Node: The Set Builtin188382
+Node: The Shopt Builtin198795
+Node: Special Builtins214224
+Node: Shell Variables215203
+Node: Bourne Shell Variables215640
+Node: Bash Variables217744
+Node: Bash Features250559
+Node: Invoking Bash251572
+Node: Bash Startup Files257585
+Node: Interactive Shells262688
+Node: What is an Interactive Shell?263098
+Node: Is this Shell Interactive?263747
+Node: Interactive Shell Behavior264562
+Node: Bash Conditional Expressions268075
+Node: Shell Arithmetic272717
+Node: Aliases275661
+Node: Arrays278274
+Node: The Directory Stack284283
+Node: Directory Stack Builtins285067
+Node: Controlling the Prompt289327
+Node: The Restricted Shell292292
+Node: Bash POSIX Mode294889
+Node: Shell Compatibility Mode306162
+Node: Job Control312818
+Node: Job Control Basics313278
+Node: Job Control Builtins318280
+Node: Job Control Variables323680
+Node: Command Line Editing324836
+Node: Introduction and Notation326507
+Node: Readline Interaction328130
+Node: Readline Bare Essentials329321
+Node: Readline Movement Commands331104
+Node: Readline Killing Commands332064
+Node: Readline Arguments333982
+Node: Searching335026
+Node: Readline Init File337212
+Node: Readline Init File Syntax338473
+Node: Conditional Init Constructs359753
+Node: Sample Init File363949
+Node: Bindable Readline Commands367073
+Node: Commands For Moving368277
+Node: Commands For History370328
+Node: Commands For Text375322
+Node: Commands For Killing378971
+Node: Numeric Arguments382004
+Node: Commands For Completion383143
+Node: Keyboard Macros387334
+Node: Miscellaneous Commands388021
+Node: Readline vi Mode393960
+Node: Programmable Completion394867
+Node: Programmable Completion Builtins402647
+Node: A Programmable Completion Example413342
+Node: Using History Interactively418589
+Node: Bash History Facilities419273
+Node: Bash History Builtins422278
+Node: History Interaction427286
+Node: Event Designators430906
+Node: Word Designators432260
+Node: Modifiers434020
+Node: Installing Bash435831
+Node: Basic Installation436968
+Node: Compilers and Options440226
+Node: Compiling For Multiple Architectures440967
+Node: Installation Names442660
+Node: Specifying the System Type443478
+Node: Sharing Defaults444194
+Node: Operation Controls444867
+Node: Optional Features445825
+Node: Reporting Bugs456625
+Node: Major Differences From The Bourne Shell457900
+Node: GNU Free Documentation License474750
+Node: Indexes499927
+Node: Builtin Index500381
+Node: Reserved Word Index507208
+Node: Variable Index509656
+Node: Function Index526148
+Node: Concept Index539932

 End Tag Table