Index: pep-3118.txt
===================================================================
--- pep-3118.txt (revision 78193)
+++ pep-3118.txt (working copy)
@@ -637,9 +637,54 @@
ctypes and NumPy for example). The Python 2.5 specification is
at http://docs.python.org/library/struct.html.
-Here are the proposed additions:
+The grammar of the original struct string-syntax is very simple. It consist of
+a byte-order specifier followed by a character code which may optionally be
+preceded by a numeric count::
+ struct-string ::= ( )*
+ byte-order-specifier ::= '!' | '@' | '=' | '>' | '<' | '^'
+ count ::=
+ code ::= 'x' | 'c' | 'b' | 'B' | '?' | 'h' | 'H' | 'i' | 'I' | 'l' | 'L'
+ | 'q' | 'Q' | 'f' | 'd' | 's' | 'p' | 'P'
+The proposed additions will extend this syntax by adding support for new
+primitive types, name specifiers, detailed structure layout, and
+function-pointers. The high-level structure of the new syntax is::
+
+ struct-string ::= ( ?)*
+ type-string ::=
+ |
+ |
+
+The struct module will be changed to understand this new syntax and
+return appropriate Python objects on unpacking. White-space in the
+struct-string syntax will be ignored, if it isn't already. The details
+of the grammar elements *primitive*, *name-specifier*, *structure*,
+and *pointer-to-function* are described in the following sub-sections.
+
+In addition to implementing this new syntax, functions should be added to
+ctypes to create a ctypes object from a struct description, and add
+long-double, and ucs-2 to ctypes.
+
+Primitive Extensions
+---------------------
+
+The extenstions to the primitive data types will provide new type codes,
+the ability to change byte-order mid-stream, and a way to specify pointers
+to data::
+
+ primitive ::= ? ? +
+ byte-order-specifier ::= '!' | '@' | '=' | '>' | '<' | '^'
+ count ::=
+ pointer-specifier ::= '&'
+ array-specifier ::= '(' (',' )* ')'
+ code ::= 'x' | 'c' | 'b' | 'B' | '?' | 'h' | 'H' | 'i' | 'I' | 'l' | 'L'
+ | 'q' | 'Q' | 'f' | 'd' | 's' | 'p' | 'P' | 't' | 'g' | 'u' | 'w'
+ | 'O' | 'Z'
+
+The new *code* types and modifications to old *code* types are described as
+follows:
+
================ ===========
Character Description
================ ===========
@@ -650,45 +695,75 @@
'u' ucs-2
'w' ucs-4
'O' pointer to Python Object
-'Z' complex (whatever the next specifier is)
-'&' specific pointer (prefix before another character)
-'T{}' structure (detailed layout inside {})
-'(k1,k2,...,kn)' multi-dimensional array of whatever follows
-':name:' optional name of the preceeding element
-'X{}' pointer to a function (optional function
- signature inside {} with any return value
- preceeded by -> and placed at the end)
+'Z' complex
================ ===========
-The struct module will be changed to understand these as well and
-return appropriate Python objects on unpacking. Unpacking a
-long-double will return a decimal object or a ctypes long-double.
-Unpacking 'u' or 'w' will return Python unicode. Unpacking a
-multi-dimensional array will return a list (of lists if >1d).
-Unpacking a pointer will return a ctypes pointer object. Unpacking a
-function pointer will return a ctypes call-object (perhaps). Unpacking
-a bit will return a Python Bool. White-space in the struct-string
-syntax will be ignored if it isn't already. Unpacking a named-object
-will return some kind of named-tuple-like object that acts like a
-tuple but whose entries can also be accessed by name. Unpacking a
-nested structure will return a nested tuple.
+The *pointer-specifier* is used to denote a pointer to a specified type.
+For example, '&g' represents a pointer to a long-double and '&&I' respresents
+a pointer to a pointer to an unsigned integer.
-Endian-specification ('!', '@','=','>','<', '^') is also allowed
-inside the string so that it can change if needed. The
-previously-specified endian string is in force until changed. The
-default endian is '@' which means native data-types and alignment. If
-un-aligned, native data-types are requested, then the endian
+The *array-specifier* is used to denote homogenous multi-dimensional areas
+of memory. The type-code immediately following the array-specifier denotes
+the type of the elements in that memory area. This extension also allows
+specifying if the data is supposed to be viewed as a (C-style contiguous,
+last-dimension varies the fastest) multi-dimensional array of a particular
+format.
+
+The *byte-order-specifier* is now allowed inside the string so that it can
+change if needed. The previously specified byte-order specifier is in force
+until changed. The default byte-order is '@' which means native data-types and
+alignment. If un-aligned, native data-types are requested, then the byte-order
specification is '^'.
-According to the struct-module, a number can preceed a character
-code to specify how many of that type there are. The
-``(k1,k2,...,kn)`` extension also allows specifying if the data is
-supposed to be viewed as a (C-style contiguous, last-dimension
-varies the fastest) multi-dimensional array of a particular format.
+The following unpacking requirements must be met:
-Functions should be added to ctypes to create a ctypes object from
-a struct description, and add long-double, and ucs-2 to ctypes.
+* a long-double will return a decimal object or a ctypes long-double.
+* 'u' or 'w' will return Python unicode.
+* a multi-dimensional array will return a list (of lists if >1d).
+* a pointer will return a ctypes pointer object.
+* a bit will return a Python Bool.
+* a pointer to a Python Object will return the Python Object associated with
+ the address encoded in the struct-string if a Python Object of that address
+ exist. Otherwise, None is returned.
+Named Specifier
+---------------
+The name specifier is used to associate names with values in the struct-string::
+
+ name-specifier := ':' ':'
+
+The following unpacking requirements must be met:
+
+* a named-object will return some kind of named-tuple-like object
+ that acts like a tuple but whose entries can also be accessed by name.
+
+
+Structure Layout
+----------------
+The new structure layout syntax provides a way to specify a detailed
+structure layout::
+
+ structure := 'T' '{' '}'
+
+Structures may be arbitrarily nested.
+
+The following unpacking requirements must be met:
+
+* Unpacking a nested structure will return a nested tuple.
+
+
+Pointer to Functions
+--------------------
+The pointer to a function syntax provides a way to specify ...::
+
+ pointer-to-function := 'X' '{' ? '}
+ signature := '->'
+
+The following unpacking requirements must be met:
+
+* a function pointer will return a ctypes call-object (perhaps).
+
+
Examples of Data-Format Descriptions
====================================