Initial revision

1 files changed, 347 insertions, 0 deletions

diff --git a/Doc/ref7.tex b/Doc/ref7.tex
new file mode 100644
index 0000000..357bd5f
--- /dev/null
+++ b/Doc/ref7.tex
@@ -0,0 +1,347 @@
+\chapter{Compound statements}
+\indexii{compound}{statement}
+
+Compound statements contain (groups of) other statements; they affect
+or control the execution of those other statements in some way.  In
+general, compound statements span multiple lines, although in simple
+incarnations a whole compound statement may be contained in one line.
+
+The \verb\if\, \verb\while\ and \verb\for\ statements implement
+traditional control flow constructs.  \verb\try\ specifies exception
+handlers and/or cleanup code for a group of statements.  Function and
+class definitions are also syntactically compound statements.
+
+Compound statements consist of one or more `clauses'.  A clause
+consists of a header and a `suite'.  The clause headers of a
+particular compound statement are all at the same indentation level.
+Each clause header begins with a uniquely identifying keyword and ends
+with a colon.  A suite is a group of statements controlled by a
+clause.  A suite can be one or more semicolon-separated simple
+statements on the same line as the header, following the header's
+colon, or it can be one or more indented statements on subsequent
+lines.  Only the latter form of suite can contain nested compound
+statements; the following is illegal, mostly because it wouldn't be
+clear to which \verb\if\ clause a following \verb\else\ clause would
+belong:
+\index{clause}
+\index{suite}
+
+\begin{verbatim}
+if test1: if test2: print x
+\end{verbatim}
+
+Also note that the semicolon binds tighter than the colon in this
+context, so that in the following example, either all or none of the
+\verb\print\ statements are executed:
+
+\begin{verbatim}
+if x < y < z: print x; print y; print z
+\end{verbatim}
+
+Summarizing:
+
+\begin{verbatim}
+compound_stmt:  if_stmt | while_stmt | for_stmt
+              | try_stmt | funcdef | classdef
+suite:          stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT
+statement:      stmt_list NEWLINE | compound_stmt
+stmt_list:      simple_stmt (";" simple_stmt)* [";"]
+\end{verbatim}
+
+Note that statements always end in a \verb\NEWLINE\ possibly followed
+by a \verb\DEDENT\.
+\index{NEWLINE token}
+\index{DEDENT token}
+
+Also note that optional continuation clauses always begin with a
+keyword that cannot start a statement, thus there are no ambiguities
+(the `dangling \verb\else\' problem is solved in Python by requiring
+nested \verb\if\ statements to be indented).
+\indexii{dangling}{else}
+
+The formatting of the grammar rules in the following sections places
+each clause on a separate line for clarity.
+
+\section{The {\tt if} statement}
+\stindex{if}
+
+The \verb\if\ statement is used for conditional execution:
+
+\begin{verbatim}
+if_stmt:        "if" condition ":" suite
+               ("elif" condition ":" suite)*
+               ["else" ":" suite]
+\end{verbatim}
+
+It selects exactly one of the suites by evaluating the conditions one
+by one until one is found to be true (see section \ref{Booleans} for
+the definition of true and false); then that suite is executed (and no
+other part of the \verb\if\ statement is executed or evaluated).  If
+all conditions are false, the suite of the \verb\else\ clause, if
+present, is executed.
+\kwindex{elif}
+\kwindex{else}
+
+\section{The {\tt while} statement}
+\stindex{while}
+\indexii{loop}{statement}
+
+The \verb\while\ statement is used for repeated execution as long as a
+condition is true:
+
+\begin{verbatim}
+while_stmt:     "while" condition ":" suite
+               ["else" ":" suite]
+\end{verbatim}
+
+This repeatedly tests the condition and, if it is true, executes the
+first suite; if the condition is false (which may be the first time it
+is tested) the suite of the \verb\else\ clause, if present, is
+executed and the loop terminates.
+\kwindex{else}
+
+A \verb\break\ statement executed in the first suite terminates the
+loop without executing the \verb\else\ clause's suite.  A
+\verb\continue\ statement executed in the first suite skips the rest
+of the suite and goes back to testing the condition.
+\stindex{break}
+\stindex{continue}
+
+\section{The {\tt for} statement}
+\stindex{for}
+\indexii{loop}{statement}
+
+The \verb\for\ statement is used to iterate over the elements of a
+sequence (string, tuple or list):
+\obindex{sequence}
+
+\begin{verbatim}
+for_stmt:       "for" target_list "in" condition_list ":" suite
+               ["else" ":" suite]
+\end{verbatim}
+
+The condition list is evaluated once; it should yield a sequence.  The
+suite is then executed once for each item in the sequence, in the
+order of ascending indices.  Each item in turn is assigned to the
+target list using the standard rules for assignments, and then the
+suite is executed.  When the items are exhausted (which is immediately
+when the sequence is empty), the suite in the \verb\else\ clause, if
+present, is executed, and the loop terminates.
+\kwindex{in}
+\kwindex{else}
+\indexii{target}{list}
+
+A \verb\break\ statement executed in the first suite terminates the
+loop without executing the \verb\else\ clause's suite.  A
+\verb\continue\ statement executed in the first suite skips the rest
+of the suite and continues with the next item, or with the \verb\else\
+clause if there was no next item.
+\stindex{break}
+\stindex{continue}
+
+The suite may assign to the variable(s) in the target list; this does
+not affect the next item assigned to it.
+
+The target list is not deleted when the loop is finished, but if the
+sequence is empty, it will not have been assigned to at all by the
+loop.
+
+Hint: the built-in function \verb\range()\ returns a sequence of
+integers suitable to emulate the effect of Pascal's \verb\for i := a
+to b do\; e.g. \verb\range(3)\ returns the list \verb\[0, 1, 2]\.
+\bifuncindex{range}
+\index{Pascal}
+
+{\bf Warning:} There is a subtlety when the sequence is being modified
+by the loop (this can only occur for mutable sequences, i.e. lists).
+An internal counter is used to keep track of which item is used next,
+and this is incremented on each iteration.  When this counter has
+reached the length of the sequence the loop terminates.  This means that
+if the suite deletes the current (or a previous) item from the
+sequence, the next item will be skipped (since it gets the index of
+the current item which has already been treated).  Likewise, if the
+suite inserts an item in the sequence before the current item, the
+current item will be treated again the next time through the loop.
+This can lead to nasty bugs that can be avoided by making a temporary
+copy using a slice of the whole sequence, e.g.
+\index{loop!over mutable sequence}
+\index{mutable sequence!loop over}
+
+\begin{verbatim}
+for x in a[:]:
+    if x < 0: a.remove(x)
+\end{verbatim}
+
+\section{The {\tt try} statement}
+\stindex{try}
+
+The \verb\try\ statement specifies exception handlers and/or cleanup
+code for a group of statements:
+
+\begin{verbatim}
+try_stmt:       try_exc_stmt | try_fin_stmt
+try_exc_stmt:   "try" ":" suite
+               ("except" [condition ["," target]] ":" suite)+
+try_fin_stmt:   "try" ":" suite
+               "finally" ":" suite
+\end{verbatim}
+
+There are two forms of \verb\try\ statement: \verb\try...except\ and
+\verb\try...finally\.  These forms cannot be mixed.
+
+The \verb\try...except\ form specifies one or more exception handlers
+(the \verb\except\ clauses).  When no exception occurs in the
+\verb\try\ clause, no exception handler is executed.  When an
+exception occurs in the \verb\try\ suite, a search for an exception
+handler is started.  This inspects the except clauses in turn until
+one is found that matches the exception.  A condition-less except
+clause, if present, must be last; it matches any exception.  For an
+except clause with a condition, that condition is evaluated, and the
+clause matches the exception if the resulting object is ``compatible''
+with the exception.  An object is compatible with an exception if it
+is either the object that identifies the exception or it is a tuple
+containing an item that is compatible with the exception.  Note that
+the object identities must match, i.e. it must be the same object, not
+just an object with the same value.
+\kwindex{except}
+
+If no except clause matches the exception, the search for an exception
+handler continues in the surrounding code and on the invocation stack.
+
+If the evaluation of a condition in the header of an except clause
+raises an exception, the original search for a handler is cancelled
+and a search starts for the new exception in the surrounding code and
+on the call stack (it is treated as if the entire \verb\try\ statement
+raised the exception).
+
+When a matching except clause is found, the exception's parameter is
+assigned to the target specified in that except clause, if present,
+and the except clause's suite is executed.  When the end of this suite
+is reached, execution continues normally after the entire try
+statement.  (This means that if two nested handlers exist for the same
+exception, and the exception occurs in the try clause of the inner
+handler, the outer handler will not handle the exception.)
+
+The \verb\try...finally\ form specifies a `cleanup' handler.  The
+\verb\try\ clause is executed.  When no exception occurs, the
+\verb\finally\ clause is executed.  When an exception occurs in the
+\verb\try\ clause, the exception is temporarily saved, the
+\verb\finally\ clause is executed, and then the saved exception is
+re-raised.  If the \verb\finally\ clause raises another exception or
+executes a \verb\return\, \verb\break\ or \verb\continue\ statement,
+the saved exception is lost.
+\kwindex{finally}
+
+When a \verb\return\ or \verb\break\ statement is executed in the
+\verb\try\ suite of a \verb\try...finally\ statement, the
+\verb\finally\ clause is also executed `on the way out'.  A
+\verb\continue\ statement is illegal in the \verb\try\ clause.  (The
+reason is a problem with the current implementation --- this
+restriction may be lifted in the future).
+\stindex{return}
+\stindex{break}
+\stindex{continue}
+
+\section{Function definitions} \label{function}
+\indexii{function}{definition}
+
+A function definition defines a user-defined function object (see
+section \ref{types}):
+\obindex{user-defined function}
+\obindex{function}
+
+\begin{verbatim}
+funcdef:        "def" funcname "(" [parameter_list] ")" ":" suite
+parameter_list: (parameter ",")* ("*" identifier | parameter [","])
+sublist:        parameter ("," parameter)* [","]
+parameter:      identifier | "(" sublist ")"
+funcname:       identifier
+\end{verbatim}
+
+A function definition is an executable statement.  Its execution binds
+the function name in the current local name space to a function object
+(a wrapper around the executable code for the function).  This
+function object contains a reference to the current global name space
+as the global name space to be used when the function is called.
+\indexii{function}{name}
+\indexii{name}{binding}
+
+The function definition does not execute the function body; this gets
+executed only when the function is called.
+
+Function call semantics are described in section \ref{calls}.  When a
+user-defined function is called, the arguments (a.k.a. actual
+parameters) are bound to the (formal) parameters, as follows:
+\indexii{function}{call}
+\indexiii{user-defined}{function}{call}
+\index{parameter}
+\index{argument}
+\indexii{parameter}{formal}
+\indexii{parameter}{actual}
+
+\begin{itemize}
+
+\item
+If there are no formal parameters, there must be no arguments.
+
+\item
+If the formal parameter list does not end in a star followed by an
+identifier, there must be exactly as many arguments as there are
+parameters in the formal parameter list (at the top level); the
+arguments are assigned to the formal parameters one by one.  Note that
+the presence or absence of a trailing comma at the top level in either
+the formal or the actual parameter list makes no difference.  The
+assignment to a formal parameter is performed as if the parameter
+occurs on the left hand side of an assignment statement whose right
+hand side's value is that of the argument.
+
+\item
+If the formal parameter list ends in a star followed by an identifier,
+preceded by zero or more comma-followed parameters, there must be at
+least as many arguments as there are parameters preceding the star.
+Call this number {\em N}.  The first {\em N} arguments are assigned to
+the corresponding formal parameters in the way descibed above.  A
+tuple containing the remaining arguments, if any, is then assigned to
+the identifier following the star.  This variable will always be a
+tuple: if there are no extra arguments, its value is \verb\()\, if
+there is just one extra argument, it is a singleton tuple.
+\indexii{variable length}{parameter list}
+
+\end{itemize}
+
+Note that the `variable length parameter list' feature only works at
+the top level of the parameter list; individual parameters use a model
+corresponding more closely to that of ordinary assignment.  While the
+latter model is generally preferable, because of the greater type
+safety it offers (wrong-sized tuples aren't silently mistreated),
+variable length parameter lists are a sufficiently accepted practice
+in most programming languages that a compromise has been worked out.
+(And anyway, assignment has no equivalent for empty argument lists.)
+
+\section{Class definitions} \label{class}
+\indexii{class}{definition}
+
+A class definition defines a class object (see section \ref{types}):
+\obindex{class}
+
+\begin{verbatim}
+classdef:       "class" classname [inheritance] ":" suite
+inheritance:    "(" [condition_list] ")"
+classname:      identifier
+\end{verbatim}
+
+A class definition is an executable statement.  It first evaluates the
+inheritance list, if present.  Each item in the inheritance list
+should evaluate to a class object.  The class's suite is then executed
+in a new execution frame (see section \ref{execframes}), using a newly
+created local name space and the original global name space.
+(Usually, the suite contains only function definitions.)  When the
+class's suite finishes execution, its execution frame is discarded but
+its local name space is saved.  A class object is then created using
+the inheritance list for the base classes and the saved local name
+space for the attribute dictionary.  The class name is bound to this
+class object in the original local name space.
+\index{inheritance}
+\indexii{class}{name}
+\indexii{name}{binding}
+\indexii{execution}{frame}