Permalink
Browse files

Failed matches to return Nil, not (Match)

A Match now only ever represents a successful match.  A failed match is
represented by Nil.  Also, we add Match and Nil to the list of things
that are explicitly not allowed as literal tokens to smartmatchers due
to their use as success/failure from .ACCEPTS methods.

And a great sigh of relief comes from those who didn't want the OKness
proposal to go much farther than that...  :-)
  • Loading branch information...
1 parent b50c8aa commit c8f2dcc68c3646bac45fafccd86368920ddd18ea @TimToady TimToady committed Feb 23, 2013
Showing with 34 additions and 23 deletions.
  1. +18 −13 S03-operators.pod
  2. +13 −7 S05-regex.pod
  3. +3 −3 S29-functions.pod
View
@@ -14,8 +14,8 @@ Synopsis 3: Perl 6 Operators
Created: 8 Mar 2004
- Last Modified: 11 Jan 2013
- Version: 259
+ Last Modified: 23 Feb 2013
+ Version: 260
=head1 Overview
@@ -2512,7 +2512,7 @@ C<< infix:<or> >>, short-circuit inclusive or
Returns the first argument that evaluates to true, otherwise returns
the result of the last argument. In list context forces a false return
-to mean C<()>, or C<Nil>. See C<||> above for high-precedence version.
+to mean C<()>. See C<||> above for high-precedence version.
=item *
@@ -3412,7 +3412,7 @@ endpoint in the Range.
If used in a list context, a C<Range> object returns an iterator that
produces a sequence of values starting at the min and ending at the max.
Either endpoint may be excluded using C<^>. Hence C<1..2> produces
-C<(1,2)> but C<1^..^2> is equivalent to C<2..1> and produces no values (Nil).
+C<(1,2)> but C<1^..^2> is equivalent to C<2..1> and produces no values, like C<()> does.
To specify a sequence that counts down, use a reverse:
reverse 1..2
@@ -3469,7 +3469,7 @@ inferred from the right operand. (A star on both sides is not allowed.)
v1.2.3 .. * # Any version higher than 1.2.3.
May .. * # May through December
-An empty range cannot be iterated; it returns a C<Nil> instead. An empty
+An empty range cannot be iterated; it returns C<()> instead. An empty
range still has a defined C<.min> and C<.max>, but one of the following is
true: 1. The C<.min> is greater than the C<.max>. 2. The C<.min> is equal
to the C<.max> I<and> at least one of C<.excludes_min> or C<.excludes_max> is true.
@@ -3590,18 +3590,20 @@ as a default because the more specific types listed above it didn't match.
$_ X Type of Match Implied Match if (given $_)
====== ===== ===================== ===================
- Any True ~~ True (parsewarn)
- Any False ~~ False match (parsewarn)
+ Any True ~~ True (parsewarn on literal token)
+ Any False ~~ False match (parsewarn on literal token)
+ Any Match ~~ Successful match (parsewarn on literal token)
+ Any Nil ~~ Benign failure (parsewarn on literal token)
Any * block signature match block successfully binds to |$_
Any Callable:($) item sub truth X($_)
Any Callable:() simple closure truth X() (ignoring $_)
- Any Bool simple truth X
- Any Match match success X
+ Any Bool simple truth X (treats Bool value as success/failure)
+ Any Match match success X (treats Match value as success)
+ Any Nil benign failure X (treats Nil value as failure)
Any Numeric numeric equality +$_ == X
Any Stringy string equality ~$_ eq X
Any Whatever always matches True
- Any Nil is nil $_ === Nil
Hash Pair test hash mapping $_{X.key} ~~ X.value
Any Pair test object attribute ?."{X.key}" === ?X.value (e.g. filetests)
@@ -3826,10 +3828,13 @@ C<*> to match anything, if that's what you really want. Or use a closure
that returns a constant boolean value.)
Note also that regex matching does I<not> return a C<Bool>, but merely
-a C<Match> object that can be used as a boolean value. Use an explicit
-C<?> or C<so> to force a C<Bool> value if desired.
+a C<Match> object (or a C<Nil>) that can be used as a boolean value. Use an explicit
+C<?> or C<so> to force a C<Bool> value if desired. A C<Match> object
+represents a successful match and is treated by smartmatching the same as a C<True>,
+Similarly, a C<Nil> represents a failure, and cannot be used directly on the
+right side of a smartmatch. Test for definedness instead, or use C<* === Nil>.
-The primary use of the C<~~> operator is to return a boolean value in
+The primary use of the C<~~> operator is to return a boolean-ish value in
a boolean context. However, for certain operands such as regular
expressions, use of the operator within item or list context transfers
the context to that operand, so that, for instance, a regular expression
View
@@ -17,8 +17,8 @@ Synopsis 5: Regexes and Rules
Created: 24 Jun 2002
- Last Modified: 5 Oct 2012
- Version: 159
+ Last Modified: 23 Feb 2013
+ Version: 160
This document summarizes Apocalypse 5, which is about the new regex
syntax. We now try to call them I<regex> rather than "regular
@@ -2268,7 +2268,7 @@ object in others).
=item *
-Specifically, a C</.../> matches immediately in a value context (void,
+Specifically, a C</.../> matches immediately in a value context (sink,
Boolean, string, or numeric), or when it is an explicit argument of
a C<~~>. Otherwise it's a C<Regex> constructor identical to the explicit
C<regex> form. So this:
@@ -2818,15 +2818,18 @@ the regex containing the C<||>.
=item *
-A match always returns a C<Match> object, which is also available
-as C<$/>, which is a dynamic lexical declared in the outer
+A successful match always returns a C<Match> object, which is generally also
+put into C<$/>, a dynamic lexical declared in the outer
routine that is calling the regex. (A named C<regex>, C<token>,
or C<rule> is a routine, and hence declares its own
lexical C<$/> variable, which always refers to the most recent
submatch within the rule, if any.) The current match state is
kept in the regex's C<$¢> variable which will eventually get
bound to the user's C<$/> variable when the match completes.
+An unsuccessful match returns C<Nil> (and sets C<$/> to C<Nil> if
+the match would have set it).
+
=item *
Notionally, a match object contains (among other things) a boolean
@@ -3039,12 +3042,15 @@ in the parse tree.]
=item *
-All match attempts--successful or not--against any regex, subrule, or
-subpattern (see below) return an object of class C<Match>. That is:
+All match attempts--successful or not--against any regex, subrule,
+or subpattern (see below) return an object that can be evaluated
+as a boolean. (This object will be either a C<Match> or a C<Nil>.)
+That is:
$match_obj = $str ~~ /pattern/;
say "Matched" if $match_obj;
+
=item *
This returned object is also automatically bound to the lexical
View
@@ -19,8 +19,8 @@ Synopsis 29: Builtin Functions
Created: 12 Mar 2005
- Last Modified: 5 Nov 2012
- Version: 53
+ Last Modified: 23 Feb 2013
+ Version: 54
The document is a draft.
@@ -116,7 +116,7 @@ C<CharTurkish>, etc. for instantiated C<CharLingua> types.
=item Matcher
- subset Matcher of Mu where none(Bool)
+ subset Matcher of Mu where * !=== any(Bool,Match,Nil)
Used to supply a test to match against. Assume C<~~> will be used against it.
Booleans are forbidden because they almost always indicate a programming

0 comments on commit c8f2dcc

Please sign in to comment.