History modifier documentation

[Peter Stephenson <pws@xxxxxx>]

There is a traditional entry in the bug list in the FAQ (which I've a
suspicion no-one reads):

  The `:q' and `:x' modifiers don't work for variables.

and there are corresponding remarks in Bart's table of history-to-
variable conversions.

Now, it's not clear to me that this is ever going to work, since by
the time variable expansion is carried out it's a bit late to decide
where the quotes go.  The additional effect of :x is handled
(supposedly) by the word-splitting mechanism, and whether further
expansion takes places is decided by things like the globsubst option.
As noted before, the variable substitution code is fearful and the
idea of randomly inserting extra quotes gives me the willies.

However, the main point of this note is that there are various
limitations with the history variables anyway, some already
documented, and it would be nice to be consistent.

1) :q and :x, see above.  Now we've decided it's a feature, I can
shorten the bug list...

2) :p (don't execute) only works with history, no big surprise.

3) (this is an actual mistake in the documentation) g& doesn't just
apply a substitution to the first match in each word as claimed, it
behaves, as you would probably expect, like the corresponding
gs/.../.../ command and applies globally.  In fact, the bare s or &
applies to the first match in each word, but only with arrays or glob
lists. (If it's supposed to apply to each word in e.g. !*:s/foo/bar/,
there's a bug.)  Also, it seems perverse to mention g separately for &
but include it in the description for s when they are doing the same
thing.  Also, you have to be careful with the & character when using
variable substitution or globbing.  $foo:g& is obviously wrong, due to
parsing, but *(:g&) also doesn't work, you need *(:g\&).

So here is an improved form of the documentation of the modifiers for
3.1; you need yodl to regenerate the manual.

*** Doc/Zsh/expn.yo.mods	Mon Aug  4 17:59:38 1997
--- Doc/Zsh/expn.yo	Fri Oct  3 17:54:44 1997
***************
*** 853,859 ****
  After the optional word designator, you can add
  a sequence of one or more of the following modifiers,
  each preceded by a `tt(:)'.  These modifiers also work on the result
! of em(filename generation) and em(parameter expansion).
  
  startitem()
  item(tt(h))(
--- 853,860 ----
  After the optional word designator, you can add
  a sequence of one or more of the following modifiers,
  each preceded by a `tt(:)'.  These modifiers also work on the result
! of em(filename generation) and em(parameter expansion), except where
! noted.
  
  startitem()
  item(tt(h))(
***************
*** 868,885 ****
  item(tt(t))(
  Remove all leading pathname components, leaving the tail.
  )
- item(tt(&))(
- Repeat the previous substitution.
- )
- item(tt(g))(
- Apply the change to the first occurrence of a match in each word,
- by prefixing the above (for example, `tt(g&)').
- )
  item(tt(p))(
! Print the new command but do not execute it.
  )
  item(tt(q))(
! Quote the substituted words, escaping further substitutions.
  )
  item(tt(x))(
  Like tt(q), but break into words at each blank.
--- 869,881 ----
  item(tt(t))(
  Remove all leading pathname components, leaving the tail.
  )
  item(tt(p))(
! Print the new command but do not execute it.  Only works with history
! expansion.
  )
  item(tt(q))(
! Quote the substituted words, escaping further substitutions.  Only
! works with history expansion.
  )
  item(tt(x))(
  Like tt(q), but break into words at each blank.
***************
*** 911,936 ****
  item(tt(W:)var(sep)tt(:))(
  Like tt(w) but words are considered to be the parts of the string
  that are separated by var(sep). Any character can be used instead of
! the `tt(:)', opening parentheses are handled specially, see above.
  )
  item(tt(s/)var(l)tt(/)var(r)[tt(/)])(
! Substitute var(r) for var(l).
! Unless preceded by a tt(g),
  the substitution is done only for the
! first string that matches var(l).
  )
  enditem()
  
! The left-hand side of substitutions are not regular expressions,
! but character strings.
! Any character can be used as the delimiter in place of `tt(/)'.
! A backslash quotes the delimiter character.  The character `tt(&)',
! in the right hand side, is replaced by the text from the left-hand-side.
! The `tt(&)' can be quoted with a backslash.  A null var(l)
! uses the previous string either from a var(l)
! or from a contextual scan string var(s) from `tt(!?)var(s)'.
! You can omit the rightmost delimiter if a newline immediately follows
! var(r); the rightmost `tt(?)' in a context scan can similarly be omitted.
  
  By default, a history reference with no event specification refers to the same
  line as the last history reference on that command line, unless it is the
--- 907,940 ----
  item(tt(W:)var(sep)tt(:))(
  Like tt(w) but words are considered to be the parts of the string
  that are separated by var(sep). Any character can be used instead of
! the `tt(:)'; opening parentheses are handled specially, see above.
  )
  item(tt(s/)var(l)tt(/)var(r)[tt(/)])(
! Substitute var(r) for var(l) as described below.
! Unless preceded immediately by a tt(g), with no colon between,
  the substitution is done only for the
! first string that matches var(l).  For arrays and filename
! substitution, this applies to each word of the expanded text.
! )
! item(tt(&))(
! Repeat the previous tt(s) substitution.  Like tt(s), may be preceded
! immediately by a tt(g).  In variable expansion the tt(&) must appear
! inside braces, and in filename expansion it must be quoted with a
! backslash.
  )
  enditem()
  
! The tt(s/l/r/) substitution works as follows.  The left-hand side of
! substitutions are not regular expressions, but character strings.  Any
! character can be used as the delimiter in place of `tt(/)'.  A
! backslash quotes the delimiter character.  The character `tt(&)', in
! the right hand side, is replaced by the text from the left-hand-side.
! The `tt(&)' can be quoted with a backslash.  A null var(l) uses the
! previous string either from a var(l) or from a contextual scan string
! var(s) from `tt(!?)var(s)'.  You can omit the rightmost delimiter if a
! newline immediately follows var(r); the rightmost `tt(?)' in a context
! scan can similarly be omitted.  Note the same record of the last
! var(l) and var(r) is maintained across all forms of expansion.
  
  By default, a history reference with no event specification refers to the same
  line as the last history reference on that command line, unless it is the

-- 
Peter Stephenson <pws@xxxxxx>       Tel: +49 33762 77366
WWW:  http://www.ifh.de/~pws/       Fax: +49 33762 77413
Deutsches Elektronen-Synchrotron --- Institut fuer Hochenergiephysik Zeuthen
DESY-IfH, Platanenallee 6, 15738 Zeuthen, Germany.