Attempt to document aliasing more fully

Attempt to document aliasing more fully

[Bart Schaefer]

So here is what I have (see diff below).  This describes the situation
prior to workers/34641.  To keep 34641, we'd just have to add another
itemiz() calling out command separators as a separate class of "word",
though I still think that if included, those should (a) still exclude
newline and (b) require "alias -g".

Either way I rather suspect that POSIX_ALIASES should prohibit more
than just the reserved words, e.g., I doubt that parameter references
and quoted strings are meant to be allowed in aliases by POSIX.  That
should get fixed, along with the bug(s) mentioned in 34668 and 34682.


diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo
index 63d90df..ee44841 100644
--- a/Doc/Zsh/grammar.yo
+++ b/Doc/Zsh/grammar.yo
@@ -532,12 +532,12 @@ characters up to a newline to be ignored.
 texinode(Aliasing)(Quoting)(Comments)(Shell Grammar)
 sect(Aliasing)
 cindex(aliasing)
-Every token in the shell input is checked to see if there
+Every eligible em(word) in the shell input is checked to see if there
 is an alias defined for it.
 If so, it is replaced by the text of the alias if it is in command
 position (if it could be the first word of a simple command),
 or if the alias is global.
-If the text ends with a space, the next word in the shell input
+If the replacement text ends with a space, the next word in the shell input
 is treated as though it were in command position for purposes of alias
 expansion.
 findex(alias, use of)
@@ -545,6 +545,22 @@ cindex(aliases, global)
 An alias is defined using the tt(alias) builtin; global aliases
 may be defined using the tt(-g) option to that builtin.
 
+A em(word) is defined as:
+
+startitemize()
+itemiz(Any plain string or glob pattern)
+itemiz(Any quoted string, using any quoting method (note that the quotes
+must be part of the alias definition for this to be eligible))
+itemiz(Any parameter reference or command substitution)
+itemiz(Any series of the foregoing, concatenated without whitespace or
+other tokens between them)
+itemiz(Any reserved word (tt(case), tt(do), tt(else), etc.))
+enditemize()
+
+Reserved words are not eligible for aliasing when tt(POSIX_ALIASES) set.
+The alias builtin does not reject ineligible aliases, but they are not
+expanded.
+
 Alias expansion is done on the shell input before any other expansion
 except history expansion.  Therefore, if an alias is defined for the
 word tt(foo), alias expansion may be avoided by quoting part of the

Re: Attempt to document aliasing more fully

[Peter Stephenson]

On Sat, 14 Mar 2015 13:54:06 -0700
Bart Schaefer <schaefer@brasslantern.com> wrote:
> So here is what I have (see diff below).  This describes the situation
> prior to workers/34641.  To keep 34641, we'd just have to add another
> itemiz() calling out command separators as a separate class of "word",
> though I still think that if included, those should (a) still exclude
> newline and (b) require "alias -g".

Thanks, that looks reasonable.  I'd sort of vaguely be inclined to point
out a bit more actively that if you're aliasing quoted stuff the quotes
form part of the alias (which is kind of weird if your use to shells written by normal people) and maybe hint what therefore doesn't get aliased (though I entirely agree with the basic logic, i.e. spelling out what does), but that's very minor.

I've got no very strong feelings about keeping the new feature since
it's been the way it has for decades and it only got noticed as a side
issue.  However, the limitations above sound sane, since using "alias
-g" is already for hotheads, so maybe that's a good compromise.

> Either way I rather suspect that POSIX_ALIASES should prohibit more
> than just the reserved words, e.g., I doubt that parameter references
> and quoted strings are meant to be allowed in aliases by POSIX.  That
> should get fixed, along with the bug(s) mentioned in 34668 and 34682.

Yes, I agree with that.

pws

Re: Attempt to document aliasing more fully

[Bart Schaefer]

On Mar 15,  6:35pm, Peter Stephenson wrote:
} Subject: Re: Attempt to document aliasing more fully
}
} On Sat, 14 Mar 2015 13:54:06 -0700
} Bart Schaefer <schaefer@brasslantern.com> wrote:
} > So here is what I have (see diff below).  This describes the situation
} > prior to workers/34641.  To keep 34641, we'd just have to add another
} > itemiz() calling out command separators as a separate class of "word",
} > though I still think that if included, those should (a) still exclude
} > newline and (b) require "alias -g".
} 
} Thanks, that looks reasonable.

OK, I'll start by committing that and we can go from there.

Re: Attempt to document aliasing more fully

[Bart Schaefer]

On Mar 15,  6:35pm, Peter Stephenson wrote:
} Subject: Re: Attempt to document aliasing more fully
}
} On Sat, 14 Mar 2015 13:54:06 -0700
} Bart Schaefer <schaefer@brasslantern.com> wrote:
} > though I still think that if included, those should (a) still exclude
} > newline and (b) require "alias -g".
} 
} I've got no very strong feelings about keeping the new feature since
} it's been the way it has for decades and it only got noticed as a side
} issue.  However, the limitations above sound sane, since using "alias
} -g" is already for hotheads, so maybe that's a good compromise.

OK, no code changes yet, but here for consideration is the corresponding
documentation change.  The caveats necessary about "((" and "\&&" give
me a nervous tic and re-emphasize why I think allowing this is loony.
On the other hand we already have this problem with \$(echo foo) [which
I think nobody would complain about *dropping* from the list of eligible
words, but I've been wrong before].


diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo
index b30e423..e8e68ed 100644
--- a/Doc/Zsh/grammar.yo
+++ b/Doc/Zsh/grammar.yo
@@ -538,8 +538,7 @@ If so, it is replaced by the text of the alias if it is in command
 position (if it could be the first word of a simple command),
 or if the alias is global.
 If the replacement text ends with a space, the next word in the shell input
-is treated as though it were in command position for purposes of alias
-expansion.
+is always eligible for purposes of alias expansion.
 findex(alias, use of)
 cindex(aliases, global)
 An alias is defined using the tt(alias) builtin; global aliases
@@ -555,22 +554,32 @@ itemiz(Any parameter reference or command substitution)
 itemiz(Any series of the foregoing, concatenated without whitespace or
 other tokens between them)
 itemiz(Any reserved word (tt(case), tt(do), tt(else), etc.))
+itemiz(With global aliasing, any command separator, any redirection
+operator, and `tt(LPAR())' or `tt(RPAR())' when not part of a glob pattern
 enditemize()
 
-Reserved words are not eligible for aliasing when tt(POSIX_ALIASES) is set.
-The tt(alias) builtin does not reject ineligible aliases, but they are not
-expanded.
+It is not presently possible to alias the `tt(LPAR()LPAR())' token that
+introduces arithmetic expressions, because until a full statement has been
+parsed, it cannot be distinguished from two consecutive `tt(LPAR())'
+tokens introducing nested subshells.
+
+When tt(POSIX_ALIASES) is set, only plain strings or glob patterns are
+eligible for aliasing.  The tt(alias) builtin does not reject ineligible
+aliases, but they are not expanded.
 
 Alias expansion is done on the shell input before any other expansion
 except history expansion.  Therefore, if an alias is defined for the
 word tt(foo), alias expansion may be avoided by quoting part of the
 word, e.g. tt(\foo).  Any form of quoting works, although there is
 nothing to prevent an alias being defined for the quoted form such as
-tt(\foo) as well.  For use with completion, which would remove an
-initial backslash followed by a character that isn't special, it may be
-more convenient to quote the word by starting with a single quote,
-i.e. tt('foo); completion will automatically add the trailing single
-quote.
+tt(\foo) as well.  Also, if a separator such as tt(&&) is aliased,
+tt(\&&) turns into the two tokens tt(\&) and tt(&), each of which may
+have been aliased separately.  Similarly for tt(\<<), tt(\>|), etc.
+
+For use with completion, which would remove an initial backslash followed
+by a character that isn't special, it may be more convenient to quote the
+word by starting with a single quote, i.e. tt('foo); completion will
+automatically add the trailing single quote.
 
 There is a commonly encountered problem with aliases
 illustrated by the following code: