fixes #49 - updated documentation for new yield_changed param on muta…

…te()

docs/source/fuzz.rst

@@ -7,6 +7,25 @@ Fuzzing
 With the addition of the :any:`pfp.fuzz` module, pfp now supports fuzzing
 out-of-the box! (w00t!).
 
+``pfp.fuzz.mutate()`` function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+pfp contains a :any:`pfp.fuzz.mutate` function that will mutate a provided
+field. The provided field will most likely just be the resulting dom from
+calling :any:`pfp.parse`.
+
+The :any:`pfp.fuzz.mutate` function accepts several arguments:
+
+* ``field`` - The field to fuzz. This does not have to be a :any:`pfp.fields.Dom`
+  object, although in the normal use case it will be.
+* ``strat_name_or_cls`` - The name (or direct class) of the :any:`StratGroup <pfp.fuzz.strats.StratGroup>` to use
+* ``num`` - The number of iterations to perform. Defaults to ``100``
+* ``at_once`` - The number of fields to fuzz at once. Defaults to ``1``
+* ``yield_changed`` - If true, the mutate generator will yield a tuple
+  of ``(mutated_dom,changed_fields)``, where changed_fields is a ``set`` (not a list) of the
+  fields that were changed. Also note that the yielded set of changed fields *can*
+  be modified and is no longer needed by the mutate function. Defaults to ``False``
+
 Strategies
 ^^^^^^^^^^
 
@@ -15,7 +34,7 @@ allowed me to pre-define various fuzzing strategies. This allows one to reuse, t
 existing, or create new strategies specific to each target or attack surface.
 
 StratGroup
------------
+----------
 
 pfp strategy groups are containers for sets of field-specific fuzzing strategies.
 :any:`StratGroups <pfp.fuzz.strats.StratGroup>` must define a

pfp/fuzz/__init__.py

@@ -41,7 +41,10 @@ def mutate(field, strat_name_or_cls, num=100, at_once=1, yield_changed=False):
     strategy specified with ``strat_name_or_class``, yielding ``num`` mutations
     that affect up to ``at_once`` fields at once.
 
-    This function will yield back the field after each mutation.
+    This function will yield back the field after each mutation, optionally
+    also yielding a ``set`` of fields that were mutated in that iteration (if ``yield_changed`` is
+    ``True``). It should also be noted that the yielded set of changed fields *can*
+    be modified and is no longer needed by the mutate() function.
 
     :param pfp.fields.Field field: The field to mutate (can be anything, not just Dom/Structs)
     :param strat_name_or_class: Can be the name of a strategy, or the actual strategy class (not an instance)

tests/test_fuzz.py

@@ -49,15 +49,15 @@ def test_fuzz_yield_fields(self):
         data = "abc"
         dom = pfp.parse(template=template, data=data)
 
-        for at_once in [0,1,2]:
+        for at_once in [1,2,3]:
             for mutated,changed_fields in pfp.fuzz.mutate(
                     dom,
                     "basic",
                     num           = 100,
                     at_once       = at_once,
                     yield_changed = True
                 ):
-                pass
+                self.assertEqual(len(changed_fields), at_once)
 
     # see #49 - make mutate return the changed fields
     def test_fuzz_yield_fields_no_yield(self):