because parsing is performed in a manner identical to the code
forming the application. It is also faster.
+The \module{parser} module was written and documented by Fred
+L. Drake, Jr. (\email{fdrake@acm.org}).%
+\index{Drake, Fred L., Jr.}
+
There are a few things to note about this module which are important
to making use of the data structures created. This is not a tutorial
on editing the parse trees for Python code, but some examples of using
and compiled code objects, but there are also functions which serve to
query the type of parse tree represented by an AST object.
-\setindexsubitem{(in module parser)}
-
\subsection{Creating AST Objects}
\label{Creating ASTs}
be compiled into executable code objects. Parse trees may be
extracted with or without line numbering information.
-\begin{funcdesc}{ast2list}{ast\optional{, line_info\code{ = 0}}}
+\begin{funcdesc}{ast2list}{ast\optional{, line_info}}
This function accepts an AST object from the caller in
\code{\var{ast}} and returns a Python list representing the
equivelent parse tree. The resulting list representation can be used
omitted if the flag is false or omitted.
\end{funcdesc}
-\begin{funcdesc}{ast2tuple}{ast\optional{, line_info\code{ = 0}}}
+\begin{funcdesc}{ast2tuple}{ast\optional{, line_info}}
This function accepts an AST object from the caller in
\code{\var{ast}} and returns a Python tuple representing the
equivelent parse tree. Other than returning a tuple instead of a
\label{Querying ASTs}
Two functions are provided which allow an application to determine if
-an AST was create as an expression or a suite. Neither of these
+an AST was created as an expression or a suite. Neither of these
functions can be used to determine if an AST was created from source
code via \function{expr()} or \function{suite()} or from a parse tree
via \function{sequence2ast()}.
>>> eval(code)
10
\end{verbatim}
-%
+
The equivelent operation using the \module{parser} module is somewhat
longer, and allows the intermediate internal parse tree to be retained
as an AST object:
>>> eval(code)
10
\end{verbatim}
-%
+
An application which needs both AST and code objects can package this
code into readily available functions:
code = parser.compileast(ast)
return ast, code
\end{verbatim}
-%
+
\subsubsection{Information Discovery}
Some applications benefit from direct access to the parse tree. The
"""Some documentation.
"""
\end{verbatim}
-%
+
Using the interpreter to take a look at the parse tree, we find a
bewildering mass of numbers and parentheses, with the documentation
buried deep in nested tuples.
(4, ''),
(0, ''))
\end{verbatim}
-%
+
The numbers at the first element of each node in the tree are the node
types; they map directly to terminal and non-terminal symbols in the
grammar. Unfortunately, they are represented as integers in the
break
return same, vars
\end{verbatim}
-%
+
Using this simple representation for syntactic variables and the symbolic
node types, the pattern for the candidate docstring subtrees becomes
fairly readable. (See file \file{example.py}.)
(token.NEWLINE, '')
))
\end{verbatim}
-%
+
Using the \function{match()} function with this pattern, extracting the
module docstring from the parse tree created previously is easy:
>>> vars
{'docstring': '"""Some documentation.\012"""'}
\end{verbatim}
-%
+
Once specific data can be extracted from a location where it is
expected, the question of where information can be expected
needs to be answered. When dealing with docstrings, the answer is
name = cstmt[2][1]
self._class_info[name] = ClassInfo(cstmt)
\end{verbatim}
-%
+
After initializing some internal state, the constructor calls the
\method{_extract_info()} method. This method performs the bulk of the
information extraction which takes place in the entire example. The
\begin{verbatim}
def square(x): "Square an argument."; return x ** 2
\end{verbatim}
-%
+
while the long form uses an indented block and allows nested
definitions:
return x ** y
return raiser
\end{verbatim}
-%
+
When the short form is used, the code block may contain a docstring as
the first, and possibly only, \constant{small_stmt} element. The
extraction of such a docstring is slightly different and requires only
tup = parser.ast2tuple(ast)
return ModuleInfo(tup, basename)
\end{verbatim}
-%
+
This provides an easy-to-use interface to the documentation of a
module. If information is required which is not extracted by the code
of this example, the code may be extended at clearly defined points to
\begin{seealso}
-\seemodule{symbol}{
- useful constants representing internal nodes of the parse tree}
+\seemodule{symbol}
+ {useful constants representing internal nodes of the parse tree}
-\seemodule{token}{
- useful constants representing leaf nodes of the parse tree and
- functions for testing node values}
+\seemodule{token}
+ {useful constants representing leaf nodes of the parse tree and
+ functions for testing node values}
\end{seealso}
because parsing is performed in a manner identical to the code
forming the application. It is also faster.
+The \module{parser} module was written and documented by Fred
+L. Drake, Jr. (\email{fdrake@acm.org}).%
+\index{Drake, Fred L., Jr.}
+
There are a few things to note about this module which are important
to making use of the data structures created. This is not a tutorial
on editing the parse trees for Python code, but some examples of using
and compiled code objects, but there are also functions which serve to
query the type of parse tree represented by an AST object.
-\setindexsubitem{(in module parser)}
-
\subsection{Creating AST Objects}
\label{Creating ASTs}
be compiled into executable code objects. Parse trees may be
extracted with or without line numbering information.
-\begin{funcdesc}{ast2list}{ast\optional{, line_info\code{ = 0}}}
+\begin{funcdesc}{ast2list}{ast\optional{, line_info}}
This function accepts an AST object from the caller in
\code{\var{ast}} and returns a Python list representing the
equivelent parse tree. The resulting list representation can be used
omitted if the flag is false or omitted.
\end{funcdesc}
-\begin{funcdesc}{ast2tuple}{ast\optional{, line_info\code{ = 0}}}
+\begin{funcdesc}{ast2tuple}{ast\optional{, line_info}}
This function accepts an AST object from the caller in
\code{\var{ast}} and returns a Python tuple representing the
equivelent parse tree. Other than returning a tuple instead of a
\label{Querying ASTs}
Two functions are provided which allow an application to determine if
-an AST was create as an expression or a suite. Neither of these
+an AST was created as an expression or a suite. Neither of these
functions can be used to determine if an AST was created from source
code via \function{expr()} or \function{suite()} or from a parse tree
via \function{sequence2ast()}.
>>> eval(code)
10
\end{verbatim}
-%
+
The equivelent operation using the \module{parser} module is somewhat
longer, and allows the intermediate internal parse tree to be retained
as an AST object:
>>> eval(code)
10
\end{verbatim}
-%
+
An application which needs both AST and code objects can package this
code into readily available functions:
code = parser.compileast(ast)
return ast, code
\end{verbatim}
-%
+
\subsubsection{Information Discovery}
Some applications benefit from direct access to the parse tree. The
"""Some documentation.
"""
\end{verbatim}
-%
+
Using the interpreter to take a look at the parse tree, we find a
bewildering mass of numbers and parentheses, with the documentation
buried deep in nested tuples.
(4, ''),
(0, ''))
\end{verbatim}
-%
+
The numbers at the first element of each node in the tree are the node
types; they map directly to terminal and non-terminal symbols in the
grammar. Unfortunately, they are represented as integers in the
break
return same, vars
\end{verbatim}
-%
+
Using this simple representation for syntactic variables and the symbolic
node types, the pattern for the candidate docstring subtrees becomes
fairly readable. (See file \file{example.py}.)
(token.NEWLINE, '')
))
\end{verbatim}
-%
+
Using the \function{match()} function with this pattern, extracting the
module docstring from the parse tree created previously is easy:
>>> vars
{'docstring': '"""Some documentation.\012"""'}
\end{verbatim}
-%
+
Once specific data can be extracted from a location where it is
expected, the question of where information can be expected
needs to be answered. When dealing with docstrings, the answer is
name = cstmt[2][1]
self._class_info[name] = ClassInfo(cstmt)
\end{verbatim}
-%
+
After initializing some internal state, the constructor calls the
\method{_extract_info()} method. This method performs the bulk of the
information extraction which takes place in the entire example. The
\begin{verbatim}
def square(x): "Square an argument."; return x ** 2
\end{verbatim}
-%
+
while the long form uses an indented block and allows nested
definitions:
return x ** y
return raiser
\end{verbatim}
-%
+
When the short form is used, the code block may contain a docstring as
the first, and possibly only, \constant{small_stmt} element. The
extraction of such a docstring is slightly different and requires only
tup = parser.ast2tuple(ast)
return ModuleInfo(tup, basename)
\end{verbatim}
-%
+
This provides an easy-to-use interface to the documentation of a
module. If information is required which is not extracted by the code
of this example, the code may be extended at clearly defined points to
\begin{seealso}
-\seemodule{symbol}{
- useful constants representing internal nodes of the parse tree}
+\seemodule{symbol}
+ {useful constants representing internal nodes of the parse tree}
-\seemodule{token}{
- useful constants representing leaf nodes of the parse tree and
- functions for testing node values}
+\seemodule{token}
+ {useful constants representing leaf nodes of the parse tree and
+ functions for testing node values}
\end{seealso}
projects / python / commitdiff