Permalink
Browse files

Adding some docs for new parameter parsing API. They really should be…

… more

fleshed out.
  • Loading branch information...
1 parent 801cadc commit 27d63c5b8debcb5a491dd054b5b4f04526e515f8 Andrei Zmievski committed Oct 22, 2001
Showing with 101 additions and 0 deletions.
  1. +101 −0 README.PARAMETER_PARSING_API
@@ -0,0 +1,101 @@
+New parameter parsing functions
+===============================
+
+It should be easier to parse input parameters to an extension function.
+Hence, borrowing from Python's example, there are now a set of functions
+that given the string of type specifiers, can parse the input parameters
+and store the results in the user specified variables. This avoids most
+of the IS_* checks and convert_to_* conversions. The functions also
+check for the appropriate number of parameters, and try to output
+meaningful error messages.
+
+
+Prototypes
+----------
+/* Implemented. */
+zend_parse_parameters(int num_args, char *type_spec, ...);
+zend_parse_parameters_ex(int flags, int num_args, char *type_spec, ...);
+
+/* Not implemented yet. */
+zend_parse_parameters_hash(HashTable *ht, char *type_spec, ...);
+zend_parse_parameters_hash_ex(int flags, HashTable *ht, char *type_spec, ...);
+
+
+The zend_parse_parameters() function takes the number of parameters
+passed to the extension function, the type specifier string, and the
+list of pointers to variables to store the results in. The _ex() version
+also takes 'flags' argument -- current only ZEND_PARSE_PARAMS_QUIET can
+be used as 'flags' to specify that the function should operate quietly
+and not output any error messages.
+
+The auto-conversions are performed as necessary. Arrays, objects, and
+resources cannot be autoconverted.
+
+
+Type specifiers
+---------------
+ l - long
+ d - double
+ s - string (with possible null bytes) and its length
+ b - boolean, stored in zend_bool
+ r - resource (stored in zval)
+ a - array
+ o - object (of any type)
+ O - object (of specific type, specified by class entry)
+ z - the actual zval
+
+ The following characters also have a meaning in the specifier string:
+ | - indicates that the remaining parameters are optional, they
+ should be initialized to default values by the extension since they
+ will not be touched by the parsing function if they are not
+ passed to it.
+ / - use SEPARATE_ZVAL_IF_NOT_REF() on the parameter it follows
+ ! - the parameter it follows can be of specified type or NULL (only applies
+ to 'a', 'o', 'O', 'r', and 'z'). If NULL is passed, the results
+ pointer is set to NULL as well.
+
+Examples
+--------
+/* Gets a long, a string and its length, and a zval */
+long l;
+char *s;
+int s_len;
+zval *param;
+zend_parse_parameters(ZEND_NUM_ARGS(), "lsz", &l, &s, &s_len, &param);
+
+
+/* Gets an object of class specified by my_ce, and an optional double. */
+zval *obj;
+double d = 0.5;
+zend_parse_parameters(ZEND_NUM_ARGS(), "O|d", &obj, my_ce, &d);
+
+
+/* Gets an object or null, and an array.
+ If null is passed for object, obj will be set to NULL. */
+zval *obj;
+zval *arr;
+zend_parse_parameters(ZEND_NUM_ARGS(), "O!a", &obj, &arr);
+
+
+/* Gets a separated array. */
+zval *arr;
+zend_parse_parameters(ZEND_NUM_ARGS(), "a/", &arr));
+
+
+/* Get only the first three parameters (useful for varargs functions). */
+zval *z;
+zend_bool b;
+zval *r;
+zend_parse_parameters(3, "zbr!", &z, &b, &r);
+
+
+/* Get either a set of 3 longs or a string. */
+long l1, l2, l3;
+char *s;
+if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(), "lll", &l1, &l2, &l3)) {
+ /* manipulate longs */
+} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(), "s", &s)) {
+ /* manipulate string */
+} else {
+ /* output error */
+}

0 comments on commit 27d63c5

Please sign in to comment.