home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / !Python / Lib / Lib2 / py / AST < prev    next >
Encoding:
Text File  |  1996-08-21  |  6.6 KB  |  242 lines
  1. """Object-oriented interface to the parser module.
  2.  
  3. This module exports four classes which together provide an interface
  4. to the parser module.  Together, the three classes represent two ways
  5. to create parsed representations of Python source and the two starting
  6. data types (source text and tuple representations).  Each class
  7. provides interfaces which are identical other than the constructors.
  8. The constructors are described in detail in the documentation for each
  9. class and the remaining, shared portion of the interface is documented
  10. below.  Briefly, the classes provided are:
  11.  
  12. AST
  13.     Defines the primary interface to the AST objects and supports creation
  14.     from the tuple representation of the parse tree.
  15.  
  16. ExpressionAST
  17.     Supports creation of expression constructs from source text.
  18.  
  19. SuiteAST
  20.     Supports creation of statement suites from source text.
  21.  
  22. FileSuiteAST
  23.     Convenience subclass of the `SuiteAST' class; loads source text of the
  24.     suite from an external file.
  25.  
  26. Common Methods
  27. --------------
  28.  
  29. Aside from the constructors, several methods are provided to allow
  30. access to the various interpretations of the parse tree and to check
  31. conditions of the construct represented by the parse tree.
  32.  
  33. ast()
  34.     Returns the corresponding `parser.ASTType' object.
  35.  
  36. code()
  37.     Returns the compiled code object.
  38.  
  39. filename()
  40.     Returns the name of the associated source file, if known.
  41.  
  42. isExpression()
  43.     Returns true value if parse tree represents an expression, or a false
  44.     value otherwise.
  45.  
  46. isSuite()
  47.     Returns true value if parse tree represents a suite of statements, or
  48.     a false value otherwise.
  49.  
  50. text()
  51.     Returns the source text, or None if not available.
  52.  
  53. tuple()
  54.     Returns the tuple representing the parse tree.
  55. """
  56.  
  57. __version__ = '$Revision: 1.2 $'
  58. __copyright__ = """Copyright (c) 1995, 1996 by Fred L. Drake, Jr.
  59.  
  60. This software may be used and distributed freely for any purpose provided
  61. that this notice is included unchanged on any and all copies.  The author
  62. does not warrant or guarantee this software in any way.
  63. """
  64.  
  65. class AST:
  66.     """Base class for Abstract Syntax Tree objects.
  67.  
  68.     Creates an Abstract Syntax Tree based on the tuple representation
  69.     of the parse tree.  The parse tree can represent either an
  70.     expression or a suite; which will be recognized automatically.
  71.     This base class provides all of the query methods for subclass
  72.     objects defined in this module.
  73.     """
  74.     import parser            # import internally to avoid
  75.     _p = parser                # namespace pollution at the
  76.                     # top level
  77.     _text = None
  78.     _code = None
  79.     _ast  = None
  80.     _type = 'unknown'
  81.     _tupl = None
  82.  
  83.     def __init__(self, tuple):
  84.     """Create an `AST' instance from a tuple-tree representation.
  85.  
  86.     tuple
  87.         The tuple tree to convert.
  88.  
  89.     The tuple-tree may represent either an expression or a suite; the
  90.     type will be determined automatically.  Line number information may
  91.     optionally be present for any subset of the terminal tokens.
  92.     """
  93.     if type(tuple) is not type(()):
  94.         raise TypeError, 'Base AST class requires tuple parameter.'
  95.  
  96.     self._tupl = tuple
  97.     self._ast  = self._p.tuple2ast(tuple)
  98.     self._type = (self._p.isexpr(self._ast) and 'expression') or 'suite'
  99.  
  100.     def list(self, line_info = 0):
  101.     """Returns a fresh list representing the parse tree.
  102.  
  103.     line_info
  104.         If true, includes line number information for terminal tokens in
  105.         the output data structure,
  106.     """
  107.     return self._p.ast2list(self._ast, line_info)
  108.  
  109.     def tuple(self, line_info = 0):
  110.     """Returns the tuple representing the parse tree.
  111.  
  112.     line_info
  113.         If true, includes line number information for terminal tokens in
  114.         the output data structure,
  115.     """
  116.     if self._tupl is None:
  117.         self._tupl = self._p.ast2tuple(self._ast, line_info)
  118.     return self._tupl
  119.  
  120.     def code(self):
  121.     """Returns the compiled code object.
  122.  
  123.     The code object returned by this method may be passed to the
  124.     exec statement if `AST.isSuite()' is true or to the eval()
  125.     function if `AST.isExpression()' is true.  All the usual rules
  126.     regarding execution of code objects apply.
  127.     """
  128.     if not self._code:
  129.         self._code = self._p.compileast(self._ast)
  130.     return self._code
  131.  
  132.     def ast(self):
  133.     """Returns the corresponding `parser.ASTType' object.
  134.     """
  135.     return self._ast
  136.  
  137.     def filename(self):
  138.     """Returns the name of the source file if known, or None.
  139.     """
  140.     return None
  141.  
  142.     def text(self):
  143.     """Returns the source text, or None if not available.
  144.  
  145.     If the instance is of class `AST', None is returned since no
  146.     source text is available.  If of class `ExpressionAST' or
  147.     `SuiteAST', the source text passed to the constructor is
  148.     returned.
  149.     """
  150.     return self._text
  151.  
  152.     def isSuite(self):
  153.     """Determine if `AST' instance represents a suite of statements.
  154.     """
  155.     return self._type == 'suite'
  156.  
  157.     def isExpression(self):
  158.     """Determine if `AST' instance represents an expression.
  159.     """
  160.     return self._type == 'expression'
  161.  
  162.  
  163.  
  164. class SuiteAST(AST):
  165.     """Statement suite parse tree representation.
  166.  
  167.     This subclass of the `AST' base class represents statement suites
  168.     parsed from the source text of a Python suite.  If the source text
  169.     does not represent a parsable suite of statements, the appropriate
  170.     exception is raised by the parser.
  171.     """
  172.     _type = 'suite'
  173.  
  174.     def __init__(self, text):
  175.     """Initialize a `SuiteAST' from source text.
  176.  
  177.     text
  178.         Source text to parse.
  179.     """
  180.     if type(text) is not type(''):
  181.         raise TypeError, 'SuiteAST requires source text parameter.'
  182.     self._text = text
  183.     self._ast  = self._p.suite(text)
  184.  
  185.     def isSuite(self):
  186.     return 1
  187.  
  188.     def isExpression(self):
  189.     return 0
  190.  
  191.  
  192. class FileSuiteAST(SuiteAST):
  193.     """Representation of a python source file syntax tree.
  194.  
  195.     This provides a convenience wrapper around the `SuiteAST' class to
  196.     load the source text from an external file.
  197.     """
  198.     def __init__(self, fileName):
  199.     """Initialize a `SuiteAST' from a source file.
  200.  
  201.     fileName
  202.         Name of the external source file.
  203.     """
  204.     self._fileName = fileName
  205.     SuiteAST.__init__(self, open(fileName).read())
  206.  
  207.     def filename(self):
  208.     return self._fileName
  209.  
  210.  
  211.  
  212. class ExpressionAST(AST):
  213.     """Expression parse tree representation.
  214.  
  215.     This subclass of the `AST' base class represents expression
  216.     constructs parsed from the source text of a Python expression.  If
  217.     the source text does not represent a parsable expression, the
  218.     appropriate exception is raised by the Python parser.
  219.     """
  220.     _type = 'expression'
  221.  
  222.     def __init__(self, text):
  223.     """Initialize an expression AST from source text.
  224.  
  225.     text
  226.         Source text to parse.
  227.     """
  228.     if type(text) is not type(''):
  229.         raise TypeError, 'ExpressionAST requires source text parameter.'
  230.     self._text = text
  231.     self._ast  = self._p.expr(text)
  232.  
  233.     def isSuite(self):
  234.     return 0
  235.  
  236.     def isExpression(self):
  237.     return 1
  238.  
  239.  
  240. #
  241. #  end of file
  242.