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 ====================================