Class Pattern

Creates and returns a PEG pattern from a given parameter.

For a given parameter:
* literal string - Matches its specific text (case insensitively) in a
                   subject string.
* list - Must contain a single string which is treated as a character class,
         otherwise a ``ValueError`` will be raised.
         Matches any character in a subject string contained in this class.
* integer - Must be positive or a ``ValueError`` will be raised.
            Matches exactly that many characters in a subject string.
* function - The function will be passed the subject string and current
             index the PEG is at. If a non-negative integer is returned,
             that integer becomes the new index, indicating a match.
* dictionary - A dictionary is interpreted as a grammar. These are useful
               for defining recursive patterns. Each dictionary has key
               names with pattern values, otherwise a ``TypeError`` will be
               raised. Also, there must be a 'default' key whose value is
               the name key for the default pattern to initially match. A
               ``ValueError`` will be raised if it does not exist. If it
               points to an invalid name key, ``KeyError`` will be raised.
* Pattern - The pattern is simply copied.
* anything else - ``TypeError`` will be raised.

Warning: left-recursive patterns are not checked for and will cause a
``RuntimeError`` when ``match`` is called due to a recursion overflow.

Examples::

  # creates a pattern that matches 'foo' literally
  patt = Pattern('foo')

  # creates a pattern that matches 'a', or 'b', or 'c' character once
  patt = Pattern(['abc'])

  # creates a pattern that matches any single character
  patt = Pattern(1)

  # creates a pattern that matches any even, single digit number
  def even_single_digit(subject, index):
    digit = subject[index]
    if digit >= '0' and digit <= '9' and int(digit) % 2 == 0:
      return index + 1
  patt = Pattern(even_single_digit)

  # creates a pattern that searches for 'e'
  patt = Pattern({
    1: Pattern('e') | Pattern(1) + PatternBackRef(1),
    'default': 1
  })

Returns a PEG repetition of this pattern given a slice.

Valid slices are: * ``[:1]`` - matches zero or one occurance of the pattern. * ``[0:]`` - matches zero or more occurances of the pattern. * ``[1:]`` - matches one or more occurances of the pattern. * anything else - ``ValueError`` will be raised.

Warning: repeating patterns that do not consume input zero or more times will cause a ``RuntimeError`` after ``self.REPETITION_LIMIT`` loops. This cannot be checked for.

Examples:

 # creates a pattern that matches 'foo' either not at all or only once
 patt = Pattern('foo')[:0]

 # creates a pattern that matches 'bar' either not at all or many times
 patt = Pattern('bar')[0:]

 # creates a pattern that matches 'baz' at least once
 patt = Pattern('baz')[1:]

Returns a PEG And-predicate for the current pattern.

An And-predicate matches the pattern, but does not consume input.

Examples:

 # creates a pattern that matches 'foo' literally, but does not consume it
 patt = +Pattern('foo')

 # creates a mattern that matches 'foo', but only consumes 'f'
 patt = +Pattern('foo') + 'f'

Returns a PEG Not-predicate for the current pattern.

A Not-predicate matches the inverse of the pattern, consuming no input.

Examples:

 # creates a pattern that does not match the characters 'a', 'b', or 'c'
 patt = -Pattern(['abc'])

 # creates a pattern that matches 'foo', but not 'bar' afterwards
 patt = Pattern('foo') + -Pattern('bar')

Joins this pattern and another together in a PEG Sequence and returns it.

A Sequence matches the first pattern and then the second.

If the other pattern is a literal string, list, integer, function, or dictionary, it is converted into a PEG pattern as in ``__init__`` first.

Examples:

 # creates a pattern that matches 'foo' and 'bar' literally
 patt = Pattern('foo') + 'bar'

Syntactic sugar for ``-other + self``.

Examples:

 # creates a pattern that matches any character but 'a'
 patt = Pattern(1) - 'a'

Join this pattern and another together in a PEG Prioritized Choice and returns it.

A Prioritized Choice matches either pattern, the first taking precedence.

If the other pattern is a literal string, list, integer, function, or dictionary, it is converted into a PEG pattern as in ``__init__`` first.

Examples:

 # creates a pattern that matches 'foo' first, or else 'bar'
 patt = Pattern('foo') | 'bar'

Matches this PEG pattern against a subject string starting at init. If any captures are contained in the pattern, they are returned as a tuple. Otherwise, the index of the first character in subject after the match is returned, or ``-1`` if the match failed.

``IndexError`` will be raised if ``init >= len(subject)``.

Examples:

 patt = Pattern('foo')
 index = patt.match('foobar')
 #result: index = 3

 patt = Pattern('bar')
 index = patt.match('foobar', 3)
 #result: index = 6

 patt = SimpleCapture('foo')
 text, = patt.match('foobar')
 #result: text = 'foo'