* generic/tclParseExpr.c: Corrected parser to recognize all

boolean literals accepted by Tcl_GetBoolean, including prefixes like "y" and "f", and to allow "eq" and "ne" as function names in the proper context. [Bug 1201589].
author: dgp <dgp@users.sourceforge.net> 2005-05-20 15:29:32 (GMT)
committer: dgp <dgp@users.sourceforge.net> 2005-05-20 15:29:32 (GMT)
commit: ec92a2656e264a8588b743b96f52f8bcfeedc563 (patch)
tree: 26e4de7e43d5a02125aa0b983e411a77bf39b8e1
parent: 30e59e8121633750bc18de094d05911b08f35318 (diff)
download: tcl-ec92a2656e264a8588b743b96f52f8bcfeedc563.zip
tcl-ec92a2656e264a8588b743b96f52f8bcfeedc563.tar.gz
tcl-ec92a2656e264a8588b743b96f52f8bcfeedc563.tar.bz2
286 files changed, 78473 insertions, 0 deletions
diff --git a/Doc/library/__builtin__.rst b/Doc/library/__builtin__.rst
new file mode 100644
index 0000000..b3e1e11
--- /dev/null
+++ b/Doc/library/__builtin__.rst
@@ -0,0 +1,41 @@
+
+:mod:`__builtin__` --- Built-in objects
+=======================================
+
+.. module:: __builtin__
+   :synopsis: The module that provides the built-in namespace.
+
+
+This module provides direct access to all 'built-in' identifiers of Python; for
+example, ``__builtin__.open`` is the full name for the built-in function
+:func:`open`.  See chapter :ref:`builtin`.
+
+This module is not normally accessed explicitly by most applications, but can be
+useful in modules that provide objects with the same name as a built-in value,
+but in which the built-in of that name is also needed.  For example, in a module
+that wants to implement an :func:`open` function that wraps the built-in
+:func:`open`, this module can be used directly::
+
+   import __builtin__
+
+   def open(path):
+       f = __builtin__.open(path, 'r')
+       return UpperCaser(f)
+
+   class UpperCaser:
+       '''Wrapper around a file that converts output to upper-case.'''
+
+       def __init__(self, f):
+           self._f = f
+
+       def read(self, count=-1):
+           return self._f.read(count).upper()
+
+       # ...
+
+As an implementation detail, most modules have the name ``__builtins__`` (note
+the ``'s'``) made available as part of their globals.  The value of
+``__builtins__`` is normally either this module or the value of this modules's
+:attr:`__dict__` attribute.  Since this is an implementation detail, it may not
+be used by alternate implementations of Python.
+
diff --git a/Doc/library/__future__.rst b/Doc/library/__future__.rst
new file mode 100644
index 0000000..6bf2830
--- /dev/null
+++ b/Doc/library/__future__.rst
@@ -0,0 +1,61 @@
+
+:mod:`__future__` --- Future statement definitions
+==================================================
+
+.. module:: __future__
+   :synopsis: Future statement definitions
+
+
+:mod:`__future__` is a real module, and serves three purposes:
+
+* To avoid confusing existing tools that analyze import statements and expect to
+  find the modules they're importing.
+
+* To ensure that future_statements run under releases prior to 2.1 at least
+  yield runtime exceptions (the import of :mod:`__future__` will fail, because
+  there was no module of that name prior to 2.1).
+
+* To document when incompatible changes were introduced, and when they will be
+  --- or were --- made mandatory.  This is a form of executable documentation, and
+  can be inspected programatically via importing :mod:`__future__` and examining
+  its contents.
+
+Each statement in :file:`__future__.py` is of the form::
+
+   FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ","
+                           CompilerFlag ")"
+
+
+where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are
+5-tuples of the same form as ``sys.version_info``::
+
+   (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
+    PY_MINOR_VERSION, # the 1; an int
+    PY_MICRO_VERSION, # the 0; an int
+    PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
+    PY_RELEASE_SERIAL # the 3; an int
+   )
+
+*OptionalRelease* records the first release in which the feature was accepted.
+
+In the case of a *MandatoryRelease* that has not yet occurred,
+*MandatoryRelease* predicts the release in which the feature will become part of
+the language.
+
+Else *MandatoryRelease* records when the feature became part of the language; in
+releases at or after that, modules no longer need a future statement to use the
+feature in question, but may continue to use such imports.
+
+*MandatoryRelease* may also be ``None``, meaning that a planned feature got
+dropped.
+
+Instances of class :class:`_Feature` have two corresponding methods,
+:meth:`getOptionalRelease` and :meth:`getMandatoryRelease`.
+
+*CompilerFlag* is the (bitfield) flag that should be passed in the fourth
+argument to the builtin function :func:`compile` to enable the feature in
+dynamically compiled code.  This flag is stored in the :attr:`compiler_flag`
+attribute on :class:`_Feature` instances.
+
+No feature description will ever be deleted from :mod:`__future__`.
+
diff --git a/Doc/library/__main__.rst b/Doc/library/__main__.rst
new file mode 100644
index 0000000..a1d3c24
--- /dev/null
+++ b/Doc/library/__main__.rst
@@ -0,0 +1,17 @@
+
+:mod:`__main__` --- Top-level script environment
+================================================
+
+.. module:: __main__
+   :synopsis: The environment where the top-level script is run.
+
+
+This module represents the (otherwise anonymous) scope in which the
+interpreter's main program executes --- commands read either from standard
+input, from a script file, or from an interactive prompt.  It is this
+environment in which the idiomatic "conditional script" stanza causes a script
+to run::
+
+   if __name__ == "__main__":
+       main()
+
diff --git a/Doc/library/_ast.rst b/Doc/library/_ast.rst
new file mode 100644
index 0000000..9b195be
--- /dev/null
+++ b/Doc/library/_ast.rst
@@ -0,0 +1,59 @@
+.. _ast:
+
+Abstract Syntax Trees
+=====================
+
+.. module:: _ast
+   :synopsis: Abstract Syntax Tree classes.
+
+.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
+
+
+.. versionadded:: 2.5
+
+The ``_ast`` module helps Python applications to process trees of the Python
+abstract syntax grammar. The Python compiler currently provides read-only access
+to such trees, meaning that applications can only create a tree for a given
+piece of Python source code; generating byte code from a (potentially modified)
+tree is not supported. The abstract syntax itself might change with each Python
+release; this module helps to find out programmatically what the current grammar
+looks like.
+
+An abstract syntax tree can be generated by passing ``_ast.PyCF_ONLY_AST`` as a
+flag to the :func:`compile` builtin function. The result will be a tree of
+objects whose classes all inherit from ``_ast.AST``.
+
+The actual classes are derived from the ``Parser/Python.asdl`` file, which is
+reproduced below. There is one class defined for each left-hand side symbol in
+the abstract grammar (for example, ``_ast.stmt`` or ``_ast.expr``). In addition,
+there is one class defined for each constructor on the right-hand side; these
+classes inherit from the classes for the left-hand side trees. For example,
+``_ast.BinOp`` inherits from ``_ast.expr``. For production rules with
+alternatives (aka "sums"), the left-hand side class is abstract: only instances
+of specific constructor nodes are ever created.
+
+Each concrete class has an attribute ``_fields`` which gives the names of all
+child nodes.
+
+Each instance of a concrete class has one attribute for each child node, of the
+type as defined in the grammar. For example, ``_ast.BinOp`` instances have an
+attribute ``left`` of type ``_ast.expr``.   Instances of ``_ast.expr`` and
+``_ast.stmt`` subclasses also have lineno and col_offset attributes.  The lineno
+is the line number of source text (1 indexed so the first line is line 1) and
+the col_offset is the utf8 byte offset of the first token that generated the
+node.  The utf8 offset is recorded because the parser uses utf8  internally.
+
+If these attributes are marked as optional in the grammar (using a question
+mark), the value might be ``None``. If the attributes can have zero-or-more
+values (marked with an asterisk), the values are represented as Python lists.
+
+
+Abstract Grammar
+----------------
+
+The module defines a string constant ``__version__`` which is the decimal
+subversion revision number of the file shown below.
+
+The abstract grammar is currently defined as follows:
+
+.. literalinclude:: ../../Parser/Python.asdl
diff --git a/Doc/library/_winreg.rst b/Doc/library/_winreg.rst
new file mode 100644
index 0000000..fddbfd1
--- /dev/null
+++ b/Doc/library/_winreg.rst
@@ -0,0 +1,420 @@
+
+:mod:`_winreg` -- Windows registry access
+=========================================
+
+.. module:: _winreg
+   :platform: Windows
+   :synopsis: Routines and objects for manipulating the Windows registry.
+.. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>
+
+
+.. versionadded:: 2.0
+
+These functions expose the Windows registry API to Python.  Instead of using an
+integer as the registry handle, a handle object is used to ensure that the
+handles are closed correctly, even if the programmer neglects to explicitly
+close them.
+
+This module exposes a very low-level interface to the Windows registry; it is
+expected that in the future a new ``winreg``  module will be created offering a
+higher-level interface to the registry API.
+
+This module offers the following functions:
+
+
+.. function:: CloseKey(hkey)
+
+   Closes a previously opened registry key. The hkey argument specifies a
+   previously opened key.
+
+   Note that if *hkey* is not closed using this method (or via
+   :meth:`handle.Close`), it is closed when the *hkey* object is destroyed by
+   Python.
+
+
+.. function:: ConnectRegistry(computer_name, key)
+
+   Establishes a connection to a predefined registry handle on  another computer,
+   and returns a :dfn:`handle object`
+
+   *computer_name* is the name of the remote computer, of the  form
+   ``r"\\computername"``.  If ``None``, the local computer is used.
+
+   *key* is the predefined handle to connect to.
+
+   The return value is the handle of the opened key. If the function fails, an
+   :exc:`EnvironmentError` exception is  raised.
+
+
+.. function:: CreateKey(key, sub_key)
+
+   Creates or opens the specified key, returning a :dfn:`handle object`
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *sub_key* is a string that names the key this method opens  or creates.
+
+   If *key* is one of the predefined keys, *sub_key* may  be ``None``. In that
+   case, the handle returned is the same key handle  passed in to the function.
+
+   If the key already exists, this function opens the existing key.
+
+   The return value is the handle of the opened key. If the function fails, an
+   :exc:`EnvironmentError` exception is  raised.
+
+
+.. function:: DeleteKey(key, sub_key)
+
+   Deletes the specified key.
+
+   *key* is an already open key, or any one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *sub_key* is a string that must be a subkey of the key  identified by the *key*
+   parameter.  This value must not be  ``None``, and the key may not have subkeys.
+
+   *This method can not delete keys with subkeys.*
+
+   If the method succeeds, the entire key, including all of its values, is removed.
+   If the method fails, an :exc:`EnvironmentError`  exception is raised.
+
+
+.. function:: DeleteValue(key, value)
+
+   Removes a named value from a registry key.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *value* is a string that identifies the value to remove.
+
+
+.. function:: EnumKey(key, index)
+
+   Enumerates subkeys of an open registry key, returning a string.
+
+   *key* is an already open key, or any one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *index* is an integer that identifies the index of the key to  retrieve.
+
+   The function retrieves the name of one subkey each time it  is called.  It is
+   typically called repeatedly until an  :exc:`EnvironmentError` exception  is
+   raised, indicating, no more values are available.
+
+
+.. function:: EnumValue(key, index)
+
+   Enumerates values of an open registry key, returning a tuple.
+
+   *key* is an already open key, or any one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *index* is an integer that identifies the index of the value  to retrieve.
+
+   The function retrieves the name of one subkey each time it is  called. It is
+   typically called repeatedly, until an  :exc:`EnvironmentError` exception is
+   raised, indicating  no more values.
+
+   The result is a tuple of 3 items:
+
+   +-------+--------------------------------------------+
+   | Index | Meaning                                    |
+   +=======+============================================+
+   | ``0`` | A string that identifies the value name    |
+   +-------+--------------------------------------------+
+   | ``1`` | An object that holds the value data, and   |
+   |       | whose type depends on the underlying       |
+   |       | registry type                              |
+   +-------+--------------------------------------------+
+   | ``2`` | An integer that identifies the type of the |
+   |       | value data                                 |
+   +-------+--------------------------------------------+
+
+
+.. function:: FlushKey(key)
+
+   Writes all the attributes of a key to the registry.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   It is not necessary to call RegFlushKey to change a key. Registry changes are
+   flushed to disk by the registry using its lazy  flusher.  Registry changes are
+   also flushed to disk at system  shutdown.  Unlike :func:`CloseKey`, the
+   :func:`FlushKey` method  returns only when all the data has been written to the
+   registry. An application should only call :func:`FlushKey` if it requires
+   absolute  certainty that registry changes are on disk.
+
+   .. note::
+
+      If you don't know whether a :func:`FlushKey` call is required, it  probably
+      isn't.
+
+
+.. function:: RegLoadKey(key, sub_key, file_name)
+
+   Creates a subkey under the specified key and stores registration  information
+   from a specified file into that subkey.
+
+   *key* is an already open key, or any of the predefined :const:`HKEY_\*`
+   constants.
+
+   *sub_key* is a string that identifies the sub_key to load.
+
+   *file_name* is the name of the file to load registry data from. This file must
+   have been created with the :func:`SaveKey` function. Under the file allocation
+   table (FAT) file system, the filename may not have an extension.
+
+   A call to LoadKey() fails if the calling process does not have the
+   :const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different than
+   permissions - see the Win32 documentation for more details.
+
+   If *key* is a handle returned by :func:`ConnectRegistry`,  then the path
+   specified in *fileName* is relative to the  remote computer.
+
+   The Win32 documentation implies *key* must be in the  :const:`HKEY_USER` or
+   :const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true.
+
+
+.. function:: OpenKey(key, sub_key[, res=0][, sam=KEY_READ])
+
+   Opens the specified key, returning a :dfn:`handle object`
+
+   *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
+   constants.
+
+   *sub_key* is a string that identifies the sub_key to open.
+
+   *res* is a reserved integer, and must be zero.  The default is zero.
+
+   *sam* is an integer that specifies an access mask that describes  the desired
+   security access for the key.  Default is :const:`KEY_READ`
+
+   The result is a new handle to the specified key.
+
+   If the function fails, :exc:`EnvironmentError` is raised.
+
+
+.. function:: OpenKeyEx()
+
+   The functionality of :func:`OpenKeyEx` is provided via :func:`OpenKey`, by the
+   use of default arguments.
+
+
+.. function:: QueryInfoKey(key)
+
+   Returns information about a key, as a tuple.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   The result is a tuple of 3 items:
+
+   +-------+---------------------------------------------+
+   | Index | Meaning                                     |
+   +=======+=============================================+
+   | ``0`` | An integer giving the number of sub keys    |
+   |       | this key has.                               |
+   +-------+---------------------------------------------+
+   | ``1`` | An integer giving the number of values this |
+   |       | key has.                                    |
+   +-------+---------------------------------------------+
+   | ``2`` | A long integer giving when the key was last |
+   |       | modified (if available) as 100's of         |
+   |       | nanoseconds since Jan 1, 1600.              |
+   +-------+---------------------------------------------+
+
+
+.. function:: QueryValue(key, sub_key)
+
+   Retrieves the unnamed value for a key, as a string
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *sub_key* is a string that holds the name of the subkey with which  the value is
+   associated.  If this parameter is ``None`` or empty, the  function retrieves the
+   value set by the :func:`SetValue` method  for the key identified by *key*.
+
+   Values in the registry have name, type, and data components. This  method
+   retrieves the data for a key's first value that has a NULL name. But the
+   underlying API call doesn't return the type, Lame Lame Lame, DO NOT USE THIS!!!
+
+
+.. function:: QueryValueEx(key, value_name)
+
+   Retrieves the type and data for a specified value name associated with  an open
+   registry key.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *value_name* is a string indicating the value to query.
+
+   The result is a tuple of 2 items:
+
+   +-------+-----------------------------------------+
+   | Index | Meaning                                 |
+   +=======+=========================================+
+   | ``0`` | The value of the registry item.         |
+   +-------+-----------------------------------------+
+   | ``1`` | An integer giving the registry type for |
+   |       | this value.                             |
+   +-------+-----------------------------------------+
+
+
+.. function:: SaveKey(key, file_name)
+
+   Saves the specified key, and all its subkeys to the specified file.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *file_name* is the name of the file to save registry data to. This file cannot
+   already exist. If this filename includes an extension, it cannot be used on file
+   allocation table (FAT) file systems by the :meth:`LoadKey`, :meth:`ReplaceKey`
+   or  :meth:`RestoreKey` methods.
+
+   If *key* represents a key on a remote computer, the path  described by
+   *file_name* is relative to the remote computer. The caller of this method must
+   possess the :const:`SeBackupPrivilege`  security privilege.  Note that
+   privileges are different than permissions  - see the Win32 documentation for
+   more details.
+
+   This function passes NULL for *security_attributes* to the API.
+
+
+.. function:: SetValue(key, sub_key, type, value)
+
+   Associates a value with a specified key.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *sub_key* is a string that names the subkey with which the value  is associated.
+
+   *type* is an integer that specifies the type of the data. Currently this must be
+   :const:`REG_SZ`, meaning only strings are supported.  Use the :func:`SetValueEx`
+   function for support for other data types.
+
+   *value* is a string that specifies the new value.
+
+   If the key specified by the *sub_key* parameter does not exist, the SetValue
+   function creates it.
+
+   Value lengths are limited by available memory. Long values (more than 2048
+   bytes) should be stored as files with the filenames stored in the configuration
+   registry.  This helps the registry perform efficiently.
+
+   The key identified by the *key* parameter must have been  opened with
+   :const:`KEY_SET_VALUE` access.
+
+
+.. function:: SetValueEx(key, value_name, reserved, type, value)
+
+   Stores data in the value field of an open registry key.
+
+   *key* is an already open key, or one of the predefined  :const:`HKEY_\*`
+   constants.
+
+   *value_name* is a string that names the subkey with which the  value is
+   associated.
+
+   *type* is an integer that specifies the type of the data.   This should be one
+   of the following constants defined in this module:
+
+   +----------------------------------+---------------------------------------------+
+   | Constant                         | Meaning                                     |
+   +==================================+=============================================+
+   | :const:`REG_BINARY`              | Binary data in any form.                    |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_DWORD`               | A 32-bit number.                            |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_DWORD_LITTLE_ENDIAN` | A 32-bit number in little-endian format.    |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_DWORD_BIG_ENDIAN`    | A 32-bit number in big-endian format.       |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_EXPAND_SZ`           | Null-terminated string containing           |
+   |                                  | references to environment variables         |
+   |                                  | (``%PATH%``).                               |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_LINK`                | A Unicode symbolic link.                    |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_MULTI_SZ`            | A sequence of null-terminated strings,      |
+   |                                  | terminated by two null characters.  (Python |
+   |                                  | handles  this termination automatically.)   |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_NONE`                | No defined value type.                      |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_RESOURCE_LIST`       | A device-driver resource list.              |
+   +----------------------------------+---------------------------------------------+
+   | :const:`REG_SZ`                  | A null-terminated string.                   |
+   +----------------------------------+---------------------------------------------+
+
+   *reserved* can be anything - zero is always passed to the  API.
+
+   *value* is a string that specifies the new value.
+
+   This method can also set additional value and type information for the specified
+   key.  The key identified by the key parameter must have been opened with
+   :const:`KEY_SET_VALUE` access.
+
+   To open the key, use the :func:`CreateKeyEx` or  :func:`OpenKey` methods.
+
+   Value lengths are limited by available memory. Long values (more than 2048
+   bytes) should be stored as files with the filenames stored in the configuration
+   registry.  This helps the registry perform efficiently.
+
+
+.. _handle-object:
+
+Registry Handle Objects
+-----------------------
+
+This object wraps a Windows HKEY object, automatically closing it when the
+object is destroyed.  To guarantee cleanup, you can call either the
+:meth:`Close` method on the object, or the  :func:`CloseKey` function.
+
+All registry functions in this module return one of these objects.
+
+All registry functions in this module which accept a handle object  also accept
+an integer, however, use of the handle object is  encouraged.
+
+Handle objects provide semantics for :meth:`__bool__` - thus  ::
+
+   if handle:
+       print "Yes"
+
+will print ``Yes`` if the handle is currently valid (has not been closed or
+detached).
+
+The object also support comparison semantics, so handle objects will compare
+true if they both reference the same underlying Windows handle value.
+
+Handle objects can be converted to an integer (e.g., using the builtin
+:func:`int` function), in which case the underlying Windows handle value is
+returned.  You can also use the  :meth:`Detach` method to return the integer
+handle, and also disconnect the Windows handle from the handle object.
+
+
+.. method:: PyHKEY.Close()
+
+   Closes the underlying Windows handle.
+
+   If the handle is already closed, no error is raised.
+
+
+.. method:: PyHKEY.Detach()
+
+   Detaches the Windows handle from the handle object.
+
+   The result is an integer (or long on 64 bit Windows) that holds the value of the
+   handle before it is detached.  If the handle is already detached or closed, this
+   will return zero.
+
+   After calling this function, the handle is effectively invalidated, but the
+   handle is not closed.  You would call this function when  you need the
+   underlying Win32 handle to exist beyond the lifetime  of the handle object.
+
diff --git a/Doc/library/aepack.rst b/Doc/library/aepack.rst
new file mode 100644
index 0000000..7eaffd8
--- /dev/null
+++ b/Doc/library/aepack.rst
@@ -0,0 +1,92 @@
+
+:mod:`aepack` --- Conversion between Python variables and AppleEvent data containers
+====================================================================================
+
+.. module:: aepack
+   :platform: Mac
+   :synopsis: Conversion between Python variables and AppleEvent data containers.
+.. sectionauthor:: Vincent Marchetti <vincem@en.com>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aepack` module defines functions for converting (packing) Python
+variables to AppleEvent descriptors and back (unpacking). Within Python the
+AppleEvent descriptor is handled by Python objects of built-in type
+:class:`AEDesc`, defined in module :mod:`Carbon.AE`.
+
+The :mod:`aepack` module defines the following functions:
+
+
+.. function:: pack(x[, forcetype])
+
+   Returns an :class:`AEDesc` object  containing a conversion of Python value x. If
+   *forcetype* is provided it specifies the descriptor type of the result.
+   Otherwise, a default mapping of Python types to Apple Event descriptor types is
+   used, as follows:
+
+   +-----------------+-----------------------------------+
+   | Python type     | descriptor type                   |
+   +=================+===================================+
+   | :class:`FSSpec` | typeFSS                           |
+   +-----------------+-----------------------------------+
+   | :class:`FSRef`  | typeFSRef                         |
+   +-----------------+-----------------------------------+
+   | :class:`Alias`  | typeAlias                         |
+   +-----------------+-----------------------------------+
+   | integer         | typeLong (32 bit integer)         |
+   +-----------------+-----------------------------------+
+   | float           | typeFloat (64 bit floating point) |
+   +-----------------+-----------------------------------+
+   | string          | typeText                          |
+   +-----------------+-----------------------------------+
+   | unicode         | typeUnicodeText                   |
+   +-----------------+-----------------------------------+
+   | list            | typeAEList                        |
+   +-----------------+-----------------------------------+
+   | dictionary      | typeAERecord                      |
+   +-----------------+-----------------------------------+
+   | instance        | *see below*                       |
+   +-----------------+-----------------------------------+
+
+   If *x* is a Python instance then this function attempts to call an
+   :meth:`__aepack__` method.  This method should return an :class:`AEDesc` object.
+
+   If the conversion *x* is not defined above, this function returns the Python
+   string representation of a value (the repr() function) encoded as a text
+   descriptor.
+
+
+.. function:: unpack(x[, formodulename])
+
+   *x* must be an object of type :class:`AEDesc`. This function returns a Python
+   object representation of the data in the Apple Event descriptor *x*. Simple
+   AppleEvent data types (integer, text, float) are returned as their obvious
+   Python counterparts. Apple Event lists are returned as Python lists, and the
+   list elements are recursively unpacked.  Object references (ex. ``line 3 of
+   document 1``) are returned as instances of :class:`aetypes.ObjectSpecifier`,
+   unless ``formodulename`` is specified.  AppleEvent descriptors with descriptor
+   type typeFSS are returned as :class:`FSSpec` objects.  AppleEvent record
+   descriptors are returned as Python dictionaries, with 4-character string keys
+   and elements recursively unpacked.
+
+   The optional ``formodulename`` argument is used by the stub packages generated
+   by :mod:`gensuitemodule`, and ensures that the OSA classes for object specifiers
+   are looked up in the correct module. This ensures that if, say, the Finder
+   returns an object specifier for a window you get an instance of
+   ``Finder.Window`` and not a generic ``aetypes.Window``. The former knows about
+   all the properties and elements a window has in the Finder, while the latter
+   knows no such things.
+
+
+.. seealso::
+
+   Module :mod:`Carbon.AE`
+      Built-in access to Apple Event Manager routines.
+
+   Module :mod:`aetypes`
+      Python definitions of codes for Apple Event descriptor types.
+
+   ` Inside Macintosh: Interapplication Communication <http://developer.apple.com/techpubs/mac/IAC/IAC-2.html>`_
+      Information about inter-process communications on the Macintosh.
+
diff --git a/Doc/library/aetools.rst b/Doc/library/aetools.rst
new file mode 100644
index 0000000..b5fd4ad
--- /dev/null
+++ b/Doc/library/aetools.rst
@@ -0,0 +1,86 @@
+
+:mod:`aetools` --- OSA client support
+=====================================
+
+.. module:: aetools
+   :platform: Mac
+   :synopsis: Basic support for sending Apple Events
+.. sectionauthor:: Jack Jansen <Jack.Jansen@cwi.nl>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aetools` module contains the basic functionality on which Python
+AppleScript client support is built. It also imports and re-exports the core
+functionality of the :mod:`aetypes` and :mod:`aepack` modules. The stub packages
+generated by :mod:`gensuitemodule` import the relevant portions of
+:mod:`aetools`, so usually you do not need to import it yourself. The exception
+to this is when you cannot use a generated suite package and need lower-level
+access to scripting.
+
+The :mod:`aetools` module itself uses the AppleEvent support provided by the
+:mod:`Carbon.AE` module. This has one drawback: you need access to the window
+manager, see section :ref:`osx-gui-scripts` for details. This restriction may be
+lifted in future releases.
+
+The :mod:`aetools` module defines the following functions:
+
+
+.. function:: packevent(ae, parameters, attributes)
+
+   Stores parameters and attributes in a pre-created ``Carbon.AE.AEDesc`` object.
+   ``parameters`` and ``attributes`` are  dictionaries mapping 4-character OSA
+   parameter keys to Python objects. The objects are packed using
+   ``aepack.pack()``.
+
+
+.. function:: unpackevent(ae[, formodulename])
+
+   Recursively unpacks a ``Carbon.AE.AEDesc`` event to Python objects. The function
+   returns the parameter dictionary and the attribute dictionary. The
+   ``formodulename`` argument is used by generated stub packages to control where
+   AppleScript classes are looked up.
+
+
+.. function:: keysubst(arguments, keydict)
+
+   Converts a Python keyword argument dictionary ``arguments`` to the format
+   required by ``packevent`` by replacing the keys, which are Python identifiers,
+   by the four-character OSA keys according to the mapping specified in
+   ``keydict``. Used by the generated suite packages.
+
+
+.. function:: enumsubst(arguments, key, edict)
+
+   If the ``arguments`` dictionary contains an entry for ``key`` convert the value
+   for that entry according to dictionary ``edict``. This converts human-readable
+   Python enumeration names to the OSA 4-character codes. Used by the generated
+   suite packages.
+
+The :mod:`aetools` module defines the following class:
+
+
+.. class:: TalkTo([signature=None, start=0, timeout=0])
+
+   Base class for the proxy used to talk to an application. ``signature`` overrides
+   the class attribute ``_signature`` (which is usually set by subclasses) and is
+   the 4-char creator code defining the application to talk to. ``start`` can be
+   set to true to enable running the application on class instantiation.
+   ``timeout`` can be specified to change the default timeout used while waiting
+   for an AppleEvent reply.
+
+
+.. method:: TalkTo._start()
+
+   Test whether the application is running, and attempt to start it if not.
+
+
+.. method:: TalkTo.send(code, subcode[, parameters, attributes])
+
+   Create the AppleEvent ``Carbon.AE.AEDesc`` for the verb with the OSA designation
+   ``code, subcode`` (which are the usual 4-character strings), pack the
+   ``parameters`` and ``attributes`` into it, send it to the target application,
+   wait for the reply, unpack the reply with ``unpackevent`` and return the reply
+   appleevent, the unpacked return values as a dictionary and the return
+   attributes.
+
diff --git a/Doc/library/aetypes.rst b/Doc/library/aetypes.rst
new file mode 100644
index 0000000..0dd0a88
--- /dev/null
+++ b/Doc/library/aetypes.rst
@@ -0,0 +1,150 @@
+
+:mod:`aetypes` --- AppleEvent objects
+=====================================
+
+.. module:: aetypes
+   :platform: Mac
+   :synopsis: Python representation of the Apple Event Object Model.
+.. sectionauthor:: Vincent Marchetti <vincem@en.com>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aetypes` defines classes used to represent Apple Event data
+descriptors and Apple Event object specifiers.
+
+Apple Event data is contained in descriptors, and these descriptors are typed.
+For many descriptors the Python representation is simply the corresponding
+Python type: ``typeText`` in OSA is a Python string, ``typeFloat`` is a float,
+etc. For OSA types that have no direct Python counterpart this module declares
+classes. Packing and unpacking instances of these classes is handled
+automatically by :mod:`aepack`.
+
+An object specifier is essentially an address of an object implemented in a
+Apple Event server. An Apple Event specifier is used as the direct object for an
+Apple Event or as the argument of an optional parameter. The :mod:`aetypes`
+module contains the base classes for OSA classes and properties, which are used
+by the packages generated by :mod:`gensuitemodule` to populate the classes and
+properties in a given suite.
+
+For reasons of backward compatibility, and for cases where you need to script an
+application for which you have not generated the stub package this module also
+contains object specifiers for a number of common OSA classes such as
+``Document``, ``Window``, ``Character``, etc.
+
+The :mod:`AEObjects` module defines the following classes to represent Apple
+Event descriptor data:
+
+
+.. class:: Unknown(type, data)
+
+   The representation of OSA descriptor data for which the :mod:`aepack` and
+   :mod:`aetypes` modules have no support, i.e. anything that is not represented by
+   the other classes here and that is not equivalent to a simple Python value.
+
+
+.. class:: Enum(enum)
+
+   An enumeration value with the given 4-character string value.
+
+
+.. class:: InsertionLoc(of, pos)
+
+   Position ``pos`` in object ``of``.
+
+
+.. class:: Boolean(bool)
+
+   A boolean.
+
+
+.. class:: StyledText(style, text)
+
+   Text with style information (font, face, etc) included.
+
+
+.. class:: AEText(script, style, text)
+
+   Text with script system and style information included.
+
+
+.. class:: IntlText(script, language, text)
+
+   Text with script system and language information included.
+
+
+.. class:: IntlWritingCode(script, language)
+
+   Script system and language information.
+
+
+.. class:: QDPoint(v, h)
+
+   A quickdraw point.
+
+
+.. class:: QDRectangle(v0, h0, v1, h1)
+
+   A quickdraw rectangle.
+
+
+.. class:: RGBColor(r, g, b)
+
+   A color.
+
+
+.. class:: Type(type)
+
+   An OSA type value with the given 4-character name.
+
+
+.. class:: Keyword(name)
+
+   An OSA keyword with the given 4-character name.
+
+
+.. class:: Range(start, stop)
+
+   A range.
+
+
+.. class:: Ordinal(abso)
+
+   Non-numeric absolute positions, such as ``"firs"``, first, or ``"midd"``,
+   middle.
+
+
+.. class:: Logical(logc, term)
+
+   The logical expression of applying operator ``logc`` to ``term``.
+
+
+.. class:: Comparison(obj1, relo, obj2)
+
+   The comparison ``relo`` of ``obj1`` to ``obj2``.
+
+The following classes are used as base classes by the generated stub packages to
+represent AppleScript classes and properties in Python:
+
+
+.. class:: ComponentItem(which[, fr])
+
+   Abstract baseclass for an OSA class. The subclass should set the class attribute
+   ``want`` to the 4-character OSA class code. Instances of subclasses of this
+   class are equivalent to AppleScript Object Specifiers. Upon instantiation you
+   should pass a selector in ``which``, and optionally a parent object in ``fr``.
+
+
+.. class:: NProperty(fr)
+
+   Abstract baseclass for an OSA property. The subclass should set the class
+   attributes ``want`` and ``which`` to designate which property we are talking
+   about. Instances of subclasses of this class are Object Specifiers.
+
+
+.. class:: ObjectSpecifier(want, form, seld[, fr])
+
+   Base class of ``ComponentItem`` and ``NProperty``, a general OSA Object
+   Specifier. See the Apple Open Scripting Architecture documentation for the
+   parameters. Note that this class is not abstract.
+
diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst
new file mode 100644
index 0000000..0cfcb52
--- /dev/null
+++ b/Doc/library/aifc.rst
@@ -0,0 +1,225 @@
+
+:mod:`aifc` --- Read and write AIFF and AIFC files
+==================================================
+
+.. module:: aifc
+   :synopsis: Read and write audio files in AIFF or AIFC format.
+
+
+.. index::
+   single: Audio Interchange File Format
+   single: AIFF
+   single: AIFF-C
+
+This module provides support for reading and writing AIFF and AIFF-C files.
+AIFF is Audio Interchange File Format, a format for storing digital audio
+samples in a file.  AIFF-C is a newer version of the format that includes the
+ability to compress the audio data.
+
+**Caveat:**  Some operations may only work under IRIX; these will raise
+:exc:`ImportError` when attempting to import the :mod:`cl` module, which is only
+available on IRIX.
+
+Audio files have a number of parameters that describe the audio data. The
+sampling rate or frame rate is the number of times per second the sound is
+sampled.  The number of channels indicate if the audio is mono, stereo, or
+quadro.  Each frame consists of one sample per channel.  The sample size is the
+size in bytes of each sample.  Thus a frame consists of
+*nchannels*\**samplesize* bytes, and a second's worth of audio consists of
+*nchannels*\**samplesize*\**framerate* bytes.
+
+For example, CD quality audio has a sample size of two bytes (16 bits), uses two
+channels (stereo) and has a frame rate of 44,100 frames/second.  This gives a
+frame size of 4 bytes (2\*2), and a second's worth occupies 2\*2\*44100 bytes
+(176,400 bytes).
+
+Module :mod:`aifc` defines the following function:
+
+
+.. function:: open(file[, mode])
+
+   Open an AIFF or AIFF-C file and return an object instance with methods that are
+   described below.  The argument *file* is either a string naming a file or a file
+   object.  *mode* must be ``'r'`` or ``'rb'`` when the file must be opened for
+   reading, or ``'w'``  or ``'wb'`` when the file must be opened for writing.  If
+   omitted, ``file.mode`` is used if it exists, otherwise ``'rb'`` is used.  When
+   used for writing, the file object should be seekable, unless you know ahead of
+   time how many samples you are going to write in total and use
+   :meth:`writeframesraw` and :meth:`setnframes`.
+
+Objects returned by :func:`open` when a file is opened for reading have the
+following methods:
+
+
+.. method:: aifc.getnchannels()
+
+   Return the number of audio channels (1 for mono, 2 for stereo).
+
+
+.. method:: aifc.getsampwidth()
+
+   Return the size in bytes of individual samples.
+
+
+.. method:: aifc.getframerate()
+
+   Return the sampling rate (number of audio frames per second).
+
+
+.. method:: aifc.getnframes()
+
+   Return the number of audio frames in the file.
+
+
+.. method:: aifc.getcomptype()
+
+   Return a four-character string describing the type of compression used in the
+   audio file.  For AIFF files, the returned value is ``'NONE'``.
+
+
+.. method:: aifc.getcompname()
+
+   Return a human-readable description of the type of compression used in the audio
+   file.  For AIFF files, the returned value is ``'not compressed'``.
+
+
+.. method:: aifc.getparams()
+
+   Return a tuple consisting of all of the above values in the above order.
+
+
+.. method:: aifc.getmarkers()
+
+   Return a list of markers in the audio file.  A marker consists of a tuple of
+   three elements.  The first is the mark ID (an integer), the second is the mark
+   position in frames from the beginning of the data (an integer), the third is the
+   name of the mark (a string).
+
+
+.. method:: aifc.getmark(id)
+
+   Return the tuple as described in :meth:`getmarkers` for the mark with the given
+   *id*.
+
+
+.. method:: aifc.readframes(nframes)
+
+   Read and return the next *nframes* frames from the audio file.  The returned
+   data is a string containing for each frame the uncompressed samples of all
+   channels.
+
+
+.. method:: aifc.rewind()
+
+   Rewind the read pointer.  The next :meth:`readframes` will start from the
+   beginning.
+
+
+.. method:: aifc.setpos(pos)
+
+   Seek to the specified frame number.
+
+
+.. method:: aifc.tell()
+
+   Return the current frame number.
+
+
+.. method:: aifc.close()
+
+   Close the AIFF file.  After calling this method, the object can no longer be
+   used.
+
+Objects returned by :func:`open` when a file is opened for writing have all the
+above methods, except for :meth:`readframes` and :meth:`setpos`.  In addition
+the following methods exist.  The :meth:`get\*` methods can only be called after
+the corresponding :meth:`set\*` methods have been called.  Before the first
+:meth:`writeframes` or :meth:`writeframesraw`, all parameters except for the
+number of frames must be filled in.
+
+
+.. method:: aifc.aiff()
+
+   Create an AIFF file.  The default is that an AIFF-C file is created, unless the
+   name of the file ends in ``'.aiff'`` in which case the default is an AIFF file.
+
+
+.. method:: aifc.aifc()
+
+   Create an AIFF-C file.  The default is that an AIFF-C file is created, unless
+   the name of the file ends in ``'.aiff'`` in which case the default is an AIFF
+   file.
+
+
+.. method:: aifc.setnchannels(nchannels)
+
+   Specify the number of channels in the audio file.
+
+
+.. method:: aifc.setsampwidth(width)
+
+   Specify the size in bytes of audio samples.
+
+
+.. method:: aifc.setframerate(rate)
+
+   Specify the sampling frequency in frames per second.
+
+
+.. method:: aifc.setnframes(nframes)
+
+   Specify the number of frames that are to be written to the audio file. If this
+   parameter is not set, or not set correctly, the file needs to support seeking.
+
+
+.. method:: aifc.setcomptype(type, name)
+
+   .. index::
+      single: u-LAW
+      single: A-LAW
+      single: G.722
+
+   Specify the compression type.  If not specified, the audio data will not be
+   compressed.  In AIFF files, compression is not possible.  The name parameter
+   should be a human-readable description of the compression type, the type
+   parameter should be a four-character string.  Currently the following
+   compression types are supported: NONE, ULAW, ALAW, G722.
+
+
+.. method:: aifc.setparams(nchannels, sampwidth, framerate, comptype, compname)
+
+   Set all the above parameters at once.  The argument is a tuple consisting of the
+   various parameters.  This means that it is possible to use the result of a
+   :meth:`getparams` call as argument to :meth:`setparams`.
+
+
+.. method:: aifc.setmark(id, pos, name)
+
+   Add a mark with the given id (larger than 0), and the given name at the given
+   position.  This method can be called at any time before :meth:`close`.
+
+
+.. method:: aifc.tell()
+
+   Return the current write position in the output file.  Useful in combination
+   with :meth:`setmark`.
+
+
+.. method:: aifc.writeframes(data)
+
+   Write data to the output file.  This method can only be called after the audio
+   file parameters have been set.
+
+
+.. method:: aifc.writeframesraw(data)
+
+   Like :meth:`writeframes`, except that the header of the audio file is not
+   updated.
+
+
+.. method:: aifc.close()
+
+   Close the AIFF file.  The header of the file is updated to reflect the actual
+   size of the audio data. After calling this method, the object can no longer be
+   used.
+
diff --git a/Doc/library/allos.rst b/Doc/library/allos.rst
new file mode 100644
index 0000000..900d6d3
--- /dev/null
+++ b/Doc/library/allos.rst
@@ -0,0 +1,27 @@
+
+.. _allos:
+
+*********************************
+Generic Operating System Services
+*********************************
+
+The modules described in this chapter provide interfaces to operating system
+features that are available on (almost) all operating systems, such as files and
+a clock.  The interfaces are generally modeled after the Unix or C interfaces,
+but they are available on most other systems as well.  Here's an overview:
+
+
+.. toctree::
+
+   os.rst
+   time.rst
+   optparse.rst
+   getopt.rst
+   logging.rst
+   getpass.rst
+   curses.rst
+   curses.ascii.rst
+   curses.panel.rst
+   platform.rst
+   errno.rst
+   ctypes.rst
diff --git a/Doc/library/anydbm.rst b/Doc/library/anydbm.rst
new file mode 100644
index 0000000..413b7de
--- /dev/null
+++ b/Doc/library/anydbm.rst
@@ -0,0 +1,96 @@
+
+:mod:`anydbm` --- Generic access to DBM-style databases
+=======================================================
+
+.. module:: anydbm
+   :synopsis: Generic interface to DBM-style database modules.
+
+
+.. index::
+   module: dbhash
+   module: bsddb
+   module: gdbm
+   module: dbm
+   module: dumbdbm
+
+:mod:`anydbm` is a generic interface to variants of the DBM database ---
+:mod:`dbhash` (requires :mod:`bsddb`), :mod:`gdbm`, or :mod:`dbm`.  If none of
+these modules is installed, the slow-but-simple implementation in module
+:mod:`dumbdbm` will be used.
+
+
+.. function:: open(filename[, flag[, mode]])
+
+   Open the database file *filename* and return a corresponding object.
+
+   If the database file already exists, the :mod:`whichdb` module is  used to
+   determine its type and the appropriate module is used; if it does not exist, the
+   first module listed above that can be imported is used.
+
+   The optional *flag* argument can be ``'r'`` to open an existing database for
+   reading only, ``'w'`` to open an existing database for reading and writing,
+   ``'c'`` to create the database if it doesn't exist, or ``'n'``, which will
+   always create a new empty database.  If not specified, the default value is
+   ``'r'``.
+
+   The optional *mode* argument is the Unix mode of the file, used only when the
+   database has to be created.  It defaults to octal ``0666`` (and will be modified
+   by the prevailing umask).
+
+
+.. exception:: error
+
+   A tuple containing the exceptions that can be raised by each of the supported
+   modules, with a unique exception also named :exc:`anydbm.error` as the first
+   item --- the latter is used when :exc:`anydbm.error` is raised.
+
+The object returned by :func:`open` supports most of the same functionality as
+dictionaries; keys and their corresponding values can be stored, retrieved, and
+deleted, and the :meth:`has_key` and :meth:`keys` methods are available.  Keys
+and values must always be strings.
+
+The following example records some hostnames and a corresponding title,  and
+then prints out the contents of the database::
+
+   import anydbm
+
+   # Open database, creating it if necessary.
+   db = anydbm.open('cache', 'c')
+
+   # Record some values
+   db['www.python.org'] = 'Python Website'
+   db['www.cnn.com'] = 'Cable News Network'
+
+   # Loop through contents.  Other dictionary methods
+   # such as .keys(), .values() also work.
+   for k, v in db.iteritems():
+       print k, '\t', v
+
+   # Storing a non-string key or value will raise an exception (most
+   # likely a TypeError).
+   db['www.yahoo.com'] = 4
+
+   # Close when done.
+   db.close()
+
+
+.. seealso::
+
+   Module :mod:`dbhash`
+      BSD ``db`` database interface.
+
+   Module :mod:`dbm`
+      Standard Unix database interface.
+
+   Module :mod:`dumbdbm`
+      Portable implementation of the ``dbm`` interface.
+
+   Module :mod:`gdbm`
+      GNU database interface, based on the ``dbm`` interface.
+
+   Module :mod:`shelve`
+      General object persistence built on top of  the Python ``dbm`` interface.
+
+   Module :mod:`whichdb`
+      Utility module used to determine the type of an existing database.
+
diff --git a/Doc/library/archiving.rst b/Doc/library/archiving.rst
new file mode 100644
index 0000000..7d0df5f
--- /dev/null
+++ b/Doc/library/archiving.rst
@@ -0,0 +1,18 @@
+
+.. _archiving:
+
+******************************
+Data Compression and Archiving
+******************************
+
+The modules described in this chapter support data compression with the zlib,
+gzip, and bzip2 algorithms, and  the creation of ZIP- and tar-format archives.
+
+
+.. toctree::
+
+   zlib.rst
+   gzip.rst
+   bz2.rst
+   zipfile.rst
+   tarfile.rst
diff --git a/Doc/library/array.rst b/Doc/library/array.rst
new file mode 100644
author	dgp <dgp@users.sourceforge.net>	2005-05-20 15:29:32 (GMT)
committer	dgp <dgp@users.sourceforge.net>	2005-05-20 15:29:32 (GMT)
commit	ec92a2656e264a8588b743b96f52f8bcfeedc563 (patch)
tree	26e4de7e43d5a02125aa0b983e411a77bf39b8e1
parent	30e59e8121633750bc18de094d05911b08f35318 (diff)
download	tcl-ec92a2656e264a8588b743b96f52f8bcfeedc563.zip tcl-ec92a2656e264a8588b743b96f52f8bcfeedc563.tar.gz tcl-ec92a2656e264a8588b743b96f52f8bcfeedc563.tar.bz2