Merge pull request #1 from BinaryAnalysisPlatform/new-python-interface

introducing new python interface

Author: ivg

setup.py

@@ -7,5 +7,7 @@
     version = '1.0.0~alpha',
     package_dir = {'bap' : 'src'},
     packages = ['bap'],
-    install_requires = ['requests']
+    extras_require = {
+        'rpc' : ['requests']
+    }
 )

src/__init__.py

@@ -1,5 +1,43 @@
 r"""Python inteface to BAP.
 
+
+Porcelain Interace
+==================
+
+The high level interface allows to run ``bap`` and get back the information
+that we were able to infer from the file. It consists only from one function,
+``bap.run``, that will drive ``bap`` for you. It is quite versatile, so read the
+documentation for the further information.
+
+
+Example
+-------
+
+>>> import bap
+>>> proj = bap.run('/bin/true', ['--symbolizer=ida'])
+>>> text = proj.sections['.text']
+>>> main = proj.program.subs.find('main')
+>>> entry = main.blks[0]
+>>> next = main.blks.find(entry.jmps[0].target.arg)
+
+It is recommended to explore the interface using ipython or similiar
+interactive toplevels.
+
+We use ADT syntax to communicate with python. It is a syntactical
+subset of Python grammar, so in fact, bap just returns a valid Python
+program, that is then evaluated. The ADT stands for Algebraic Data
+Type, and is described in ``adt`` module. For non-trivial tasks one
+should consider using ``adt.Visitor`` class.
+
+
+
+Plumbing interface [rpc]
+========================
+
+The low level interface provides an access to internal services. It
+uses ``bap-server``, and talks with bap using RPC protocol. It is in
+extras section and must be installed explicitly with ``[rpc]`` tag.
+
 In a few keystrokes:
 
     >>> import bap
@@ -23,7 +61,7 @@
 #. ``image``  loads given file
 
 Disassembling things
-====================
+--------------------
 
 ``disasm`` is a swiss knife for disassembling things. It takes either a
 string object, or something returned by an ``image`` function, e.g.,
@@ -56,7 +94,7 @@
 that is instance of one of this kind, it will stop.
 
 Reading files
-=============
+-------------
 
 To read and analyze file one should load it with ``image``
 function. This function  returns an instance of class ``Image`` that
@@ -99,6 +137,10 @@
 
 Where data is actual string of bytes.
 """
-__all__ = ['disasm', 'image', 'adt', 'asm', 'arm', 'bil']
 
-from .bap import disasm, image
+from .bap import run
+
+try :
+    from .rpc import disasm, image
+except ImportError:
+    pass

src/adt.py

@@ -3,11 +3,11 @@
 Algebraic Data Types (ADT) is used to represent two kinds of things:
 
 1. A discrimintated union of types, called sum
-2. A combination of some types, called product.
+2. A combination of ADT types, called product.
 
 # Sum types
 
-Sum types represents a concept of generalizing. For example,
+Sum types represent a concept of generalizing. For example,
 on ARM R0 and R1 are all general purpose registers (GPR). Also on ARM
 we have Condition Code registers (CCR) :
 
@@ -48,10 +48,10 @@ class ADT(object):
     """ Algebraic Data Type.
 
     This is a base class for all ADTs. ADT represented by a tuple of arguments,
-    stored in a val field. Arguments should be instances of ADT class, or numbers,
+    stored in a `arg` field. Arguments should be instances of ADT class, or numbers,
     or strings. Empty set of arguments is permitted.
     A one-tuple is automatically untupled, i.e., `Int(12)` has value `12`, not `(12,)`.
-    For convenience, a name of the constructor is provided in `name` field.
+    A name of the constructor is stored in the `constr` field
 
     A structural comparison is provided.
 
@@ -115,7 +115,7 @@ def run(self, adt):
 
         Otherwise, for an ADT of type C the method `visit_C` is looked up in the
         visitors methods dictionary. If it doesn't exist, then `visit_B` is
-        looked up, where `D` is the base class of `C`. The process continues,
+        looked up, where `B` is the base class of `C`. The process continues,
         until the method is found. This is guaranteed to terminate,
         since visit_ADT method is defined.
 
@@ -124,8 +124,8 @@ def run(self, adt):
         Once the method is found it is called. It is the method's responsiblity
         to recurse into sub-elements, e.g., call run method.
 
-        For example, suppose that we want to count negative values in a given
-        BIL expression:
+        For example, suppose that we want to count negative values in
+        some BIL expression:
 
         class CountNegatives(Visitor):
             def __init__(self):
@@ -148,7 +148,7 @@ def visit_NEG(self, op):
         visit_Int for Int constructor and visit_NEG for counting unary minuses.
         (Actually we should count for bitwise NOT operation also, since it will
         change the sign bit also, but lets forget about it for the matter of the
-        excercise (and it can be easily fixed just by matching visit_UnOp)).
+        exercise (and it can be easily fixed just by matching visit_UnOp)).
 
         When we hit visit_NEG we toggle current sign, storing its previous value
         and recurse into the operand. After we return from the recursion, we restore