Markup nits.
Adjust examples to use the object interface instead of the function
interface.
diff --git a/Doc/lib/libparser.tex b/Doc/lib/libparser.tex
index 7d6cff6..d1595d2 100644
--- a/Doc/lib/libparser.tex
+++ b/Doc/lib/libparser.tex
@@ -10,7 +10,7 @@
%
\section{\module{parser} ---
- Access parse trees for Python code}
+ Access Python parse trees}
\declaremodule{builtin}{parser}
\modulesynopsis{Access parse trees for Python source code.}
@@ -67,7 +67,7 @@
\keyword{if} in an \constant{if_stmt}, are included in the node tree without
any special treatment. For example, the \keyword{if} keyword is
represented by the tuple \code{(1, 'if')}, where \code{1} is the
-numeric value associated with all \code{NAME} tokens, including
+numeric value associated with all \constant{NAME} tokens, including
variable and function names defined by the user. In an alternate form
returned when line number information is requested, the same token
might be represented as \code{(1, 'if', 12)}, where the \code{12}
@@ -104,15 +104,14 @@
\end{seealso}
-\subsection{Creating AST Objects}
-\label{Creating ASTs}
+\subsection{Creating AST Objects \label{Creating ASTs}}
AST objects may be created from source code or from a parse tree.
When creating an AST object from source, different functions are used
to create the \code{'eval'} and \code{'exec'} forms.
\begin{funcdesc}{expr}{string}
-The \function{expr()} function parses the parameter \code{\var{string}}
+The \function{expr()} function parses the parameter \var{string}
as if it were an input to \samp{compile(\var{string}, 'eval')}. If
the parse succeeds, an AST object is created to hold the internal
parse tree representation, otherwise an appropriate exception is
@@ -120,7 +119,7 @@
\end{funcdesc}
\begin{funcdesc}{suite}{string}
-The \function{suite()} function parses the parameter \code{\var{string}}
+The \function{suite()} function parses the parameter \var{string}
as if it were an input to \samp{compile(\var{string}, 'exec')}. If
the parse succeeds, an AST object is created to hold the internal
parse tree representation, otherwise an appropriate exception is
@@ -157,8 +156,7 @@
\end{funcdesc}
-\subsection{Converting AST Objects}
-\label{Converting ASTs}
+\subsection{Converting AST Objects \label{Converting ASTs}}
AST objects, regardless of the input used to create them, may be
converted to parse trees represented as list- or tuple- trees, or may
@@ -167,7 +165,7 @@
\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
+\var{ast} and returns a Python list representing the
equivelent parse tree. The resulting list representation can be used
for inspection or the creation of a new parse tree in list form. This
function does not fail so long as memory is available to build the
@@ -177,7 +175,7 @@
required, this function is significantly faster than retrieving a
tuple representation and converting that to nested lists.
-If \code{\var{line_info}} is true, line number information will be
+If \var{line_info} is true, line number information will be
included for all terminal tokens as a third element of the list
representing the token. Note that the line number provided specifies
the line on which the token \emph{ends}. This information is
@@ -186,11 +184,11 @@
\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
+\var{ast} and returns a Python tuple representing the
equivelent parse tree. Other than returning a tuple instead of a
list, this function is identical to \function{ast2list()}.
-If \code{\var{line_info}} is true, line number information will be
+If \var{line_info} is true, line number information will be
included for all terminal tokens as a third element of the list
representing the token. This information is omitted if the flag is
false or omitted.
@@ -198,12 +196,12 @@
\begin{funcdesc}{compileast}{ast\optional{, filename\code{ = '<ast>'}}}
The Python byte compiler can be invoked on an AST object to produce
-code objects which can be used as part of an \code{exec} statement or
+code objects which can be used as part of an \keyword{exec} statement or
a call to the built-in \function{eval()}\bifuncindex{eval} function.
This function provides the interface to the compiler, passing the
-internal parse tree from \code{\var{ast}} to the parser, using the
-source file name specified by the \code{\var{filename}} parameter.
-The default value supplied for \code{\var{filename}} indicates that
+internal parse tree from \var{ast} to the parser, using the
+source file name specified by the \var{filename} parameter.
+The default value supplied for \var{filename} indicates that
the source was an AST object.
Compiling an AST object may result in exceptions related to
@@ -218,8 +216,7 @@
\end{funcdesc}
-\subsection{Queries on AST Objects}
-\label{Querying ASTs}
+\subsection{Queries on AST Objects \label{Querying ASTs}}
Two functions are provided which allow an application to determine if
an AST was created as an expression or a suite. Neither of these
@@ -228,7 +225,7 @@
via \function{sequence2ast()}.
\begin{funcdesc}{isexpr}{ast}
-When \code{\var{ast}} represents an \code{'eval'} form, this function
+When \var{ast} represents an \code{'eval'} form, this function
returns true, otherwise it returns false. This is useful, since code
objects normally cannot be queried for this information using existing
built-in functions. Note that the code objects created by
@@ -247,8 +244,7 @@
\end{funcdesc}
-\subsection{Exceptions and Error Handling}
-\label{AST Errors}
+\subsection{Exceptions and Error Handling \label{AST Errors}}
The parser module defines a single exception, but may also pass other
built-in exceptions from other portions of the Python runtime
@@ -276,8 +272,7 @@
to the descriptions of each function for detailed information.
-\subsection{AST Objects}
-\label{AST Objects}
+\subsection{AST Objects \label{AST Objects}}
AST objects returned by \function{expr()}, \function{suite()} and
\function{sequence2ast()} have no methods of their own.
@@ -316,8 +311,7 @@
\end{methoddesc}
-\subsection{Examples}
-\nodename{AST Examples}
+\subsection{Examples \label{AST Examples}}
The parser modules allows operations to be performed on the parse tree
of Python source code before the bytecode is generated, and provides
@@ -348,7 +342,7 @@
\begin{verbatim}
>>> import parser
>>> ast = parser.expr('a + 5')
->>> code = parser.compileast(ast)
+>>> code = ast.compile()
>>> a = 5
>>> eval(code)
10
@@ -362,23 +356,22 @@
def load_suite(source_string):
ast = parser.suite(source_string)
- code = parser.compileast(ast)
- return ast, code
+ return ast, ast.compile()
def load_expression(source_string):
ast = parser.expr(source_string)
- code = parser.compileast(ast)
- return ast, code
+ return ast, ast.compile()
\end{verbatim}
\subsubsection{Information Discovery}
Some applications benefit from direct access to the parse tree. The
remainder of this section demonstrates how the parse tree provides
-access to module documentation defined in docstrings without requiring
-that the code being examined be loaded into a running interpreter via
-\keyword{import}. This can be very useful for performing analyses of
-untrusted code.
+access to module documentation defined in
+docstrings\index{string!documentation}\index{docstrings} without
+requiring that the code being examined be loaded into a running
+interpreter via \keyword{import}. This can be very useful for
+performing analyses of untrusted code.
Generally, the example will demonstrate how the parse tree may be
traversed to distill interesting information. Two functions and a set
@@ -398,7 +391,7 @@
definitions that will be considered are those which are defined in the
top level of their context, e.g., a function defined by a \keyword{def}
statement at column zero of a module, but not a function defined
-within a branch of an \code{if} ... \code{else} construct, though
+within a branch of an \keyword{if} ... \keyword{else} construct, though
there are some good reasons for doing so in some situations. Nesting
of definitions will be handled by the code developed in the example.
@@ -425,7 +418,7 @@
>>> import parser
>>> import pprint
>>> ast = parser.suite(open('docstring.py').read())
->>> tup = parser.ast2tuple(ast)
+>>> tup = ast.totuple()
>>> pprint.pprint(tup)
(257,
(264,
@@ -709,13 +702,13 @@
\begin{verbatim}
def get_docs(fileName):
- source = open(fileName).read()
import os
- basename = os.path.basename(os.path.splitext(fileName)[0])
import parser
+
+ source = open(fileName).read()
+ basename = os.path.basename(os.path.splitext(fileName)[0])
ast = parser.suite(source)
- tup = parser.ast2tuple(ast)
- return ModuleInfo(tup, basename)
+ return ModuleInfo(ast.totuple(), basename)
\end{verbatim}
This provides an easy-to-use interface to the documentation of a