- Add some documentation for ext_skel and a note about it's existence.

1 files changed, 123 insertions, 0 deletions

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");
+}
+/* }}} */
+