From @RandalSchwartz

The globbing described by the File​::Glob manpage, which is also used
for the default globbing in 5.6, does not give any definition or even
enough examples to know what is provided and what is not. (Older
Perls got away with "this does what your shell does", but that's no
longer true.)

I suppose I could wander through the source to find out, but a quick
description would be good on the manpage for those that don't have the
wherewithall to do that.

For example, I suspect the following is supported​:

  [abc0-9]
  *
  ?
  non-matching of "." unless explicit
  multi-level like /*/*/foo.c
  \-quoting

because these are in V7 glob. But I also see examples that show
csh-style globbing with "{foo,bar}*.c". So, I'm left baffled with the
manpage, and I bet dozens of other users are as well.

From schubiger@cpan.org

[merlyn@​stonehenge.com - Mon Apr 24 02​:04​:15 2000]​:

The globbing described by the File​::Glob manpage, which is also used
for the default globbing in 5.6, does not give any definition or even
enough examples to know what is provided and what is not. (Older
Perls got away with "this does what your shell does", but that's no
longer true.)

Agreed.

Some info to start with, since we shouldn't expect, that everybody
using File​::Glob is familiar to the semantics of Perl's core glob().

[glob(3)]
The glob() function is a pathname generator that implements the rules for
file name pattern matching used by the shell.

glob() matches all accessible pathnames against the pattern and creates a
list of the pathnames that match. In order to have access to a pathname,
glob() requires search permission on every component of a path except the
last and read permission on each directory of any filename component of
pattern that contains any of the special characters `*', `?', or `['.
[/glob(3)]

I suppose I could wander through the source to find out, but a quick
description would be good on the manpage for those that don't have the
wherewithall to do that.

Everything seems to boil down to Glob.xs, which then #include's "bsd_glob.h"
-> bsd_glob.c. So, I'd say glob(3) should suffice mostly therefore, which is
being mentioned introductory in the docs + additional text above.

For example, I suspect the following is supported​:

    \[abc0\-9\]
    \*
    ?
    non\-matching of "\." unless explicit
    multi\-level like /\*/\*/foo\.c
    \\\-quoting

because these are in V7 glob.

Sighted these meta chars hiding in the docs and they seem to need some
explanation, since a reference to perlre would be to exhaustive
and in my view, inadequate too, since perlre documents functionality
that is not given here.

But I also see examples that show csh-style globbing with "{foo,bar}*.c". So, I'm left baffled with the
manpage, and I bet dozens of other users are as well.

Yes, needs some special treatmeant though.

Any objections or shall I start working on a patch?

From @demerphq

On 28 Mar 2005 03​:35​:32 -0000, Steven Schubiger via RT
<perlbug-followup@​perl.org> wrote​:

[merlyn@​stonehenge.com - Mon Apr 24 02​:04​:15 2000]​:

The globbing described by the File​::Glob manpage, which is also used
for the default globbing in 5.6, does not give any definition or even
enough examples to know what is provided and what is not. (Older
Perls got away with "this does what your shell does", but that's no
longer true.)

Agreed.

Some info to start with, since we shouldn't expect, that everybody
using File​::Glob is familiar to the semantics of Perl's core glob().

[glob(3)]
The glob() function is a pathname generator that implements the rules for
file name pattern matching used by the shell.

glob() matches all accessible pathnames against the pattern and creates a
list of the pathnames that match. In order to have access to a pathname,
glob() requires search permission on every component of a path except the
last and read permission on each directory of any filename component of
pattern that contains any of the special characters `*', `?', or `['.
[/glob(3)]

I suppose I could wander through the source to find out, but a quick
description would be good on the manpage for those that don't have the
wherewithall to do that.

Everything seems to boil down to Glob.xs, which then #include's "bsd_glob.h"
-> bsd_glob.c. So, I'd say glob(3) should suffice mostly therefore, which is
being mentioned introductory in the docs + additional text above.

For example, I suspect the following is supported​:

    \[abc0\-9\]
    \*
    ?
    non\-matching of "\." unless explicit
    multi\-level like /\*/\*/foo\.c
    \\\-quoting

because these are in V7 glob.

Sighted these meta chars hiding in the docs and they seem to need some
explanation, since a reference to perlre would be to exhaustive
and in my view, inadequate too, since perlre documents functionality
that is not given here.

But I also see examples that show csh-style globbing with "{foo,bar}*.c". So, I'm left baffled with the
manpage, and I bet dozens of other users are as well.

Yes, needs some special treatmeant though.

Any objections or shall I start working on a patch?

Please try to keep in mind that many win32 users will have no access
to documentation for these things outside of perl.

Cheers,
yves

--
perl -Mre=debug -e "/just|another|perl|hacker/"

From @schwern

Some documentation of the meta characters has been added to File​::Glob
but not much else. Just how much documentation of globbing do we want
to put in the docs and how much can be "go read X"? Maybe a reference
to a Unix tutorial on how globbing works?

From @RandalSchwartz

"Michael" == Michael G Schwern via RT <perlbug-followup@​perl.org> writes​:

Michael> Some documentation of the meta characters has been added to File​::Glob
Michael> but not much else. Just how much documentation of globbing do we want
Michael> to put in the docs and how much can be "go read X"? Maybe a reference
Michael> to a Unix tutorial on how globbing works?

Well, if they're on Windows, they don't have "X" for the most part.
Just a reference doc would be fine​:

  [a-z]
  *
  ?
  {a,b,c}
  ~

etc. Maybe we can take the BSD manpage (with liberal copyright terms)
and just insert relevant portions.

--
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<merlyn@​stonehenge.com> <URL​:http​://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!

From @schwern

On Thu, Jul 14, 2005 at 01​:09​:10PM -0700, Randal L. Schwartz wrote​:

Just how much documentation of globbing do we want
to put in the docs and how much can be "go read X"? Maybe a
reference to a Unix tutorial on how globbing works?

Well, if they're on Windows, they don't have "X" for the most part.

There's this new fangled technology called "the web".

Just a reference doc would be fine​:

    \[a\-z\]
    \*
    ?       
    \{a\,b\,c\}
    ~

etc. Maybe we can take the BSD manpage (with liberal copyright terms)
and just insert relevant portions.

There's already this​:

  META CHARACTERS

  \ Quote the next metacharacter
  [] Character class
  {} Multiple pattern
  * Match any string of characters
  ? Match any single character
  ~ User name home directory

  The metanotation "a{b,c,d}e" is a shorthand for "abe ace ade". Left to
  right order is preserved, with results of matches being sorted sepa-
  rately at a low level to preserve this order. As a special case "{",
  "}", and "{}" are passed undisturbed.

but only {} is explicitly explained. I don't know how much of the rest
need detailed explainations as the terms should already be familiar from
regular expressions. Maybe that needs to be made explicit?

Anyhow, I don't think File​::Glob should cut & paste a man page to explain
file globbing in detail. Its out of scope. A reference to a web page will
do a better job.

Know any?

--
Michael G Schwern schwern@​pobox.com http​://www.pobox.com/~schwern
Reality is that which, when you stop believing in it, doesn't go away.
  -- Phillip K. Dick

From @hvds

Michael G Schwern <schwern@​pobox.com> wrote​:
:Anyhow, I don't think File​::Glob should cut & paste a man page to explain
:file globbing in detail. Its out of scope. A reference to a web page will
:do a better job.

There's a stub here​:
  http​://en.wikipedia.org/wiki/Glob_pattern
.. which is just waiting for someone to fill it out.

Hugo

From @smpeters

[hv - Thu Jul 14 16​:45​:57 2005]​:

Michael G Schwern <schwern@​pobox.com> wrote​:
:Anyhow, I don't think File​::Glob should cut & paste a man page to explain
:file globbing in detail. Its out of scope. A reference to a web
page will
:do a better job.

There's a stub here​:
http​://en.wikipedia.org/wiki/Glob_pattern
.. which is just waiting for someone to fill it out.

Hugo

Or maybe a webpage like the Single Unix Specification at
<http​://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_13>?

From @jkeenan

There has been no correspondence on this ticket for nearly six years,
which is a prima facie case for closing it.

Since I am coming to it fresh, I read​:

  perldoc File​::Glob
  perldoc -f glob
  man 3 glob (Darwin)

My judgment is that the POD for File​::Glob is sufficient. About the
only thing someone might consider adding is one sentence explaining the
circumstances where someone would want to use File​::Glob rather than the
built-in glob(). (In my own work, I have never had to resort to
File​::Glob.)

Do we want such a one-sentence description? If not, the ticket should
be closed.

Thank you very much.
Jim Keenan

From @cpansprout

On Sun Nov 06 05​:48​:29 2011, jkeen@​verizon.net wrote​:

There has been no correspondence on this ticket for nearly six years,
which is a prima facie case for closing it.

Since I am coming to it fresh, I read​:

perldoc File​::Glob
perldoc -f glob
man 3 glob (Darwin)

My judgment is that the POD for File​::Glob is sufficient. About the
only thing someone might consider adding is one sentence explaining the
circumstances where someone would want to use File​::Glob rather than the
built-in glob(). (In my own work, I have never had to resort to
File​::Glob.)

Do we want such a one-sentence description?

perlfunc/glob and File​::Glob have long mentioned that File​::Glob’s
bsd_glob function does not split the pattern into words.

If not, the ticket should
be closed.

I’m closing it now.

Thank you very much.
Jim Keenan

--

Father Chrysostomos

@cpansprout - Status changed from 'open' to 'resolved'