summaryrefslogtreecommitdiffstats
path: root/Doc/libparser.tex
diff options
context:
space:
mode:
authorGuido van Rossum <guido@python.org>1997-07-17 16:34:52 (GMT)
committerGuido van Rossum <guido@python.org>1997-07-17 16:34:52 (GMT)
commite47da0ae04814fab2a0aa6e637de2e4269978017 (patch)
tree1360ad7010b92c02d287e79accc1415c77bedc3e /Doc/libparser.tex
parent3c2a056fdd3af1f3b94f134b0cab2bd8050c9703 (diff)
downloadcpython-e47da0ae04814fab2a0aa6e637de2e4269978017.zip
cpython-e47da0ae04814fab2a0aa6e637de2e4269978017.tar.gz
cpython-e47da0ae04814fab2a0aa6e637de2e4269978017.tar.bz2
AMK's megapatch:
* \bcode, \ecode added everywhere * \label{module-foo} added everywhere * A few \seealso sections added. * Indentation fixed inside verbatim in lib*tex files
Diffstat (limited to 'Doc/libparser.tex')
-rw-r--r--Doc/libparser.tex72
1 files changed, 36 insertions, 36 deletions
diff --git a/Doc/libparser.tex b/Doc/libparser.tex
index a51b01b..4503358 100644
--- a/Doc/libparser.tex
+++ b/Doc/libparser.tex
@@ -288,30 +288,30 @@ bytecode generation, the simplest operation is to do nothing. For
this purpose, using the \code{parser} module to produce an
intermediate data structure is equivelent to the code
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> code = compile('a + 5', 'eval')
>>> a = 5
>>> eval(code)
10
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The equivelent operation using the \code{parser} module is somewhat
longer, and allows the intermediate internal parse tree to be retained
as an AST object:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import parser
>>> ast = parser.expr('a + 5')
>>> code = parser.compileast(ast)
>>> a = 5
>>> eval(code)
10
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
An application which needs both AST and code objects can package this
code into readily available functions:
-\begin{verbatim}
+\bcode\begin{verbatim}
import parser
def load_suite(source_string):
@@ -323,8 +323,8 @@ def load_expression(source_string):
ast = parser.expr(source_string)
code = parser.compileast(ast)
return ast, code
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\subsubsection{Information Discovery}
Some applications benefit from direct access to the parse tree. The
@@ -366,16 +366,16 @@ Consider the simplest case of interest when searching for docstrings:
a module consisting of a docstring and nothing else. (See file
\file{docstring.py}.)
-\begin{verbatim}
+\bcode\begin{verbatim}
"""Some documentation.
"""
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
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.
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import parser
>>> import pprint
>>> ast = parser.suite(open('docstring.py').read())
@@ -403,8 +403,8 @@ buried deep in nested tuples.
(4, ''))),
(4, ''),
(0, ''))
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
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
@@ -442,7 +442,7 @@ form, allowing a simple variable representation to be
the pattern matching, returning a boolean and a dictionary of variable
name to value mappings. (See file \file{example.py}.)
-\begin{verbatim}
+\bcode\begin{verbatim}
from types import ListType, TupleType
def match(pattern, data, vars=None):
@@ -460,13 +460,13 @@ def match(pattern, data, vars=None):
if not same:
break
return same, vars
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
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}.)
-\begin{verbatim}
+\bcode\begin{verbatim}
import symbol
import token
@@ -493,19 +493,19 @@ DOCSTRING_STMT_PATTERN = (
)))))))))))))))),
(token.NEWLINE, '')
))
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Using the \code{match()} function with this pattern, extracting the
module docstring from the parse tree created previously is easy:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> found, vars = match(DOCSTRING_STMT_PATTERN, tup[1])
>>> found
1
>>> vars
{'docstring': '"""Some documentation.\012"""'}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
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
@@ -567,7 +567,7 @@ grammar, but the method which recursively creates new information
objects requires further examination. Here is the relevant part of
the \code{SuiteInfoBase} definition from \file{example.py}:
-\begin{verbatim}
+\bcode\begin{verbatim}
class SuiteInfoBase:
_docstring = ''
_name = ''
@@ -597,8 +597,8 @@ class SuiteInfoBase:
elif cstmt[0] == symbol.classdef:
name = cstmt[2][1]
self._class_info[name] = ClassInfo(cstmt)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
After initializing some internal state, the constructor calls the
\code{_extract_info()} method. This method performs the bulk of the
information extraction which takes place in the entire example. The
@@ -611,21 +611,21 @@ the ``short form'' or the ``long form.'' The short form is used when
the code block is on the same line as the definition of the code
block, as in
-\begin{verbatim}
+\bcode\begin{verbatim}
def square(x): "Square an argument."; return x ** 2
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
while the long form uses an indented block and allows nested
definitions:
-\begin{verbatim}
+\bcode\begin{verbatim}
def make_power(exp):
"Make a function that raises an argument to the exponent `exp'."
def raiser(x, y=exp):
return x ** y
return raiser
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
When the short form is used, the code block may contain a docstring as
the first, and possibly only, \code{small_stmt} element. The
extraction of such a docstring is slightly different and requires only
@@ -660,7 +660,7 @@ the real extraction algorithm remains common to all forms of code
blocks. A high-level function can be used to extract the complete set
of information from a source file. (See file \file{example.py}.)
-\begin{verbatim}
+\bcode\begin{verbatim}
def get_docs(fileName):
source = open(fileName).read()
import os
@@ -669,8 +669,8 @@ def get_docs(fileName):
ast = parser.suite(source)
tup = parser.ast2tuple(ast)
return ModuleInfo(tup, basename)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
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