From d09ec3261f1b2c2f88ee7fa6bff34859c1f0bc58 Mon Sep 17 00:00:00 2001 From: Jouni Ahto Date: Sat, 10 Jun 2000 08:59:43 +0000 Subject: - Add some documentation for ext_skel and a note about it's existence. --- README.EXT_SKEL | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 README.EXT_SKEL (limited to 'README.EXT_SKEL') diff --git a/README.EXT_SKEL b/README.EXT_SKEL new file mode 100644 index 0000000000..2b0fd48f94 --- /dev/null +++ b/README.EXT_SKEL @@ -0,0 +1,123 @@ + +WHAT IT IS + + It's a tool for automatically creating the basic framework for a PHP module + and writing C code handling arguments passed to your functions from a simple + configuration file. See an example at the end of this file. + +HOW TO USE IT + + Very simple. First, cd do directory ext/ in PHP 4 sources. If you just need + the basic framework and will be writing all the code in your functions + yourself, you can now do './ext_skel your_module_name' and everything you + need is placed in directory your_module_name. In fact, if you don't need to + test the existence of any external header files, libraries or functions in + them, the module is already almost ready to be compiled in PHP. Just remove + 3 comments in your_module_name/config.m4, cd back up to PHP sources top + directory, and do './buildconf; ./configure --enable-your_module_name; make'. + + But if you already have planned the overall scheme of your module, what + functions it will contain, their return types and the arguments they take + (a very good idea) and don't want to bother yourself with creating function + definitions and handling arguments passed yourself, it's time to create a + function definitions file, which you will give as the second argument to + ext_skel. + +FORMAT OF FUNCTION DEFINITIONS FILE + + All the definitions must be on one line. In it's simplest form, it's just + the function name, ie. + + my_function + + but then you'll be left with an almost empty function body without any + argument handling. + + Arguments are given in parenthesis after the function name, and are of + the form 'argument_type argument_name'. Arguments are separated from each + other with a comma and optional space. Argument_type can be one of int, + double, string, array, object or mixed. + + An optional argument is separated from the previous by an optional space, + then '[' and of course comma and optional space, like all the other + arguments. You should close a row of optional arguments with same amount of + ']'s as there where '['s. Currently, it does not harm if you forget to do it + or there is a wrong amount of ']'s, but this may change in the future. + + An example: + + my_function(int arg1, int arg2 [, int arg3 [, int arg4]]) + + Arguments arg3 and arg4 are optional. + + If possible, the function definition should also contain it's return type + in front of the definition. It's not actually used for any C code generating + purposes but PHP in-source documentation instead, and as such, very useful. + It can be any of int, double, string, bool, array, object, resource, mixed + or void. + + The file must contain nothing else but function definitions, no comments or + empty lines. + +CURRENT LIMITATIONS AND BUGS + + Only arguments of types int, float, string and array are handled. For other + types you must write the code yourself. And for type mixed, it wouldn't even + be possible to write anything, because only you know what to expect. + + It doesn't yet handle correctly grouped optional arguments, ie. it thinks + 'type function(type arg1 [, type arg2, type arg3]' to actually be + 'type function(type arg1 [, type arg2 [, type arg3]]', so you have to + manually correct the switch construct created. But it's nothing more than + deleting a few 'case ?:' lines and fixing PHP in-source documentation proto. + + It creates incorrect code to handle arguments passed to function when an + optional argument is of type 'resource'. + +EXAMPLE + + The following _one_ line + + bool my_drawtext(resource image, string text, resource font, int x, int y [, int color]) + + will create this function definition for you (note that there are a few + question marks to be replaced by you, and you must of course add your own + value definitions too): + +/* {{{ proto bool my_drawtext(resource image, string text, resource font, int x, int y[, int color]) + */ +PHP_FUNCTION(my_drawtext) +{ + zval **image, **text, **font, **x, **y, **color; + int argc; + int image_id = -1; + int font_id = -1; + ???LS_FETCH(); + + argc = ZEND_NUM_ARGS(); + if (argc < 5 || argc > 6 || zend_get_parameters_ex(argc, &image, &text, &font, &x, &y, &color) == FAILURE) { + WRONG_PARAM_COUNT; + } + + ZEND_FETCH_RESOURCE(???, ???, image, image_id, "???", ???G()); + ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???G()); + + switch (argc) { + case 6: + convert_to_long_ex(color); + /* Fall-through. */ + case 5: + convert_to_long_ex(y); + convert_to_long_ex(x); + /* font: fetching resources already handled. */ + convert_to_string_ex(text); + /* image: fetching resources already handled. */ + break; + default: + WRONG_PARAM_COUNT; + } + + php_error(E_WARNING, "my_drawtext: not yet implemented"); +} +/* }}} */ + -- cgit v1.2.1