[Python-checkins] r42817 - peps/trunk/pep-0339.txt

[neal.norwitz]

Author: neal.norwitz
Date: Fri Mar  3 22:45:55 2006
New Revision: 42817

Modified:
   peps/trunk/pep-0339.txt
Log:
Fix some sentances, add a little info about ceval, remove asdl_seq_APPEND()

Modified: peps/trunk/pep-0339.txt
==============================================================================
--- peps/trunk/pep-0339.txt	(original)
+++ peps/trunk/pep-0339.txt	Fri Mar  3 22:45:55 2006
@@ -86,7 +86,7 @@
 
 The abstract syntax tree (AST) is a high-level representation of the
 program structure without the necessity of containing the source code;
-it can be thought of a abstract representation of the source code.  The
+it can be thought of as an abstract representation of the source code.  The
 specification of the AST nodes is specified using the Zephyr Abstract
 Syntax Definition Language (ASDL) [Wang97]_.
 
@@ -188,6 +188,12 @@
 management when working on the compiler.  The technical details have been
 designed to be hidden from you for most cases.
 
+The only exception comes about when managing a PyObject.  Since the rest
+of Python uses reference counting, there is extra support added
+to the arena to cleanup each PyObject that was allocated.  These cases
+are very rare.  However, if you've allocated a PyObject, you must tell
+the arena about it by calling PyArena_AddPyObject().
+
 
 Parse Tree to AST
 -----------------
@@ -204,11 +210,9 @@
 the grammar specification and the nodes in the parse tree.  No help is
 directly provided by the parse tree as in yacc.
 
-For instance, one must keep track of
-which node in the parse tree one is working with (e.g., if you are
-working with an 'if' statement you need to watch out for the ':' token
-to find the end of the conditional).  No help is directly provided by
-the parse tree as in yacc.
+For instance, one must keep track of which node in the parse tree
+one is working with (e.g., if you are working with an 'if' statement
+you need to watch out for the ':' token to find the end of the conditional).
 
 The functions called to generate AST nodes from the parse tree all have
 the name ast_for_xx where xx is what the grammar rule that the function
@@ -228,8 +232,6 @@
 	Get item held at a specific position in an asdl_seq
 - ``asdl_seq_SET()``
 	Set a specific index in an asdl_seq to the specified value
-- ``asdl_seq_APPEND()``
-	Append a value to the end of an asdl_seq
 - ``asdl_seq_LEN(asdl_seq *)``
 	Return the length of an asdl_seq
 
@@ -320,7 +322,7 @@
 Emission of bytecode is handled by the following macros:
 
 - ``ADDOP()``
-    add a specified opcode.
+    add a specified opcode
 - ``ADDOP_I()``
     add an opcode that takes an argument
 - ``ADDOP_O(struct compiler *c, int op, PyObject *type, PyObject *obj)``
@@ -385,12 +387,13 @@
 
 With a new bytecode you must also change what is called the magic number for
 .pyc files.  The variable ``MAGIC`` in Python/import.c contains the number.
-Changing this number will lead to 
+Changing this number will lead to all .pyc files with the old MAGIC
+to be recompiled by the interpreter on import.
 
 Finally, you need to introduce the use of the new bytecode.  Altering
-Python/compile.c will be the primary place for changes.  But you will also need
-to change the 'compiler' package.  The key files to do that are
-Lib/compiler/pyassem.py and Lib/compiler/pycodegen.py .
+Python/compile.c and Python/ceval.c will be the primary places to change.
+But you will also need to change the 'compiler' package.  The key files
+to do that are Lib/compiler/pyassem.py and Lib/compiler/pycodegen.py .
 
 If you make a change here that can affect the output of bytecode that
 is already in existence and you do not change the magic number constantly, make
@@ -407,9 +410,13 @@
 Code Objects
 ------------
 
-In the end, one ends up with a PyCodeObject which is defined in
+The result of ``PyAST_Compile()`` is a PyCodeObject which is defined in
 Include/code.h .  And with that you now have executable Python bytecode!
 
+The code objects (byte code) is executed in Python/ceval.c .  This file
+will also need a new case statement for the new opcode in the big switch
+statement in PyEval_EvalFrameEx().
+
 
 Important Files
 ---------------
@@ -446,6 +453,9 @@
     - ast.c
         Converts Python's parse tree into the abstract syntax tree.
 
+    - ceval.c
+        Executes byte code (aka, eval loop).
+
     - compile.c
         Emits bytecode based on the AST.