[PATCH] explicitly mention ${name:/pat/repl}

[PATCH] explicitly mention ${name:/pat/repl}

[Bart Schaefer]

I was annoyed how hard it was to search the docs for this.

Any inaccuracies?  Objections?

diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index f465b2f..f67796f 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -782,12 +782,14 @@ prepending tt($0).  Hence tt(${*:0:1}) substitutes tt($0) and
 tt(${*:1:1}) substitutes tt($1).
 )
 xitem(tt(${)var(name)tt(/)var(pattern)tt(/)var(repl)tt(}))
-item(tt(${)var(name)tt(//)var(pattern)tt(/)var(repl)tt(}))(
+xitem(tt(${)var(name)tt(//)var(pattern)tt(/)var(repl)tt(}))
+item(tt(${)var(name)tt(:/)var(pattern)tt(/)var(repl)tt(}))(
 Replace the longest possible match of var(pattern) in the expansion of
 parameter var(name) by string var(repl).  The first form
-replaces just the first occurrence, the second form all occurrences.
+replaces just the first occurrence, the second form all occurrences,
+and the third form replaces only if var(pattern) matches the entire string.
 Both var(pattern) and var(repl) are subject to double-quoted substitution,
-so that expressions like tt(${name/$opat/$npat}) will work, but note the
+so that expressions like tt(${name/$opat/$npat}) will work, but obey the
 usual rule that pattern characters in tt($opat) are not treated specially
 unless either the option tt(GLOB_SUBST) is set, or tt($opat) is instead
 substituted as tt(${~opat}).
@@ -803,8 +805,8 @@ single backslash; this is not necessary if the
 `tt(%)' and `tt(#%) are not active if they occur inside a substituted
 parameter, even at the start.
 
-The first `tt(/)' may be preceded by a `tt(:)', in which case the match
-will only succeed if it matches the entire word.  Note also the
+If tt(${)var(name)tt(}) expands to an array value, the replacements act
+on each element individually.  Quoting may affect this.  Note also the
 effect of the tt(I) and tt(S) parameter expansion flags below; however,
 the flags tt(M), tt(R), tt(B), tt(E) and tt(N) are not useful.
 

Re: [PATCH] explicitly mention ${name:/pat/repl}

[Daniel Shahaf]

Bart Schaefer wrote on Tue, Nov 08, 2016 at 10:10:43 -0800:
> -The first `tt(/)' may be preceded by a `tt(:)', in which case the match
> -will only succeed if it matches the entire word.  Note also the
> +If tt(${)var(name)tt(}) expands to an array value, the replacements act
> +on each element individually.  Quoting may affect this.  Note also the

"Quoting may affect this"?  This leaves me wondering what the effect is
and under what circumstances it happens.

I assume this has to do with the «"${(@)foo}"» syntax?

>  effect of the tt(I) and tt(S) parameter expansion flags below; however,
>  the flags tt(M), tt(R), tt(B), tt(E) and tt(N) are not useful.
>  
> 

Re: [PATCH] explicitly mention ${name:/pat/repl}

[Bart Schaefer]

On Nov 9,  5:14am, Daniel Shahaf wrote:
} Subject: Re: [PATCH] explicitly mention ${name:/pat/repl}
}
} Bart Schaefer wrote on Tue, Nov 08, 2016 at 10:10:43 -0800:
} > -The first `tt(/)' may be preceded by a `tt(:)', in which case the match
} > -will only succeed if it matches the entire word.  Note also the
} > +If tt(${)var(name)tt(}) expands to an array value, the replacements act
} > +on each element individually.  Quoting may affect this.  Note also the
} 
} "Quoting may affect this"?  This leaves me wondering what the effect is
} and under what circumstances it happens.

It just means that if you quote the expansion, it won't necessarily
be an array any more.  There are too many ways this could happen to
enumerate them all every time it might apply.

Re: [PATCH] explicitly mention ${name:/pat/repl}

[Bart Schaefer]

On Nov 8, 10:39pm, Bart Schaefer wrote:
}
} It just means that if you quote the expansion, it won't necessarily
} be an array any more.  There are too many ways this could happen to
} enumerate them all every time it might apply.

How about this, then.

diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index f465b2f..87ca790 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -782,12 +782,14 @@ prepending tt($0).  Hence tt(${*:0:1}) substitutes tt($0) and
 tt(${*:1:1}) substitutes tt($1).
 )
 xitem(tt(${)var(name)tt(/)var(pattern)tt(/)var(repl)tt(}))
-item(tt(${)var(name)tt(//)var(pattern)tt(/)var(repl)tt(}))(
+xitem(tt(${)var(name)tt(//)var(pattern)tt(/)var(repl)tt(}))
+item(tt(${)var(name)tt(:/)var(pattern)tt(/)var(repl)tt(}))(
 Replace the longest possible match of var(pattern) in the expansion of
 parameter var(name) by string var(repl).  The first form
-replaces just the first occurrence, the second form all occurrences.
+replaces just the first occurrence, the second form all occurrences,
+and the third form replaces only if var(pattern) matches the entire string.
 Both var(pattern) and var(repl) are subject to double-quoted substitution,
-so that expressions like tt(${name/$opat/$npat}) will work, but note the
+so that expressions like tt(${name/$opat/$npat}) will work, but obey the
 usual rule that pattern characters in tt($opat) are not treated specially
 unless either the option tt(GLOB_SUBST) is set, or tt($opat) is instead
 substituted as tt(${~opat}).
@@ -803,8 +805,8 @@ single backslash; this is not necessary if the
 `tt(%)' and `tt(#%) are not active if they occur inside a substituted
 parameter, even at the start.
 
-The first `tt(/)' may be preceded by a `tt(:)', in which case the match
-will only succeed if it matches the entire word.  Note also the
+If, after quoting rules apply, tt(${)var(name)tt(}) expands to an array,
+the replacements act on each element individually.  Note also the
 effect of the tt(I) and tt(S) parameter expansion flags below; however,
 the flags tt(M), tt(R), tt(B), tt(E) and tt(N) are not useful.
 

Re: [PATCH] explicitly mention ${name:/pat/repl}

[Daniel Shahaf]

Bart Schaefer wrote on Tue, Nov 08, 2016 at 23:22:52 -0800:
> +If, after quoting rules apply, tt(${)var(name)tt(}) expands to an array,
> +the replacements act on each element individually.  Note also the

+1, looks good to me.