summaryrefslogtreecommitdiff
path: root/README.EXT_SKEL
diff options
context:
space:
mode:
authorJouni Ahto <jah@php.net>2000-06-15 01:57:23 (GMT)
committerJouni Ahto <jah@php.net>2000-06-15 01:57:23 (GMT)
commit495a957c99cc49677979e19920900e2b0a62a76c (patch)
treeb5b3f269bc6d6d3f2362e98291814b03b518b083 /README.EXT_SKEL
parent9ded807a20a48d4482d21bea8cb4cc24f20f04bc (diff)
downloadphp-495a957c99cc49677979e19920900e2b0a62a76c.tar.gz
- Fixed incorrect code generated when all parameters are optional.
- Fixed handling of grouped optional parameters. - Added an option to generate xml documentation. - Added an option not to be nice and helpful and create all kinds of comments and testing functions. - Added on option to create function stubs only. - Added options --assing-params and --string-lens that change the generated code. - Updated documentation.
Diffstat (limited to 'README.EXT_SKEL')
-rw-r--r--README.EXT_SKEL97
1 files changed, 79 insertions, 18 deletions
diff --git a/README.EXT_SKEL b/README.EXT_SKEL
index 736bfc5..9f3a2e5 100644
--- a/README.EXT_SKEL
+++ b/README.EXT_SKEL
@@ -9,19 +9,26 @@ 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'.
+ yourself, you can now do
+
+ ./ext_skel --extname=module_name
+
+ and everything you need is placed in directory 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-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.
+ function definitions file, which you will give as an argument to ext_skel
+ with option
+
+ --proto=filename.
FORMAT OF FUNCTION DEFINITIONS FILE
@@ -36,7 +43,7 @@ FORMAT OF FUNCTION DEFINITIONS FILE
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.
+ 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
@@ -59,17 +66,71 @@ FORMAT OF FUNCTION DEFINITIONS FILE
The file must contain nothing else but function definitions, no comments or
empty lines.
-CURRENT LIMITATIONS AND BUGS
+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.
+
+ --assign-params
+ --string-lens
+
+ By default, function proto 'void foo(string bar)' creates the following:
+ ...
+ zval **bar;
+ ... (zend_get_parameters_ex() called in the middle...)
+ convert_to_string_ex(bar);
- 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.
+ Specifying both of these options changes the generated code to:
+ ...
+ zval **bar_arg;
+ int bar_len;
+ char *bar = NULL;
+ ... (zend_get_parameters_ex() called in the middle...)
+ convert_to_string_ex(bar_arg);
+ bar = Z_STRVAL_PP(bar_arg);
+ bar_len = Z_STRLEN_PP(bar_arg);
+
+ You shouldn't have to ask what happens if you leave --string-lens out. If you
+ have to, it's questionable whether you should be reading this document.
+
+ --with-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 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 can't handle correctly, and probably never will, variable list of
+ of arguments. (void foo(int bar [, ...])
+
+ Don't trust too much the generated code. It tries to be useful in most of
+ the situations you might encounter, but automatic code generating will never
+ beat a programmer who knows the real situation at hand. axt_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