Initial revision

1 files changed, 468 insertions, 0 deletions

diff --git a/Doc/ref6.tex b/Doc/ref6.tex
new file mode 100644
index 0000000..cb257a3
--- /dev/null
+++ b/Doc/ref6.tex
@@ -0,0 +1,468 @@
+\chapter{Simple statements}
+\indexii{simple}{statement}
+
+Simple statements are comprised within a single logical line.
+Several simple statements may occur on a single line separated
+by semicolons.  The syntax for simple statements is:
+
+\begin{verbatim}
+simple_stmt:    expression_stmt
+              | assignment_stmt
+              | pass_stmt
+              | del_stmt
+              | print_stmt
+              | return_stmt
+              | raise_stmt
+              | break_stmt
+              | continue_stmt
+              | import_stmt
+              | global_stmt
+\end{verbatim}
+
+\section{Expression statements}
+\indexii{expression}{statement}
+
+Expression statements are used (mostly interactively) to compute and
+write a value, or (usually) to call a procedure (a function that
+returns no meaningful result; in Python, procedures return the value
+\verb\None\):
+
+\begin{verbatim}
+expression_stmt: expression_list
+\end{verbatim}
+
+An expression statement evaluates the expression list (which may be a
+single expression).  If the value is not \verb\None\, it is converted
+to a string using the rules for string conversions (expressions in
+reverse quotes), and the resulting string is written to standard
+output (see section \ref{print}) on a line by itself.
+\indexii{expression}{list}
+\ttindex{None}
+\indexii{string}{conversion}
+\index{output}
+\indexii{standard}{output}
+\indexii{writing}{values}
+
+(The exception for \verb\None\ is made so that procedure calls, which
+are syntactically equivalent to expressions, do not cause any output.
+A tuple with only \verb\None\ items is written normally.)
+\indexii{procedure}{call}
+
+\section{Assignment statements}
+\indexii{assignment}{statement}
+
+Assignment statements are used to (re)bind names to values and to
+modify attributes or items of mutable objects:
+\indexii{binding}{name}
+\indexii{rebinding}{name}
+\obindex{mutable}
+\indexii{attribute}{assignment}
+
+\begin{verbatim}
+assignment_stmt: (target_list "=")+ expression_list
+target_list:     target ("," target)* [","]
+target:          identifier | "(" target_list ")" | "[" target_list "]"
+               | attributeref | subscription | slicing
+\end{verbatim}
+
+(See section \ref{primaries} for the syntax definitions for the last
+three symbols.)
+
+An assignment statement evaluates the expression list (remember that
+this can be a single expression or a comma-separated list, the latter
+yielding a tuple) and assigns the single resulting object to each of
+the target lists, from left to right.
+\indexii{expression}{list}
+
+Assignment is defined recursively depending on the form of the target
+(list).  When a target is part of a mutable object (an attribute
+reference, subscription or slicing), the mutable object must
+ultimately perform the assignment and decide about its validity, and
+may raise an exception if the assignment is unacceptable.  The rules
+observed by various types and the exceptions raised are given with the
+definition of the object types (see section \ref{types}).
+\index{target}
+\indexii{target}{list}
+
+Assignment of an object to a target list is recursively defined as
+follows.
+\indexiii{target}{list}{assignment}
+
+\begin{itemize}
+\item
+If the target list is a single target: the object is assigned to that
+target.
+
+\item
+If the target list is a comma-separated list of targets: the object
+must be a tuple with the same number of items as the list contains
+targets, and the items are assigned, from left to right, to the
+corresponding targets.
+
+\end{itemize}
+
+Assignment of an object to a single target is recursively defined as
+follows.
+
+\begin{itemize} % nested
+
+\item
+If the target is an identifier (name):
+
+\begin{itemize}
+
+\item
+If the name does not occur in a \verb\global\ statement in the current
+code block: the name is bound to the object in the current local name
+space.
+\stindex{global}
+
+\item
+Otherwise: the name is bound to the object in the current global name
+space.
+
+\end{itemize} % nested
+
+The name is rebound if it was already bound.
+
+\item
+If the target is a target list enclosed in parentheses: the object is
+assigned to that target list as described above.
+
+\item
+If the target is a target list enclosed in square brackets: the object
+must be a list with the same number of items as the target list
+contains targets, and its items are assigned, from left to right, to
+the corresponding targets.
+
+\item
+If the target is an attribute reference: The primary expression in the
+reference is evaluated.  It should yield an object with assignable
+attributes; if this is not the case, \verb\TypeError\ is raised.  That
+object is then asked to assign the assigned object to the given
+attribute; if it cannot perform the assignment, it raises an exception
+(usually but not necessarily \verb\AttributeError\).
+\indexii{attribute}{assignment}
+
+\item
+If the target is a subscription: The primary expression in the
+reference is evaluated.  It should yield either a mutable sequence
+(list) object or a mapping (dictionary) object.  Next, the subscript
+expression is evaluated.
+\indexii{subscription}{assignment}
+\obindex{mutable}
+
+If the primary is a mutable sequence object (a list), the subscript
+must yield a plain integer.  If it is negative, the sequence's length
+is added to it.  The resulting value must be a nonnegative integer
+less than the sequence's length, and the sequence is asked to assign
+the assigned object to its item with that index.  If the index is out
+of range, \verb\IndexError\ is raised (assignment to a subscripted
+sequence cannot add new items to a list).
+\obindex{sequence}
+\obindex{list}
+
+If the primary is a mapping (dictionary) object, the subscript must
+have a type compatible with the mapping's key type, and the mapping is
+then asked to to create a key/datum pair which maps the subscript to
+the assigned object.  This can either replace an existing key/value
+pair with the same key value, or insert a new key/value pair (if no
+key with the same value existed).
+\obindex{mapping}
+\obindex{dictionary}
+
+\item
+If the target is a slicing: The primary expression in the reference is
+evaluated.  It should yield a mutable sequence (list) object.  The
+assigned object should be a sequence object of the same type.  Next,
+the lower and upper bound expressions are evaluated, insofar they are
+present; defaults are zero and the sequence's length.  The bounds
+should evaluate to (small) integers.  If either bound is negative, the
+sequence's length is added to it.  The resulting bounds are clipped to
+lie between zero and the sequence's length, inclusive.  Finally, the
+sequence object is asked to replace the items indicated by the slice
+with the items of the assigned sequence.  This may change the
+sequence's length, if it allows it.
+\indexii{slicing}{assignment}
+
+\end{itemize}
+	
+(In the original implementation, the syntax for targets is taken
+to be the same as for expressions, and invalid syntax is rejected
+during the code generation phase, causing less detailed error
+messages.)
+
+\section{The {\tt pass} statement}
+\stindex{pass}
+
+\begin{verbatim}
+pass_stmt:      "pass"
+\end{verbatim}
+
+\verb\pass\ is a null operation --- when it is executed, nothing
+happens.  It is useful as a placeholder when a statement is
+required syntactically, but no code needs to be executed, for example:
+\indexii{null}{operation}
+
+\begin{verbatim}
+def f(arg): pass    # a function that does nothing (yet)
+
+class C: pass       # an class with no methods (yet)
+\end{verbatim}
+
+\section{The {\tt del} statement}
+\stindex{del}
+
+\begin{verbatim}
+del_stmt:       "del" target_list
+\end{verbatim}
+
+Deletion is recursively defined very similar to the way assignment is
+defined. Rather that spelling it out in full details, here are some
+hints.
+\indexii{deletion}{target}
+\indexiii{deletion}{target}{list}
+
+Deletion of a target list recursively deletes each target, from left
+to right.
+
+Deletion of a name removes the binding of that name (which must exist)
+from the local or global name space, depending on whether the name
+occurs in a \verb\global\ statement in the same code block.
+\stindex{global}
+\indexii{unbinding}{name}
+
+Deletion of attribute references, subscriptions and slicings
+is passed to the primary object involved; deletion of a slicing
+is in general equivalent to assignment of an empty slice of the
+right type (but even this is determined by the sliced object).
+\indexii{attribute}{deletion}
+
+\section{The {\tt print} statement} \label{print}
+\stindex{print}
+
+\begin{verbatim}
+print_stmt:     "print" [ condition ("," condition)* [","] ]
+\end{verbatim}
+
+\verb\print\ evaluates each condition in turn and writes the resulting
+object to standard output (see below).  If an object is not a string,
+it is first converted to a string using the rules for string
+conversions.  The (resulting or original) string is then written.  A
+space is written before each object is (converted and) written, unless
+the output system believes it is positioned at the beginning of a
+line.  This is the case: (1) when no characters have yet been written
+to standard output; or (2) when the last character written to standard
+output is \verb/\n/; or (3) when the last write operation on standard
+output was not a \verb\print\ statement.  (In some cases it may be
+functional to write an empty string to standard output for this
+reason.)
+\index{output}
+\indexii{writing}{values}
+
+A \verb/"\n"/ character is written at the end, unless the \verb\print\
+statement ends with a comma.  This is the only action if the statement
+contains just the keyword \verb\print\.
+\indexii{trailing}{comma}
+\indexii{newline}{suppression}
+
+Standard output is defined as the file object named \verb\stdout\
+in the built-in module \verb\sys\.  If no such object exists,
+or if it is not a writable file, a \verb\RuntimeError\ exception is raised.
+(The original implementation attempts to write to the system's original
+standard output instead, but this is not safe, and should be fixed.)
+\indexii{standard}{output}
+\bimodindex{sys}
+\ttindex{stdout}
+\exindex{RuntimeError}
+
+\section{The {\tt return} statement}
+\stindex{return}
+
+\begin{verbatim}
+return_stmt:    "return" [condition_list]
+\end{verbatim}
+
+\verb\return\ may only occur syntactically nested in a function
+definition, not within a nested class definition.
+\indexii{function}{definition}
+\indexii{class}{definition}
+
+If a condition list is present, it is evaluated, else \verb\None\
+is substituted.
+
+\verb\return\ leaves the current function call with the condition
+list (or \verb\None\) as return value.
+
+When \verb\return\ passes control out of a \verb\try\ statement
+with a \verb\finally\ clause, that finally clause is executed
+before really leaving the function.
+\kwindex{finally}
+
+\section{The {\tt raise} statement}
+\stindex{raise}
+
+\begin{verbatim}
+raise_stmt:     "raise" condition ["," condition]
+\end{verbatim}
+
+\verb\raise\ evaluates its first condition, which must yield
+a string object.  If there is a second condition, this is evaluated,
+else \verb\None\ is substituted.
+\index{exception}
+\indexii{raising}{exception}
+
+It then raises the exception identified by the first object,
+with the second one (or \verb\None\) as its parameter.
+
+\section{The {\tt break} statement}
+\stindex{break}
+
+\begin{verbatim}
+break_stmt:     "break"
+\end{verbatim}
+
+\verb\break\ may only occur syntactically nested in a \verb\for\
+or \verb\while\ loop, not nested in a function or class definition.
+\stindex{for}
+\stindex{while}
+\indexii{loop}{statement}
+
+It terminates the neares enclosing loop, skipping the optional
+\verb\else\ clause if the loop has one.
+\kwindex{else}
+
+If a \verb\for\ loop is terminated by \verb\break\, the loop control
+target keeps its current value.
+\indexii{loop control}{target}
+
+When \verb\break\ passes control out of a \verb\try\ statement
+with a \verb\finally\ clause, that finally clause is executed
+before really leaving the loop.
+\kwindex{finally}
+
+\section{The {\tt continue} statement}
+\stindex{continue}
+
+\begin{verbatim}
+continue_stmt:  "continue"
+\end{verbatim}
+
+\verb\continue\ may only occur syntactically nested in a \verb\for\ or
+\verb\while\ loop, not nested in a function or class definition, and
+not nested in the \verb\try\ clause of a \verb\try\ statement with a
+\verb\finally\ clause (it may occur nested in a \verb\except\ or
+\verb\finally\ clause of a \verb\try\ statement though).
+\stindex{for}
+\stindex{while}
+\indexii{loop}{statement}
+\kwindex{finally}
+
+It continues with the next cycle of the nearest enclosing loop.
+
+\section{The {\tt import} statement} \label{import}
+\stindex{import}
+
+\begin{verbatim}
+import_stmt:    "import" identifier ("," identifier)*
+              | "from" identifier "import" identifier ("," identifier)*
+              | "from" identifier "import" "*"
+\end{verbatim}
+
+Import statements are executed in two steps: (1) find a module, and
+initialize it if necessary; (2) define a name or names in the local
+name space (of the scope where the \verb\import\ statement occurs).
+The first form (without \verb\from\) repeats these steps for each
+identifier in the list, the \verb\from\ form performs them once, with
+the first identifier specifying the module name.
+\indexii{importing}{module}
+\indexii{name}{binding}
+\kwindex{from}
+
+The system maintains a table of modules that have been initialized,
+indexed by module name.  (The current implementation makes this table
+accessible as \verb\sys.modules\.)  When a module name is found in
+this table, step (1) is finished.  If not, a search for a module
+definition is started.  This first looks for a built-in module
+definition, and if no built-in module if the given name is found, it
+searches a user-specified list of directories for a file whose name is
+the module name with extension \verb\".py"\.  (The current
+implementation uses the list of strings \verb\sys.path\ as the search
+path; it is initialized from the shell environment variable
+\verb\$PYTHONPATH\, with an installation-dependent default.)
+\ttindex{modules}
+\ttindex{sys.modules}
+\indexii{module}{name}
+\indexii{built-in}{module}
+\indexii{user-defined}{module}
+\bimodindex{sys}
+\ttindex{path}
+\ttindex{sys.path}
+\indexii{filename}{extension}
+
+If a built-in module is found, its built-in initialization code is
+executed and step (1) is finished.  If no matching file is found,
+\verb\ImportError\ is raised.  If a file is found, it is parsed,
+yielding an executable code block.  If a syntax error occurs,
+\verb\SyntaxError\ is raised.  Otherwise, an empty module of the given
+name is created and inserted in the module table, and then the code
+block is executed in the context of this module.  Exceptions during
+this execution terminate step (1).
+\indexii{module}{initialization}
+\exindex{SyntaxError}
+\exindex{ImportError}
+\index{code block}
+
+When step (1) finishes without raising an exception, step (2) can
+begin.
+
+The first form of \verb\import\ statement binds the module name in the
+local name space to the module object, and then goes on to import the
+next identifier, if any.  The \verb\from\ from does not bind the
+module name: it goes through the list of identifiers, looks each one
+of them up in the module found in step (1), and binds the name in the
+local name space to the object thus found.  If a name is not found,
+\verb\ImportError\ is raised.  If the list of identifiers is replaced
+by a star (\verb\*\), all names defined in the module are bound,
+except those beginning with an underscore(\verb\_\).
+\indexii{name}{binding}
+\exindex{ImportError}
+
+Names bound by import statements may not occur in \verb\global\
+statements in the same scope.
+\stindex{global}
+
+The \verb\from\ form with \verb\*\ may only occur in a module scope.
+\kwindex{from}
+\ttindex{from ... import *}
+
+(The current implementation does not enforce the latter two
+restrictions, but programs should not abuse this freedom, as future
+implementations may enforce them or silently change the meaning of the
+program.)
+
+\section{The {\tt global} statement} \label{global}
+\stindex{global}
+
+\begin{verbatim}
+global_stmt:    "global" identifier ("," identifier)*
+\end{verbatim}
+
+The \verb\global\ statement is a declaration which holds for the
+entire current scope.  It means that the listed identifiers are to be
+interpreted as globals.  While {\em using} global names is automatic
+if they are not defined in the local scope, {\em assigning} to global
+names would be impossible without \verb\global\.
+\indexiii{global}{name}{binding}
+
+Names listed in a \verb\global\ statement must not be used in the same
+scope before that \verb\global\ statement is executed.
+
+Names listed in a \verb\global\ statement must not be defined as formal
+parameters or in a \verb\for\ loop control target, \verb\class\
+definition, function definition, or \verb\import\ statement.
+
+(The current implementation does not enforce the latter two
+restrictions, but programs should not abuse this freedom, as future
+implementations may enforce them or silently change the meaning of the
+program.)