[Python-checkins] CVS: python/dist/src/Tools/compiler/doc compiler.tex,1.5,1.6

2001年8月17日 17:24:48 -0700

Update of /cvsroot/python/python/dist/src/Tools/compiler/doc
In directory usw-pr-cvs1:/tmp/cvs-serv6569
Modified Files:
	compiler.tex 
Log Message:
Add a little introductory text.
Change several sections to subsections (part of the manual -> howto
transformation). 
Flesh out discussion of assignment nodes (and delete statements).
Add an example of manipulating AST objects at a >>> prompt
Index: compiler.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Tools/compiler/doc/compiler.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** compiler.tex	2001年08月15日 18:48:10	1.5
--- compiler.tex	2001年08月18日 00:24:46	1.6
***************
*** 52,66 ****
 \section{Introduction\label{Introduction}}

! XXX Need basic intro

! XXX what are the major advantages... the abstract syntax is much
! closer to the python source...

! \section{The basic interface}

 \declaremodule{}{compiler}

! The top-level of the package defines four functions.

 \begin{funcdesc}{parse}{buf}
--- 52,80 ----
 \section{Introduction\label{Introduction}}

! The \module{compiler} package is a Python source to bytecode
! translator written in Python. It uses the builtin parser and standard
! \ulink{\module{parser}}
! {http://www.python.org/doc/current/lib/module-parser.html} to
! generated a concrete syntax tree. This tree is used to generate an
! abstract syntax tree (AST) and then Python bytecode.

! The full functionality of the package duplicates the builtin compiler
! provided with the Python interpreter. It is intended to match its
! behavior almost exactly. Why implement another compiler that does the
! same thing? The package is useful for a variety of purposes. It can
! be modified more easily than the builtin compiler. The AST it
! generates is useful for analyzing Python source code.

+ This manual explains how the various components of the
+ \module{compiler} package work. It blends reference material with a
+ tutorial. (At least it will when the document is done.)

! \subsection{The basic interface}

 \declaremodule{}{compiler}

! The top-level of the package defines four functions. If you import
! \module{compiler}, you will get these functions and a collection of
! modules contained in the package.

 \begin{funcdesc}{parse}{buf}
***************
*** 92,98 ****
 \module{misc}, \module{pyassem}, \module{pycodegen}, \module{symbols},
 \module{transformer}, and \refmodule[compiler.visitor]{visitor}.
- 

! \section{Limitations}

 There are some problems with the error checking of the compiler
--- 106,111 ----
 \module{misc}, \module{pyassem}, \module{pycodegen}, \module{symbols},
 \module{transformer}, and \refmodule[compiler.visitor]{visitor}.

! \subsection{Limitations}

 There are some problems with the error checking of the compiler
***************
*** 106,109 ****
--- 119,123 ----
 \code{def f(x, x): ...}

+ A future version of the compiler should fix these problems.

 \section{Python Abstract Syntax}
***************
*** 133,138 ****
 abstract syntax and of the transformer are due to Stein and Tutt.

! 
! \section{AST Nodes}

 \declaremodule{}{compiler.ast}
--- 147,151 ----
 abstract syntax and of the transformer are due to Stein and Tutt.

! \subsection{AST Nodes}

 \declaremodule{}{compiler.ast}
***************
*** 222,226 ****

! \section{Assignment nodes}

 There is a collection of nodes used to represent assignments. Each
--- 235,239 ----

! \subsection{Assignment nodes}

 There is a collection of nodes used to represent assignments. Each
***************
*** 233,239 ****
 \class{AssTuple}. 

! XXX Explain what the AssXXX nodes are for. Mention \code{a.b.c = 2}
! as an example. Explain what the flags are for.

 \section{Using Visitors to Walk ASTs}
--- 246,317 ----
 \class{AssTuple}. 

! Each target assignment node will describe the kind of object being
! assigned to: \class{AssName} for a simple name, e.g. \code{a = 1}.
! \class{AssAttr} for an attribute assigned, e.g. \code{a.x = 1}.
! \class{AssList} and \class{AssTuple} for list and tuple expansion
! respectively, e.g. \code{a, b, c = a_tuple}.
! 
! The target assignment nodes also have a \member{flags} attribute that
! indicates whether the node is being used for assignment or in a delete
! statement. The \class{AssName} is also used to represent a delete
! statement, e.g. \class{del x}.
! 
! When an expression contains several attribute references, an
! assignment or delete statement will contain only one \class{AssAttr}
! node -- for the final attribute reference. The other attribute
! references will be represented as \class{Getattr} nodes in the
! \member{expr} attribute of the \class{AssAttr} instance.

+ \subsection{Examples}
+ 
+ This section shows several simple examples of ASTs for Python source
+ code. The examples demonstrate how to use the \function{parse()}
+ function, what the repr of an AST looks like, and how to access
+ attributes of an AST node.
+ 
+ The first module defines a single function. Assume it is stored in
+ \file{/tmp/doublelib.py}. 
+ 
+ \begin{verbatim}
+ """This is an example module.
+ 
+ This is the docstring.
+ """
+ 
+ def double(x):
+ "Return twice the argument"
+ return x * 2
+ \end{verbatim}
+ 
+ In the interactive interpreter session below, I have reformatted the
+ long AST reprs for readability. The AST reprs use unqualified class
+ names. If you want to create an instance from a repr, you must import
+ the class names from the \module{compiler.ast} module.
+ 
+ \begin{verbatim}
+ >>> import compiler
+ >>> mod = compiler.parseFile("/tmp/doublelib.py")
+ >>> mod
+ Module('This is an example module.\n\nThis is the docstring.\n', 
+ Stmt([Function('double', ['x'], [], 0, 'Return twice the argument', 
+ Stmt([Return(Mul((Name('x'), Const(2))))]))]))
+ >>> from compiler.ast import *
+ >>> Module('This is an example module.\n\nThis is the docstring.\n', 
+ ... Stmt([Function('double', ['x'], [], 0, 'Return twice the argument', 
+ ... Stmt([Return(Mul((Name('x'), Const(2))))]))]))
+ Module('This is an example module.\n\nThis is the docstring.\n', 
+ Stmt([Function('double', ['x'], [], 0, 'Return twice the argument', 
+ Stmt([Return(Mul((Name('x'), Const(2))))]))]))
+ >>> mod.doc
+ 'This is an example module.\n\nThis is the docstring.\n'
+ >>> for node in mod.node.nodes:
+ ... print node
+ ... 
+ Function('double', ['x'], [], 0, 'Return twice the argument',
+ Stmt([Return(Mul((Name('x'), Const(2))))]))
+ >>> func = mod.node.nodes[0]
+ >>> func.code
+ Stmt([Return(Mul((Name('x'), Const(2))))])
+ \end{verbatim}

 \section{Using Visitors to Walk ASTs}