PATCH: 3.1.6-pws-2: globbing documentation

PATCH: 3.1.6-pws-2: globbing documentation

[Peter Stephenson]

This clarifies the globbing documentation in ways which should be
familiar from recent discussions.  Please look at it and say if you
think that it has the opposite effect.

--- Doc/Zsh/expn.yo.doc	Wed Sep  1 14:41:33 1999
+++ Doc/Zsh/expn.yo	Fri Sep  3 15:52:48 1999
@@ -471,7 +471,7 @@
 Internally, each such expansion is converted into the
 equivalent list for brace expansion.  E.g., tt(${^var}) becomes
 tt({$var[1],$var[2],)...tt(}), and is processed as described in
-noderef(Brace Expansion) above.
+noderef(Brace Expansion) below.
 If word splitting is also in effect the
 tt($var[)var(N)tt(]) may themselves be split into different list
 elements.
@@ -933,6 +933,14 @@
 characters between the braces, in the manner of a search set.
 `tt(-)' is treated specially as in a search set, but `tt(^)' or `tt(!)' as
 the first character is treated normally.
+
+Note that brace expansion is not part of filename generation (globbing); an
+expression such as tt(*/{foo,bar}) is split into two separate words
+tt(*/foo) and tt(*/bar) before filename generation takes place.  In
+particular, note that this is liable to produce a `no match' error if
+em(either) of the two expressions does not match; this is to be contrasted
+with tt(*/(foo|bar)), which is treated as a single pattern but otherwise
+has similar effects.
 texinode(Filename Expansion)(Filename Generation)(Brace Expansion)(Expansion)
 sect(Filename Expansion)
 cindex(filename expansion)
@@ -1084,9 +1092,9 @@
 the `tt(LPAR())' is treated specially, as detailed below. The option
 tt(SH_GLOB) prevents bare parentheses from being used in this way, though
 the tt(KSH_GLOB) option is still available.
-Note that grouping cannot currently extend over multiple directories:
-a `tt(/)' separating a directory terminates processing of the current
-group; processing resumes after the end of the group.
+Note that grouping cannot extend over multiple directories: it is an error
+to have a `tt(/)' within a group (this only applies for patterns which
+match filenames).
 )
 item(var(x)tt(|)var(y))(
 Matches either var(x) or var(y).
@@ -1275,7 +1283,10 @@
 A pathname component of the form `tt(LPAR())var(foo)tt(/RPAR()#)'
 matches a path consisting of zero or more directories
 matching the pattern var(foo).
-As a shorthand, `tt(**/)' is equivalent to `tt((*/)#)'.
+
+As a shorthand, `tt(**/)' is equivalent to `tt((*/)#)'; note that this
+therefore matches files in the current directory as well as
+subdirectories.
 Thus:
 
 example(ls (*/)#bar)
@@ -1284,8 +1295,11 @@
 
 example(ls **/bar)
 
-does a recursive directory search for files named `tt(bar)', not following
-symbolic links.  To follow links, use `tt(***/)'.
+does a recursive directory search for files named `tt(bar)' (potentially
+including the file `tt(bar)' in the current directory), not following
+symbolic links.  To follow links, use `tt(***/)'.  Neither of these can be
+combined with other forms of globbing within the same filename segment; in
+that case, the `tt(*)' operators revert to their usual effect.
 subsect(Glob Qualifiers)
 cindex(globbing, qualifiers)
 cindex(qualifiers, globbing)

-- 
Peter Stephenson <pws@ifh.de>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56100 Pisa, Italy

Re: PATCH: 3.1.6-pws-2: globbing documentation

[Bart Schaefer]

On Sep 3,  4:43pm, Peter Stephenson wrote:
} Subject: PATCH: 3.1.6-pws-2: globbing documentation
}
} This clarifies the globbing documentation in ways which should be
} familiar from recent discussions.  Please look at it and say if you
} think that it has the opposite effect.

Well ...

} +Note that grouping cannot extend over multiple directories: it is an error
} +to have a `tt(/)' within a group (this only applies for patterns which
} +match filenames).

I'd change "which match filenames" to "used in filename generation".  If
I do

	for file in /etc/host* ; do ...; done

I tend to think of $file as "a filename" inside the loop body, but I can
still use [[ $file = (*/)# ]] without getting "bad pattern."

Then down here:

} +As a shorthand, `tt(**/)' is equivalent to `tt((*/)#)'; note that this
} +therefore matches files in the current directory as well as
} +subdirectories.

Wait, we just said that (*/)# was not a legal pattern!  How can **/ be a
shorthand for it?  What we really mean (now) is that ** is a _replacement_
(or "alternative" or some such word) for (*/)#, right?

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

Re: PATCH: 3.1.6-pws-2: globbing documentation

[Peter Stephenson]

"Bart Schaefer" wrote:
> } +As a shorthand, `tt(**/)' is equivalent to `tt((*/)#)'; note that this
> } +therefore matches files in the current directory as well as
> } +subdirectories.
> 
> Wait, we just said that (*/)# was not a legal pattern!  How can **/ be a
> shorthand for it?  What we really mean (now) is that ** is a _replacement_
> (or "alternative" or some such word) for (*/)#, right?

I'd forgotten that (<pat>/)# is a special case, dating all the way back to
pfalstad; it's handled in the globbing code, not the pattern matching code,
so it's not affected by the patches.  However, I noticed a bug: something
like (foo*/)# produces a null string alongside the correct set of matches.
This is because the test for an existing file adds a "." if the current
segment is empty.  That's fine if there is already a path, turning foo/
into foo/. for the test to bypass system foolishness, but if there's
nothing there already it shouldn't do that.  I hope.

--- Doc/Zsh/expn.yo.glob	Fri Sep  3 15:52:48 1999
+++ Doc/Zsh/expn.yo	Fri Sep  3 16:52:38 1999
@@ -1092,9 +1092,13 @@
 the `tt(LPAR())' is treated specially, as detailed below. The option
 tt(SH_GLOB) prevents bare parentheses from being used in this way, though
 the tt(KSH_GLOB) option is still available.
+
 Note that grouping cannot extend over multiple directories: it is an error
-to have a `tt(/)' within a group (this only applies for patterns which
-match filenames).
+to have a `tt(/)' within a group (this only applies for patterns used in
+filename generation).  There is one exception:  a group of the form
+tt(LPAR())var(pat)tt(/RPAR()#) appearing as a complete path segment can
+match a sequence of directories.  For example, tt(foo/(a*/)#bar) matches
+tt(foo/bar), tt(foo/any/bar), tt(foo/any/anyother/bar), and so on).
 )
 item(var(x)tt(|)var(y))(
 Matches either var(x) or var(y).
--- Src/glob.c.glob	Mon Aug 30 16:25:13 1999
+++ Src/glob.c	Fri Sep  3 16:48:15 1999
@@ -243,7 +243,11 @@
 	  "BUG: statfullpath(): pathname too long");
     strcpy(buf, pathbuf + pathbufcwd);
     strcpy(buf + pathpos - pathbufcwd, s);
-    if (!*s) {
+    if (!*s && *buf) {
+	/*
+	 * Don't add the '.' if the path so far is empty, since
+	 * then we get bogus empty strings inserted as files.
+	 */
 	buf[pathpos - pathbufcwd] = '.';
 	buf[pathpos - pathbufcwd + 1] = '\0';
 	l = 0;

-- 
Peter Stephenson <pws@ifh.de>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56127 Pisa, Italy