[darcs-users] explanation of PATTERN?

[Ralph Dratman]

Until recently, I also found the "pattern" or "regex" options
impossible to understand and use, but I finally realized that there is
a rather serious problem of nomenclature. For example, the manual
says:

_____________________

"The --patch and --tag forms simply take (POSIX extended, aka egrep)
regular expressions and match them against tag and patch names.
--match, described below, allows more powerful patterns."
_____________________

Mere wet-brains like myself find this very, very confusing.
Likewise, in the details for the Changes command, we find this:
_____________________

--from-match PATTERN 	
select changes starting with a patch matching PATTERN
_____________________

Again, the above is quite likely to mislead.


The key for me was to understand that

--match PATTERN

takes a PATTERN which is NOT a regex. Rather, PATTERN must look
something like the following, where <string> represents an ordinary
string to be found:

'exact <string>'
Examples:
--match 'exact balloon'
--match 'exact fisherman'

OR

'author <string>'
Examples:
--match 'author Rimbaud'
--match 'author Poe'

>From a language-design point of view the above are, frankly, terrible
constructs. Where one would expect to see a quoted regex, one sees
instead a field-specifier (eg., author or exact) INSIDE the quotes! A
far better syntax would have been something like the following:

--match_exact '<string>'
Example:
--match_exact 'balloon'

--match_author '<string>'
Example:
--match_author 'Poe'

But even such a flawed notation would be rendered almost acceptable if
the manual were at all clear! But it is not clear.

As things stand now, between the difficult-to-parse manual and the
difficult-to-believe grammar, the new user (such as myself) is likely
to remain confused for more time than necessary.

I have expressed myself rather awkwardly above, but do I hope this
message succeeds in clarifying the "--match" grammar a bit.

Ralph

On 12/11/06, Lev Lvovsky <lists2 at sonous.com> wrote:
> On Dec 11, 2006, at 1:00 PM, Eric Y. Kow wrote:
>
> >> darcs --from-match "[test]" gives me:
> >
> > for that you want --from-match "name [test]"
> >
> > if you want to match something with spaces in it:
> > --from-match 'name "foo bar"'
> >
> > there are other matchers besides name (e.g, author, date; look in the
> > manual)
> >
> > note that --patch is the same as --match name, so, for example
> > -p "foo bar" is short for --match 'name "foo bar"'
>
> I'm getting mixed results with this.  Perhaps it's because of the
> "[...]" square brackets acting as a regex character, but for a
> specific example, something with the title of "[build] ....",
> subsequently running darcs unrecord -p "[build]" or "\[build\]"
> brings up recorded items which don't even have "build" in their
> description (in addition however, it does bring back the one I'm
> looking for).  Am I missing something?
>
> thanks!
> -lev
>
> _______________________________________________
> darcs-users mailing list
> darcs-users at darcs.net
> http://www.abridgegame.org/mailman/listinfo/darcs-users
>