.. $Id: pattern.txt 057d79259b20 2009-05-14 mtnyogi $
.. 
.. Copyright © 2007-2008 Bruce Frederiksen
.. 
.. Permission is hereby granted, free of charge, to any person obtaining a copy
.. of this software and associated documentation files (the "Software"), to deal
.. in the Software without restriction, including without limitation the rights
.. to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
.. copies of the Software, and to permit persons to whom the Software is
.. furnished to do so, subject to the following conditions:
.. 
.. The above copyright notice and this permission notice shall be included in
.. all copies or substantial portions of the Software.
.. 
.. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
.. IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
.. FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
.. AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
.. LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
.. OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
.. THE SOFTWARE.

restindex
    crumb: Pattern
    page-description:
        The syntax of a pattern used to match data values.
    /description
    format: rest
    encoding: utf8
    output-encoding: utf8
    include: yes
    initialheaderlevel: 2
/restindex

uservalues
    filedate: $Id: pattern.txt 057d79259b20 2009-05-14 mtnyogi $
/uservalues

=============================================
Pattern Syntax
=============================================

Pattern
============

::

    pattern ::= 'None' | 'True' | 'False'
              | NUMBER | IDENTIFIER | STRING | variable
              | '(' [{pattern,}] ['*' variable] ')'

IDENTIFIER acts like a STRING here, meaning that it is taken as a literal
value.  All variables in patterns must be preceded by a ``$``.

Pyke does not currently support complex NUMBERS (for no good reason -- email
me if you need them).

Pattern Variable
===================

`Pattern variables`__ are simply called *variable* in the syntax::

    variable ::= '$'IDENTIFIER

The variable must not have a space between the ``$`` and the ``IDENTIFIER``.

.. __: `pattern variable lp`_

Anonymous Variable
====================

If the pattern variable IDENTIFIER begins with an underscore (_), the variable
is an `anonymous variable`__.  It acts like a "don't care".  Technically, this
means that multiple uses of the same IDENTIFIER may stand for different
values.  The name of the IDENTIFIER after the underscore is ignored and may be
used to document the use of the anonymous variable.

.. __: `anonymous variable lp`_

Rest Variable
================

The ``*variable`` at the end of a tuple pattern will match the rest of the
tuple.  Thus, ``variable`` is *always* bound to a (possibly empty) tuple.

The syntax is taken from rest parameter syntax in Python function definitions.
The difference here is that the variable needs a ``$`` on it.

You may use either a named variable or an anonymous variable here.


