Imported from /home/lorry/working-area/delta_php2/php-5.4.13.tar.bz2.HEADphp-5.4.13master

1 files changed, 165 insertions, 0 deletions

diff --git a/README.EXT_SKEL b/README.EXT_SKEL
new file mode 100644
index 0000000..b0db843
--- /dev/null
+++ b/README.EXT_SKEL
@@ -0,0 +1,165 @@
+(NOTE: you may also want to take a look at the pear package
+	     PECL_Gen, a PHP-only alternative for this script that
+			 supports way more extension writing tasks and is 
+			 supposed to replace ext_skel completely in the long run ...)
+
+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, change to the ext/ directory of the 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 --extname=module_name
+
+  and everything you need is placed in directory module_name. 
+
+  [ Note that GNU awk is likely required for this script to work.  Debian 
+    systems seem to default to using mawk, so you may need to change the 
+    #! line in skeleton/create_stubs and the cat $proto | awk line in
+    ext_skel to use gawk explicitly. ]
+
+  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, 
+  change back up to PHP sources top directory, and do
+
+    ./buildconf; ./configure --enable-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 an argument to ext_skel
+  with option
+
+    --proto=filename.
+
+FORMAT OF FUNCTION DEFINITIONS FILE
+
+  All the definitions must be on one line. In it's simplest form, it's just
+  the function name, e.g.
+
+    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,
+  bool, double, float, 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 additional short description may be added after the parameters. 
+  If present it will be filled into the 'proto' header comments in the stubs
+  code and the <refpurpose> tag in the XML documentation.
+
+  An example:
+
+    my_function(int arg1, int arg2 [, int arg3 [, int arg4]]) this is my 1st
+
+  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.
+
+OTHER OPTIONS
+
+    --no-help
+
+  By default, ext_skel creates both comments in the source code and a test
+  function to help first time module writers to get started and testing
+  configuring and compiling their module. This option turns off all such things
+  which may just annoy experienced PHP module coders. Especially useful with
+
+    --stubs=file
+
+  which will leave out also all module specific stuff and write just function
+  stubs with function value declarations and passed argument handling, and
+  function entries and definitions at the end of the file, for copying and
+  pasting into an already existing module.
+
+    --xml[=file]
+
+  Creates the basics for phpdoc .xml file.
+
+    --full-xml
+
+  Not implemented yet. When or if there will ever be created a framework for
+  self-contained extensions to use phpdoc system for their documentation, this
+  option enables it on the created xml file.
+
+CURRENT LIMITATIONS, BUGS AND OTHER ODDITIES
+
+  Only arguments of types int, bool, double, 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 can't handle correctly, and probably never will, variable list of
+  of arguments. (void foo(int bar [, ...])
+
+  Don't trust the generated code too much. It tries to be useful in most of
+  the situations you might encounter, but automatic code generation will never
+  beat a programmer who knows the real situation at hand. ext_skel is generally
+  best suited for quickly generating a wrapper for c-library functions you
+  might want to have available in PHP too.
+
+  This program doesn't have a --help option. It has --no-help instead.
+
+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)
+{
+    char *text = NULL;
+    int argc = ZEND_NUM_ARGS();
+    int image_id = -1;
+    int text_len;
+    int font_id = -1;
+    long x;
+    long y;
+    long color;
+    zval *image = NULL;
+    zval *font = NULL;
+
+    if (zend_parse_parameters(argc TSRMLS_CC, "rsrll|l", &image, &text, &text_len, &font, &x, &y, &color) == FAILURE)
+        return;
+
+    if (image) {
+        ZEND_FETCH_RESOURCE(???, ???, image, image_id, "???", ???_rsrc_id);
+    }
+    if (font) {
+        ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id);
+    }
+
+    php_error(E_WARNING, "my_drawtext: not yet implemented");
+}
+/* }}} */
+