autodoc.git/ autodoc.xml

Branch: Tag:

1996-11-06

1996-11-06 21:23:39 by Fredrik Hübinette (Hubbe) <hubbe@hubbe.net>

more documentation added

Rev: doc/internal/array/aggregate_array:1.1
Rev: doc/internal/array/array_index:1.2
Rev: doc/internal/array/array_remove:1.1
Rev: doc/internal/array/array_search:1.1
Rev: doc/internal/array/array_set_index:1.1
Rev: doc/internal/array/copy_array:1.1
Rev: doc/internal/array/push_array_items:1.1
Rev: doc/internal/array/resize_array:1.1
Rev: doc/internal/array/slice_array:1.1
Rev: doc/internal/pike/types:1.1
Rev: doc/internal/program/add_function:1.1
Rev: doc/internal/program/add_storage:1.1
Rev: doc/internal/program/end_c_program:1.1
Rev: doc/internal/program/set_exit_callback:1.1
Rev: doc/internal/program/set_init_callback:1.1
Rev: doc/internal/program/start_new_program:1.1

27:      </doc>   </docgroup> + <docgroup homogen-name='add_function' homogen-type='method'> + <method name='add_function'/><doc placeholder='true'> + <text> + <p><tt>add_function</tt> - add a function to the program</p> +  + <tt><p>#include "program.h"<br/> +  + </p> + <p>void add_function(char *name,<br/> + <dl><group><text>void (*fun)(INT32),<br/> + char *type,<br/> + INT16 flags)<br/> + </text></group></dl></p> + </tt> + <p>This function adds a function to the program you are building. + The function will have the name 'name' and the type 'type'. + The function 'fun' will be called with an integer telling it how + many arguments are on the stack and is expected to remove those + elements from the stack and replace them with a return value. + The flags are zero or more of the following or:ed together: + ID_STATIC, ID_PRIVATE, ID_NOMASK, ID_PUBLIC, ID_PROTECTED and + ID_INLINE.</p> +  + program</text> +  + <group><seealso/><text> + <p><ref resolved='c::start_new_program' to='start_new_program'>start_new_program</ref> and <ref resolved='c::types' to='types'>types</ref></p> + </text></group> +  + </doc> + </docgroup>   <docgroup homogen-name='add_shared_strings' homogen-type='method'>   <method name='add_shared_strings'/><doc placeholder='true'>   <text>
51:      </doc>   </docgroup> + <docgroup homogen-name='add_storage' homogen-type='method'> + <method name='add_storage'/><doc placeholder='true'> + <text> + <p><tt>add_storage</tt> - allocate space for object-local data</p> +  + <tt><p>#include "program.h"<br/> +  + </p> + <p>void add_storage(INT32 <i>size</i>);<br/> + </p> + </tt> + <p>This function allocates 'size' bytes in every object cloned from the + program you are in the process of building. (Be sure to call + start_new_program first...) Whenever one of your methods are called + fp-&gt;current_storage will point to this area.</p> +  + program</text> +  + <group><seealso/><text> + <p><ref resolved='c::start_new_program' to='start_new_program'>start_new_program</ref> and <ref resolved='c::frame' to='frame'>frame</ref></p> + </text></group> +  + </doc> + </docgroup> + <docgroup homogen-name='aggregate_array' homogen-type='method'> + <method name='aggregate_array'/><doc placeholder='true'> + <text> + <p><tt>aggregate_array</tt> - build an array from the stack</p> +  + <tt><p>#include "array.h"<br/> +  + </p> + <p>struct array *aggregate_array(INT32 num)<br/> + </p> + </tt> + <p>This pops 'num' args off the stack an puts them in an array. + The 'top' of the stack will be the last element in the array.</p> +  + array</text> +  + <group><seealso/><text> + <p><ref to='check_stack'>check_stack</ref> and <ref resolved='c::push_array_items' to='push_array_items'>push_array_items</ref></p> + </text></group> +  + </doc> + </docgroup>   <docgroup homogen-name='allocate_array' homogen-type='method'>   <method name='allocate_array'/><doc placeholder='true'>   <text>
132:   <p>If n is out of bounds (n &lt; 0 or n &gt;= a-&gt;size) Pike will dump   core. If Pike was compiled with DEBUG, a message will be written   first stating what the problem was.</p> +  + array</text></group> +  + <group><seealso/><text> + <p><ref resolved='c::assign_svalue' to='assign_svalue'>assign_svalue</ref></p>   </text></group>    -  + </doc> + </docgroup> + <docgroup homogen-name='array_remove' homogen-type='method'> + <method name='array_remove'/><doc placeholder='true'> + <text> + <p><tt>array_remove</tt> - remove an index from an array</p> +  + <tt><p>#include "array.h"<br/> +  + </p> + <p>struct array *array_remove(struct array *<i>a</i>, INT32 <i>ind</i>);<br/> + </p> + </tt> + <p>This function removes the index 'ind' from the array 'a' destructively. + The returned array should be used instead of 'a' and can be the same + as 'a'. Because this function is destructive and might free the + memory region for 'a' it may only be used on arrays which has not been + sent to any lpc functions yet.</p> +  + array</text> +    <group><seealso/><text> -  + <p><ref to='array_insert'>array_insert</ref></p> + </text></group> +  + </doc> + </docgroup> + <docgroup homogen-name='array_search' homogen-type='method'> + <method name='array_search'/><doc placeholder='true'> + <text> + <p><tt>array_search</tt> - search an array</p> +  + <tt><p>#include "array.h"<br/> +  + </p> + <p>INT32 array_search(struct array *a,<br/> + <dl><group><text>struct svalue *val,<br/> + INT32 start);<br/> + </text></group></dl></p> + </tt> + <p>This function loops over the array 'a' starting at 'start' until + it finds an index that is_eq to 'val'. When it finds such a value + the number for that index will be returned. If no such value is + found -1 is returned.</p> + </text> +  + <group><note/><text> + <p>This function checks the type_field in the array, and also re-builds + the type-field if the value is not found.</p> +  + array</text></group> +  + <group><seealso/><text> + <p><ref resolved='c::is_eq' to='is_eq'>is_eq</ref></p> + </text></group> +  + </doc> + </docgroup> + <docgroup homogen-name='array_set_index' homogen-type='method'> + <method name='array_set_index'/><doc placeholder='true'> + <text> + <p><tt>array_set_index</tt> - get an index from an array</p> +  + <tt><p>#include "array.h"<br/> +  + </p> + <p>void array_set_index(struct array *a,<br/> + <dl><group><text>INT32 ind,<br/> + struct svalue *from);<br/> + </text></group></dl></p> + </tt> + <p>This function frees the contents of the index 'ind' in the array + 'a' and replaces it with a copy of the contents from 'from'. + Basically, what it does is: + </p> + <p><matrix> + <r><c> </c><c> assign_svalue(a-&gt;item + n, from); </c></r> + <r><c> </c></r> + </matrix> +  + </p> + <p>The only differance is that it adds some debug and safety + measures. Usually you don't really need to use this function.</p> + </text> +  + <group><note/><text> + <p>If n is out of bounds (n &lt; 0 or n &gt;= a-&gt;size) Pike will dump + core. If Pike was compiled with DEBUG, a message will be written + first stating what the problem was.</p> +  + array</text></group> +  + <group><seealso/><text>   <p><ref resolved='c::assign_svalue' to='assign_svalue'>assign_svalue</ref></p>   </text></group>   
209:      </doc>   </docgroup> + <docgroup homogen-name='copy_array' homogen-type='method'> + <method name='copy_array'/><doc placeholder='true'> + <text> + <p><tt>copy_array</tt> - copy an array</p> +  + <tt><p>#include "array.h"<br/> +  + </p> + <p>struct array *copy_array(struct svalue *<i>a</i>);<br/> + </p> + </tt> + <p>This function returns a copy of the array 'a'. It is not recursive, + arrays within 'a' will only get extra references.</p> +  + array</text> +  + </doc> + </docgroup>   <docgroup homogen-name='copy_mapping' homogen-type='method'>   <method name='copy_mapping'/><doc placeholder='true'>   <text>
228:      </doc>   </docgroup> + <docgroup homogen-name='end_c_program' homogen-type='method'> + <method name='end_c_program'/><doc placeholder='true'> + <text> + <p><tt>end_c_program</tt> - finish building a 'struct program'</p> +  + <tt><p>#include "program.h"<br/> +  + </p> + <p>struct program *end_c_program(char *<i>name</i>);<br/> + </p> + </tt> + <p>This function finishes up the process of building a 'struct program'. + It initializes the struct program and calls + master()-&gt;add_precompiled_program with the program and the suggested + name. (As sent to end_c_program). It then returns the newly built + program. Note that the new program does NOT have an extra reference, + if you want to keep it around and use it you have to add that reference + yourself.</p> +  + program</text> +  + <group><seealso/><text> + <p><ref resolved='c::start_new_program' to='start_new_program'>start_new_program</ref> and <ref resolved='c::add_function' to='add_function'>add_function</ref></p> + </text></group> +  + </doc> + </docgroup>   <docgroup homogen-name='end_shared_string' homogen-type='method'>   <method name='end_shared_string'/><doc placeholder='true'>   <text>
899:      </doc>   </docgroup> + <docgroup homogen-name='push_array_items' homogen-type='method'> + <method name='push_array_items'/><doc placeholder='true'> + <text> + <p><tt>push_array_items</tt> - push array contents on stack</p> +  + <tt><p>#include "array.h"<br/> +  + </p> + <p>void push_array_items(struct array *a)<br/> + </p> + </tt> + <p>This function is mainly used by the @ operator. It pushes all elements + in the array 'a' on the stack. It also frees one ref count on 'a', so + be sure to do a-&gt;refs++ first if you want to use the array after + calling this function. This function also calls check_stack properly.</p> +  + array</text> +  + <group><seealso/><text> + <p><ref resolved='c::aggregate_array' to='aggregate_array'>aggregate_array</ref> and <ref to='check_stack'>check_stack</ref></p> + </text></group> +  + </doc> + </docgroup>   <docgroup homogen-name='push_string' homogen-type='method'>   <method name='push_string'/><doc placeholder='true'>   <text>
927:      </doc>   </docgroup> + <docgroup homogen-name='resize_array' homogen-type='method'> + <method name='resize_array'/><doc placeholder='true'> + <text> + <p><tt>resize_array</tt> - change the size of an array destructively</p> +  + <tt><p>#include "array.h"<br/> +  + </p> + <p>struct array *resize_array(struct array *<i>a</i>, INT32 <i>new_size</i>);<br/> + </p> + </tt> + <p>This function makes an array from 'a' with the size 'new_size'. + Note that the returned might or might not be the same as 'a'. + If 'a' is too small or too big for 'new_size', a copy of 'a' will + be made with enough room and then 'a' will be freed. This means + that you can only use this function on arrays which has not been + passed to any lpc functions yet.</p> +  + array</text> +  + <group><seealso/><text> + <p><ref to='array_insert'>array_insert</ref> and <ref resolved='c::array_remove' to='array_remove'>array_remove</ref></p> + </text></group> +  + </doc> + </docgroup> + <docgroup homogen-name='set_exit_callback' homogen-type='method'> + <method name='set_exit_callback'/><doc placeholder='true'> + <text> + <p><tt>set_exit_callback</tt> - set function to call att destruct()</p> +  + <tt><p>#include "program.h"<br/> +  + </p> + <p>void set_exit_callback(void (*exit)(struct object *) <i>fun</i>);<br/> + </p> + </tt> + <p>This function sets what function will be called when an object + cloned from your program is destructed. This function is + mainly for de-initializing the fp-&gt;current_storage region. + The function will be called with the object about to be destructed + as argument.</p> +  + program</text> +  + <group><seealso/><text> + <p><ref resolved='c::start_new_program' to='start_new_program'>start_new_program</ref> and <ref resolved='c::set_init_callback' to='set_init_callback'>set_init_callback</ref></p> + </text></group> +  + </doc> + </docgroup> + <docgroup homogen-name='set_init_callback' homogen-type='method'> + <method name='set_init_callback'/><doc placeholder='true'> + <text> + <p><tt>set_init_callback</tt> - set function to call att clone()</p> +  + <tt><p>#include "program.h"<br/> +  + </p> + <p>void set_init_callback(void (*init)(struct object *) <i>fun</i>);<br/> + </p> + </tt> + <p>This function sets what function will be called when someone + clones the struct program your are building. This function is + mainly for initializing the fp-&gt;current_storage region. + The initalizer function will be called with the newly cloned + object as argument.</p> +  + program</text> +  + <group><seealso/><text> + <p><ref resolved='c::start_new_program' to='start_new_program'>start_new_program</ref> and <ref resolved='c::set_exit_callback' to='set_exit_callback'>set_exit_callback</ref></p> + </text></group> +  + </doc> + </docgroup> + <docgroup homogen-name='slice_array' homogen-type='method'> + <method name='slice_array'/><doc placeholder='true'> + <text> + <p><tt>slice_array</tt> - slice a pice of an array</p> +  + <tt><p>#include "array.h"<br/> +  + </p> + <p>struct array *slice_array(struct array *<i>a</i>, INT32 <i>start</i>, INT32 <i>end</i>);<br/> + </p> + </tt> + <p>This is the equivialent of the pike operation a[start..end]. A new + array will be returned with one reference.</p> +  + array</text> +  + </doc> + </docgroup> + <docgroup homogen-name='start_new_program' homogen-type='method'> + <method name='start_new_program'/><doc placeholder='true'> + <text> + <p><tt>start_new_program</tt> - start building a new 'struct program'</p> +  + <tt><p>#include "program.h"<br/> +  + </p> + <p>void start_new_program(void);<br/> + </p> + </tt> + <p>This function initalizes a new 'struct program' to be be fitted + with functions, variables, inherits etc. etc.</p> +  + program</text> +  + <group><seealso/><text> + <p><ref resolved='c::end_c_program' to='end_c_program'>end_c_program</ref>, <ref resolved='c::add_function' to='add_function'>add_function</ref> and <ref resolved='c::add_storage' to='add_storage'>add_storage</ref></p> + </text></group> +  + </doc> + </docgroup>   <docgroup homogen-name='string_replace' homogen-type='method'>   <method name='string_replace'/><doc placeholder='true'>   <text>
1033:      </doc>   </docgroup> + <docgroup homogen-name='types' homogen-type='method'> + <method name='types'/><doc placeholder='true'> + <text> + <p><tt>types</tt> - how to describe types internally</p> +  + <p>When describing types to add_function or add_efun you always write + it in a string. You write the type just as you would in Pike. The + internal types have a few extra features though. Here is a brief + explanation of the syntax: + </p> + <p><matrix> + <r><c> type </c><c> you write: </c></r> + <r><c> int </c><c> "int" </c></r> + <r><c> float </c><c> "float" </c></r> + <r><c> string </c><c> "string" </c></r> + <r><c> mapping </c><c> "mapping(mixed:mixed)" or "mapping" </c></r> + <r><c> array of int </c><c> </c><c> "array(int)" or "int *" </c></r> + <r><c> function(int:int) </c><c> "function(int:int)" </c></r> + <r><c> varargs function </c><c> "function(int ...:int)" </c></r> + <r><c> int or string </c><c> </c><c> "int|string" </c></r> + </matrix> +  + </p> + <p>Then there are a few tricks you can use, say you have a function which + returns an int except if you call it with a string in which case it + return a string: + </p> + <p>"!function(string:mixed)&amp;function(mixed:int)|function(string:string)" + </p> + <p>The &amp; and ! operators work as you might expect but are only useful + together.</p> +  + internals</text> +  + <group><seealso/><text> + <p><ref resolved='c::add_function' to='add_function'>add_function</ref> and <ref to='add_efun'>add_efun</ref></p> + </text></group> +  + </doc> + </docgroup>   </namespace>   <namespace name='cpp'>   <doc placeholder='true'>