Diff of /doc/source/using_pyke/other_functions.txt [000000] .. [4dca5a]  Maximize  Restore

Switch to side-by-side view

--- a
+++ b/doc/source/using_pyke/other_functions.txt
@@ -0,0 +1,173 @@
+.. $Id$
+.. 
+.. Copyright Š 2007-2010 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: Other functions
+    page-description:
+        Other miscellaneous functions available that you might be interested
+        in.
+    /description
+    format: rest
+    encoding: utf8
+    output-encoding: utf8
+    include: yes
+    initialheaderlevel: 2
+/restindex
+
+uservalues
+    filedate: $Id$
+/uservalues
+
+===============
+Other Functions
+===============
+
+Running and Pickling Plans
+==========================
+
+.. this code is hidden and will set __file__ to the doc/examples directory.
+   >>> import os
+   >>> __file__ = \
+   ...   os.path.join(os.path.dirname(os.path.dirname(os.getcwd())),
+   ...                'examples')
+   >>> from pyke import knowledge_engine
+   >>> my_engine = knowledge_engine.engine(__file__)
+   >>> my_engine.add_universal_fact('family', 'son_of', ('bruce', 'thomas'))
+   >>> my_engine.add_universal_fact('family', 'son_of', ('david', 'bruce'))
+   >>> my_engine.activate('bc_related0')
+
+Once you've obtained a plan_ from `prove_goal`_ or `prove_1_goal`_, you just
+call it like a normal Python function.  The arguments required are simply those
+specified, if any, in the `taking clause`_ of the rule__ proving the top-level
+goal.
+
+You may call the plan function any number of times.  You may even pickle
+the plan for later use.  But the plans are constructed out of
+`functools.partial`_ functions, that need to be registered with copy_reg_
+if you are running Python 2.x:
+
+    >>> import copy_reg
+    >>> import functools
+    >>> copy_reg.pickle(functools.partial,
+    ...                 lambda p: (functools.partial, (p.func,) + p.args))
+
+No special code is required to unpickle a plan.  Just unpickle and call it.
+(Unpickling the plan only imports one small Pyke module to be able to run
+the plan).
+
+.. __: ../pyke_syntax/krb_syntax/bc_rule.html
+
+
+Tracing Rules
+=============
+
+Individual rules may be traced to aid in debugging.  The ``trace`` function
+takes two arguments: the rule base name, and the name of the rule to trace:
+
+    >>> my_engine.trace('bc_related0', 'grand_father_son')
+    >>> my_engine.prove_1_goal('bc_related0.father_son(thomas, david, $depth)')
+    bc_related0.grand_father_son('thomas', 'david', '$depth')
+    bc_related0.grand_father_son succeeded with ('thomas', 'david', ('grand',))
+    ({'depth': ('grand',)}, None)
+
+This can be done either before or after rule base activation and will remain
+in effect until you call ``untrace``:
+
+    >>> my_engine.untrace('bc_related0', 'grand_father_son')
+    >>> my_engine.prove_1_goal('bc_related0.father_son(thomas, david, $depth)')
+    ({'depth': ('grand',)}, None)
+
+
+Krb_traceback
+=============
+
+A handy traceback module is provided to convert Python functions, lines and
+line numbers to the `.krb file`_ rule names, lines and line numbers in a
+Python traceback.  This makes it much easier to read the tracebacks that occur
+during proofs.
+
+The ``krb_traceback`` module has exactly the same functions as the standard
+Python traceback_ module, but they convert the generated Python function
+information into .krb file information.  They also delete the intervening
+Python functions between subgoal proofs.
+
+    >>> import sys
+    >>> from pyke import knowledge_engine
+    >>> from pyke import krb_traceback
+    >>>
+    >>> my_engine = knowledge_engine.engine(__file__)
+    >>> my_engine.activate('error_test')
+    >>> try:                                            # doctest: +ELLIPSIS
+    ...     my_engine.prove_1_goal('error_test.goal()')
+    ... except:
+    ...     krb_traceback.print_exc(None, sys.stdout)   # sys.stdout needed for doctest
+    Traceback (most recent call last):
+      File "<doctest other_functions.txt[19]>", line 2, in <module>
+        my_engine.prove_1_goal('error_test.goal()')
+      File "...knowledge_engine.py", line 359, in prove_1_goal
+        return goal.compile(goal_str).prove_1(self, **args)
+      File "...goal.py", line 47, in prove_1
+        return iter(it).next()
+      File "...rule_base.py", line 50, in next
+        return self.iterator.next()
+      File "...knowledge_engine.py", line 41, in from_iterable
+        for x in iterable: yield x
+      File "...knowledge_engine.py", line 41, in from_iterable
+        for x in iterable: yield x
+      File "...error_test.krb", line 26, in rule1
+        goal2()
+      File "...error_test.krb", line 31, in rule2
+        goal3()
+      File "...error_test.krb", line 36, in rule3
+        goal4()
+      File "...error_test.krb", line 41, in rule4
+        check $bar > 0
+      File "...contexts.py", line 231, in lookup_data
+        raise KeyError("$%s not bound" % var_name)
+    KeyError: '$bar not bound'
+
+
+Miscellaneous
+=============
+
+There are a few more functions that may be useful in special situations.
+
+*some_engine*.add_case_specific_fact(kb_name, fact_name, args)
+    This is an alternate to the ``assert_`` function.
+*some_engine*.get_kb(kb_name)
+    Finds and returns the `knowledge base`_ by the name ``kb_name``.  Raises
+    ``KeyError`` if not found.  Note that for `rule bases`_, this returns the
+    active `rule base`_ where ``kb_name`` is the `rule base category`_ name.
+    Thus, not all `rule bases`_ are accessible through this call.
+*some_engine*.get_rb(rb_name)
+    Finds and returns the `rule base`_ by the name ``rb_name``.  Raises
+    ``KeyError`` if not found.  This works for any `rule base`_, whether it
+    is active_ or not.
+*some_engine*.print_stats([f = sys.stdout])
+    Prints a brief set of statistics for each knowledge base to file ``f``.
+    These are reset by the ``reset`` function.  This will show how many facts
+    were asserted, and counts of how many forward-chaining rules were fired
+    and rerun, as well as counts of how many backward-chaining goals were
+    tried, and how many backward-chaining rules matched, succeeded and failed.
+    Note that one backward-chaining rule may succeed many times through
+    backtracking.
+

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

JavaScript is required for this form.





No, thanks