Add children option to patterns

.coveragerc

@@ -5,7 +5,6 @@ include =
 omit =
     rebulk/__version__.py
     rebulk/test/*
-    rebulk/ordered_set.py
 [report]
 exclude_lines =
     pragma: no cover

README.rst

@@ -7,10 +7,10 @@ ReBulk
 
 .. image:: http://img.shields.io/badge/license-MIT-blue.svg
     :target: https://pypi.python.org/pypi/rebulk
-    :alt: License
+    :alt: MIT License
 
 .. image:: http://img.shields.io/travis/Toilal/rebulk.svg
-    :target: http://travis-ci.org/Toilal/rebulk
+    :target: http://travis-ci.org/Toilal/rebulk?branch=master
     :alt: Build Status
 
 .. image:: http://img.shields.io/coveralls/Toilal/rebulk.svg
@@ -23,6 +23,8 @@ ReBulk is a python library that performs advanced searches in strings that would
 It includes some features like ``Patterns``, ``Match``, ``Processor`` and ``Rule`` that allows developers to build a
 custom and complex string matcher using a readable and extendable API.
 
+This project is hosted on GitHub: `<https://github.com/Toilal/rebulk>`_
+
 Install
 -------
 .. code-block:: sh
@@ -188,6 +190,10 @@ All patterns have options that can be given as keyword arguments.
 
   Override value property for generated ``Match`` objects.
 
+- ``children``
+
+  If ``True``, all children ``Match`` objects will be retrieved instead of a single parent ``Match`` object.
+
 - ``private``
 
   If ``True``, ``Match`` objects generated from this pattern is available internally only. They will be removed at
@@ -229,6 +235,16 @@ and all subgroups (1, 2, ... n) will be converted to ``children`` matches of the
     'two = 2'
     'three = 3'
 
+It's possible to retrieve only children by using ``children`` parameters.
+
+.. code-block:: python
+
+    >>> matches = Rebulk() \
+    ...         .regex(r"One, (?P<one>\w+), Two, (?P<two>\w+), Three, (?P<three>\w+)", children=True) \
+    ...         .matches("Zero, 0, One, 1, Two, 2, Three, 3, Four, 4")
+    >>> matches
+    [<1:(14, 15)>, <2:(22, 23)>, <3:(32, 33)>]
+
 
 Matches
 -------

rebulk/pattern.py

@@ -27,7 +27,8 @@ class Pattern(object):
     Definition of a particular pattern to search for.
     """
 
-    def __init__(self, name=None, tags=None, formatter=None, validator=None, private=False, marker=False):
+    def __init__(self, name=None, tags=None, formatter=None, validator=None, children=False, private=False,
+                 marker=False):
         """
         :param name: Name of this pattern
         :type name: str
@@ -40,6 +41,8 @@ def __init__(self, name=None, tags=None, formatter=None, validator=None, private
         :param validator: dict (name, func) of validator to use with this pattern. name is the match name to support,
         and func a function(match) that returns the a boolean. A single validator function can also be
         passed as a shortcut for {None: validator}. If return value is False, match will be ignored.
+        :param children: generates children instead of parent
+        :type children: bool
         :param private: flag this pattern as beeing private.
         :type private: bool
         :param marker: flag this pattern as beeing a marker.
@@ -52,6 +55,7 @@ def __init__(self, name=None, tags=None, formatter=None, validator=None, private
         self.formatters = ensure_dict(formatter, self._default_formatter)
         self._default_validator = lambda match: True
         self.validators = ensure_dict(validator, self._default_validator)
+        self.children = children
         self.private = private
         self.marker = marker
 
@@ -86,7 +90,11 @@ def matches(self, input_string):
                         validated = False
                         break
                 if validated:
-                    yield match
+                    if self.children and match.children:
+                        for child in match.children:
+                            yield child
+                    else:
+                        yield match
 
     @abstractproperty
     def patterns(self):  # pragma: no cover

rebulk/test/test_pattern.py

@@ -206,6 +206,25 @@ def test_named_groups(self):
         assert group2.value == "violin"
         assert group2.parent == parent
 
+    def test_children(self):
+        pattern = RePattern(r"(?P<param1>Celt.?c)\s+(?P<param2>\w+)", label="test", children=True)
+
+        matches = list(pattern.matches(self.input_string))
+        assert len(matches) == 2
+        group1, group2 = matches
+
+        assert isinstance(group1, Match)
+        assert group1.pattern == pattern
+        assert group1.span == (28, 34)
+        assert group1.name == "param1"
+        assert group1.value == "Celtic"
+
+        assert isinstance(group2, Match)
+        assert group2.pattern == pattern
+        assert group2.span == (35, 41)
+        assert group2.name == "param2"
+        assert group2.value == "violin"
+
     def test_matches_kwargs(self):
         pattern = RePattern("He.rew", name="test", value="HE")
         matches = list(pattern.matches(self.input_string))