Source code for fbrelation.__init__

'''
**fbrelation**
    by Alex Forsythe <awforsythe@gmail.com> <http://awforsythe.com>

Defines an interpreter for a small declarative language used to define
MotionBuilder relation constraints. In this language, a program consists of a
series of relation constraint declarations, each of which contains a series
of box and connection declarations, each on its own line.

Loading a relation constraint program takes place in three phases: parsing,
compilation, and execution.

1. The **parsing** phase constructs syntax objects from input text, using
   static methods defined in the respective classes of the syntax package.
   These methods may throw a :class:`.ParsingError` if they encounter malformed
   syntax.

2. The **compilation** phase turns syntax objects into declaration objects,
   using the compile method of the individual abstract syntax objects. These
   methods perform some static checking to ensure that the program is
   relatively sound; any errors will result in a :class:`.CompilationError`
   being thrown.

3. Finally, the **execution** phase constructs FBConstraintRelation objects
   from the compiled declarations. The execute methods of the declaration
   objects handle the instantiation and configuration of MotionBuilder objects,
   and they will throw an :class:`.ExecutionError` if they encounter runtime
   problems.
'''

from fbrelation.exceptions import RelationException

from fbrelation.syntax.program import ProgramSyntax as _ProgramSyntax

def loads(string):
    '''
    Parses, compiles, and executes the program from its provided source text.

    :returns: a dictionary mapping constraint declaration names to their
              corresponding FBConstraintRelation objects.
    :raises:  a :class:`.RelationException` if a program is invalid or
              unsupported.
    '''
    syntax = _ProgramSyntax.parse(string)
    declaration = syntax.compile()
    return declaration.execute()

def load(fp):
    '''
    Parses, compiles, and executes a program from the provided open file.

    :note:    Returns and raises identically to loads.
    '''
    return loads(fp.read())