[Python-checkins] CVS: python/dist/src/Tools/compiler/doc compiler.tex,1.3,1.4
Fred L. Drake
fdrake@users.sourceforge.net
Wed, 15 Aug 2001 10:01:36 -0700
Update of /cvsroot/python/python/dist/src/Tools/compiler/doc
In directory usw-pr-cvs1:/tmp/cvs-serv22501
Modified Files:
compiler.tex
Log Message:
Use the "howto" document class rather than the "manual" class.
Remove the module index; there aren't enough modules documented yet
for this to make sense.
Add a couple more index entries, fixed a few typos, and adjusted a few
more things for consistency.
Index: compiler.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Tools/compiler/doc/compiler.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** compiler.tex 2001/08/15 14:35:13 1.3
--- compiler.tex 2001/08/15 17:01:34 1.4
***************
*** 6,10 ****
% http://www.python.org/doc/current/doc/doc.html
! \documentclass{manual}
\title{Python compiler package}
--- 6,10 ----
% http://www.python.org/doc/current/doc/doc.html
! \documentclass{howto}
\title{Python compiler package}
***************
*** 16,20 ****
\authoraddress{
PythonLabs \\
! Zope Corp. \\
Email: \email{jeremy@zope.com}
}
--- 16,20 ----
\authoraddress{
PythonLabs \\
! Zope Corporation \\
Email: \email{jeremy@zope.com}
}
***************
*** 37,47 ****
\maketitle
- % This makes the contents more accessible from the front page of the HTML.
- \ifhtml
- \chapter*{Front Matter\label{front}}
- \fi
-
- %\input{copyright}
-
\begin{abstract}
--- 37,40 ----
***************
*** 56,60 ****
\tableofcontents
! \chapter{Introduction\label{Introduction}}
XXX Need basic intro
--- 49,54 ----
\tableofcontents
!
! \section{Introduction\label{Introduction}}
XXX Need basic intro
***************
*** 63,68 ****
--- 57,65 ----
closer to the python source...
+
\section{The basic interface}
+ \declaremodule{}{compiler}
+
The top-level of the package defines four functions.
***************
*** 80,97 ****
\end{funcdesc}
! \begin{funcdesc}{walk}{ast, visitor, \optional{verbose=None}}
Do a pre-order walk over the abstract syntax tree \var{ast}. Call the
appropriate method on the \var{visitor} instance for each node
! encountered.
\end{funcdesc}
! \begin{funcdesc}{compile}{filename}
! Compile the file \var{filename} and generated \var{filename}.pyc.
\end{funcdesc}
The \module{compiler} package contains the following modules:
! \module{ast}, \module{consts}, \module{future}, \module{misc},
! \module{pyassem}, \module{pycodegen}, \module{symbols},
! \module{transformer}, and \module{visitor}.
\section{Limitations}
--- 77,96 ----
\end{funcdesc}
! \begin{funcdesc}{walk}{ast, visitor\optional{, verbose}}
Do a pre-order walk over the abstract syntax tree \var{ast}. Call the
appropriate method on the \var{visitor} instance for each node
! encountered.
\end{funcdesc}
! \begin{funcdesc}{compile}{path}
! Compile the file \var{path} and generate the corresponding \file{.pyc}
! file.
\end{funcdesc}
The \module{compiler} package contains the following modules:
! \refmodule[compiler.ast]{ast}, \module{consts}, \module{future},
! \module{misc}, \module{pyassem}, \module{pycodegen}, \module{symbols},
! \module{transformer}, and \refmodule[compiler.visitor]{visitor}.
!
\section{Limitations}
***************
*** 107,113 ****
\code{def f(x, x): ...}
- \chapter{Python Abstract Syntax}
! \section{Introduction}
The \module{compiler.ast} module defines an abstract syntax for
--- 106,111 ----
\code{def f(x, x): ...}
! \section{Python Abstract Syntax}
The \module{compiler.ast} module defines an abstract syntax for
***************
*** 116,125 ****
The abstract syntax offers a higher level interface to parsed Python
! source code. The \module{parser} module and the compiler written in C
! for the Python interpreter use a concrete syntax tree. The concrete
! syntax is tied closely to the grammar description used for the Python
! parser. Instead of a single node for a construct, there are often
! several levels of nested nodes that are introduced by Python's
! precedence rules.
The abstract syntax tree is created by the
--- 114,124 ----
The abstract syntax offers a higher level interface to parsed Python
! source code. The \ulink{\module{parser}}
! {http://www.python.org/doc/current/lib/module-parser.html}
! module and the compiler written in C for the Python interpreter use a
! concrete syntax tree. The concrete syntax is tied closely to the
! grammar description used for the Python parser. Instead of a single
! node for a construct, there are often several levels of nested nodes
! that are introduced by Python's precedence rules.
The abstract syntax tree is created by the
***************
*** 128,143 ****
generates an abstract syntax tree from the concrete tree.
! The \module{transformer} module was created by Greg Stein and Bill
! Tutt for the Python-to-C compiler. The current version contains a
number of modifications and improvements, but the basic form of the
abstract syntax and of the transformer are due to Stein and Tutt.
\section{AST Nodes}
! The \module{ast} module is generated from a text file that describes
! each node type and its elements. Each node type is represented as a
! class that inherits from the abstract base class \class{ast.Node} and
! defines a set of named attributes for child nodes.
\begin{classdesc}{Node}{}
--- 127,147 ----
generates an abstract syntax tree from the concrete tree.
! The \module{transformer} module was created by Greg
! Stein\index{Stein, Greg} and Bill Tutt\index{Tutt, Bill} for an
! experimental Python-to-C compiler. The current version contains a
number of modifications and improvements, but the basic form of the
abstract syntax and of the transformer are due to Stein and Tutt.
+
\section{AST Nodes}
! \declaremodule{}{compiler.ast}
+ The \module{compiler.ast} module is generated from a text file that
+ describes each node type and its elements. Each node type is
+ represented as a class that inherits from the abstract base class
+ \class{compiler.ast.Node} and defines a set of named attributes for
+ child nodes.
+
\begin{classdesc}{Node}{}
***************
*** 154,177 ****
be \code{None}. XXX Not sure what the rules are for which nodes
will have a useful lineno.
! \begin{methoddesc}{getChildren}{}
! Returns a flattened list of the child nodes and objects in the
! order they occur. Specifically, the order of the nodes is the
! order in which they appear in the Python grammar. Not all of the
! children are \class{Node} instances. The names of functions and
! classes, for example, are plain strings.
! \end{methoddesc}
! \begin{methoddesc}{getChildNodes}{}
! Returns a flattened list of the child nodes in the order they
! occur. This method is like \method{getChildNodes()}, except that it
! only returns those children that are \class{Node} instances.
! \end{methoddesc}
! \end{classdesc}
Two examples illustrate the general structure of \class{Node}
! classes. The while statement is defined by the following grammar
! production:
\begin{verbatim}
--- 158,182 ----
be \code{None}. XXX Not sure what the rules are for which nodes
will have a useful lineno.
+ \end{classdesc}
! All \class{Node} objects offer the following methods:
! \begin{methoddesc}{getChildren}{}
! Returns a flattened list of the child nodes and objects in the
! order they occur. Specifically, the order of the nodes is the
! order in which they appear in the Python grammar. Not all of the
! children are \class{Node} instances. The names of functions and
! classes, for example, are plain strings.
! \end{methoddesc}
! \begin{methoddesc}{getChildNodes}{}
! Returns a flattened list of the child nodes in the order they
! occur. This method is like \method{getChildren()}, except that it
! only returns those children that are \class{Node} instances.
! \end{methoddesc}
Two examples illustrate the general structure of \class{Node}
! classes. The \keyword{while} statement is defined by the following
! grammar production:
\begin{verbatim}
***************
*** 183,191 ****
\member{body}, and \member{else_}. (If the natural name for an
attribute is also a Python reserved word, it can't be used as an
! attribute name. An underscore is appended to the word to make it
! legal, hence \code{else_} instead of \code{else}.)
! The if statement is more complicated because it can include several
! tests.
\begin{verbatim}
--- 188,196 ----
\member{body}, and \member{else_}. (If the natural name for an
attribute is also a Python reserved word, it can't be used as an
! attribute name. An underscore is appended to the word to make it a
! legal identifier, hence \member{else_} instead of \keyword{else}.)
! The \keyword{if} statement is more complicated because it can include
! several tests.
\begin{verbatim}
***************
*** 195,208 ****
The \class{If} node only defines two attributes: \member{tests} and
\member{else_}. The \member{tests} attribute is a sequence of test
! expression, consequent body pairs. There is one pair of each if/elif
! clause. The first element of the pair is the test expression. The
! second elements is a \class{Stmt} node that contains the code to
! execute if the test is true.
The \method{getChildren()} method of \class{If} returns a flat list of
! child nodes. If there are three if/elif clauses and no else clause,
! then \method{getChildren()} will return a list of six elements: the
! first test expression, the first \class{Stmt}, the second text
! expression, etc.
The following table lists each of the \class{Node} subclasses defined
--- 200,213 ----
The \class{If} node only defines two attributes: \member{tests} and
\member{else_}. The \member{tests} attribute is a sequence of test
! expression, consequent body pairs. There is one pair for each
! \keyword{if}/\keyword{elif} clause. The first element of the pair is
! the test expression. The second elements is a \class{Stmt} node that
! contains the code to execute if the test is true.
The \method{getChildren()} method of \class{If} returns a flat list of
! child nodes. If there are three \keyword{if}/\keyword{elif} clauses
! and no \keyword{else} clause, then \method{getChildren()} will return
! a list of six elements: the first test expression, the first
! \class{Stmt}, the second text expression, etc.
The following table lists each of the \class{Node} subclasses defined
***************
*** 216,219 ****
--- 221,225 ----
\input{asttable}
+
\section{Assignment nodes}
***************
*** 230,236 ****
as an example. Explain what the flags are for.
- \chapter{Using Visitors to Walk ASTs}
! The visitor pattern is ... The \module{compiler} package uses a
variant on the visitor pattern that takes advantage of Python's
introspection features to elminiate the need for much of the visitor's
--- 236,245 ----
as an example. Explain what the flags are for.
! \section{Using Visitors to Walk ASTs}
!
! \declaremodule{}{compiler.visitor}
!
! The visitor pattern is ... The \refmodule{compiler} package uses a
variant on the visitor pattern that takes advantage of Python's
introspection features to elminiate the need for much of the visitor's
***************
*** 244,247 ****
--- 253,259 ----
XXX The magic \method{visit()} method for visitors.
+ \begin{funcdesc}{walk}{tree, visitor\optional{, verbose}}
+ \end{funcdesc}
+
\begin{classdesc}{ASTVisitor}{}
***************
*** 260,270 ****
found for a particular node type, the \method{default()} method is
called.
XXX describe extra arguments
! \begin{methoddesc}{default}{node\optional{, *args}}
\end{methoddesc}
! \begin{methoddesc}{dispatch}{node\optional{, *args}}
\end{methoddesc}
--- 272,285 ----
found for a particular node type, the \method{default()} method is
called.
+ \end{classdesc}
+ \class{ASTVisitor} objects have the following methods:
+
XXX describe extra arguments
! \begin{methoddesc}{default}{node\optional{, \moreargs}}
\end{methoddesc}
! \begin{methoddesc}{dispatch}{node\optional{, \moreargs}}
\end{methoddesc}
***************
*** 272,283 ****
\end{methoddesc}
- \end{classdesc}
! \begin{funcdesc}{walk}{tree, visitor\optional{, verbose=None}}
! \end{funcdesc}
!
! \chapter{Bytecode Generation}
! The code generator is a visit that emits bytecodes. Each visit method
can call the \method{emit()} method to emit a new bytecode. The basic
code generator is specialized for modules, classes, and functions. An
--- 287,294 ----
\end{methoddesc}
! \section{Bytecode Generation}
! The code generator is a visitor that emits bytecodes. Each visit method
can call the \method{emit()} method to emit a new bytecode. The basic
code generator is specialized for modules, classes, and functions. An
***************
*** 286,306 ****
objects and calculation of jump offsets.
- %
- % The ugly "%begin{latexonly}" pseudo-environments are really just to
- % keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
- % not really valuable.
- %
- % If you don't want the Module Index, you can remove all of this up
- % until the second \input line.
- %
- %begin{latexonly}
- \renewcommand{\indexname}{Module Index}
- %end{latexonly}
- \input{mod\jobname.ind} % Module Index
! %begin{latexonly}
! \renewcommand{\indexname}{Index}
! %end{latexonly}
! \input{\jobname.ind} % Index
\end{document}
--- 297,302 ----
objects and calculation of jump offsets.
! \input{compiler.ind} % Index
\end{document}