From 84560929c2516e387d43ddc56e771d6ba3e2050b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20H=C3=BCbinette=20=28Hubbe=29?= <hubbe@hubbe.net> Date: Wed, 6 Nov 1996 13:23:39 -0800 Subject: [PATCH] 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 --- doc/internal/array/aggregate_array | 17 +++++++++++++ doc/internal/array/array_index | 5 +++- doc/internal/array/array_remove | 20 ++++++++++++++++ doc/internal/array/array_search | 26 ++++++++++++++++++++ doc/internal/array/array_set_index | 30 +++++++++++++++++++++++ doc/internal/array/copy_array | 14 +++++++++++ doc/internal/array/push_array_items | 19 +++++++++++++++ doc/internal/array/resize_array | 22 +++++++++++++++++ doc/internal/array/slice_array | 14 +++++++++++ doc/internal/pike/types | 33 ++++++++++++++++++++++++++ doc/internal/program/add_function | 26 ++++++++++++++++++++ doc/internal/program/add_storage | 19 +++++++++++++++ doc/internal/program/end_c_program | 22 +++++++++++++++++ doc/internal/program/set_exit_callback | 20 ++++++++++++++++ doc/internal/program/set_init_callback | 20 ++++++++++++++++ doc/internal/program/start_new_program | 17 +++++++++++++ 16 files changed, 323 insertions(+), 1 deletion(-) create mode 100644 doc/internal/array/aggregate_array create mode 100644 doc/internal/array/array_remove create mode 100644 doc/internal/array/array_search create mode 100644 doc/internal/array/array_set_index create mode 100644 doc/internal/array/copy_array create mode 100644 doc/internal/array/push_array_items create mode 100644 doc/internal/array/resize_array create mode 100644 doc/internal/array/slice_array create mode 100644 doc/internal/pike/types create mode 100644 doc/internal/program/add_function create mode 100644 doc/internal/program/add_storage create mode 100644 doc/internal/program/end_c_program create mode 100644 doc/internal/program/set_exit_callback create mode 100644 doc/internal/program/set_init_callback create mode 100644 doc/internal/program/start_new_program diff --git a/doc/internal/array/aggregate_array b/doc/internal/array/aggregate_array new file mode 100644 index 0000000000..8a09a223e1 --- /dev/null +++ b/doc/internal/array/aggregate_array @@ -0,0 +1,17 @@ +NAME + aggregate_array - build an array from the stack + +SYNTAX + #include "array.h" + + struct array *aggregate_array(INT32 num) + +DESCRIPTION + 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. + +KEYWORDS + array + +SEE ALSO + check_stack, push_array_items \ No newline at end of file diff --git a/doc/internal/array/array_index b/doc/internal/array/array_index index bf9d37df84..7793f329ac 100644 --- a/doc/internal/array/array_index +++ b/doc/internal/array/array_index @@ -21,5 +21,8 @@ NOTA BENE core. If Pike was compiled with DEBUG, a message will be written first stating what the problem was. +KEYWORDS + array + SEE ALSO - assign_svalue \ No newline at end of file + assign_svalue diff --git a/doc/internal/array/array_remove b/doc/internal/array/array_remove new file mode 100644 index 0000000000..ffb605c52f --- /dev/null +++ b/doc/internal/array/array_remove @@ -0,0 +1,20 @@ +NAME + array_remove - remove an index from an array + +SYNTAX + #include "array.h" + + struct array *array_remove(struct array *a, INT32 ind); + +DESCRIPTION + 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. + +KEYWORDS + array + +SEE ALSO + array_insert diff --git a/doc/internal/array/array_search b/doc/internal/array/array_search new file mode 100644 index 0000000000..1f825dc7b4 --- /dev/null +++ b/doc/internal/array/array_search @@ -0,0 +1,26 @@ +NAME + array_search - search an array + +SYNTAX + #include "array.h" + + INT32 array_search(struct array *a, + struct svalue *val, + INT32 start); + +DESCRIPTION + 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. + +NOTA BENE + This function checks the type_field in the array, and also re-builds + the type-field if the value is not found. + +KEYWORDS + array + +SEE ALSO + is_eq + \ No newline at end of file diff --git a/doc/internal/array/array_set_index b/doc/internal/array/array_set_index new file mode 100644 index 0000000000..8c138aca43 --- /dev/null +++ b/doc/internal/array/array_set_index @@ -0,0 +1,30 @@ +NAME + array_set_index - get an index from an array + +SYNTAX + #include "array.h" + + void array_set_index(struct array *a, + INT32 ind, + struct svalue *from); + +DESCRIPTION + 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: + + assign_svalue(a->item + n, from); + + The only differance is that it adds some debug and safety + measures. Usually you don't really need to use this function. + +NOTA BENE + If n is out of bounds (n < 0 or n >= a->size) Pike will dump + core. If Pike was compiled with DEBUG, a message will be written + first stating what the problem was. + +KEYWORDS + array + +SEE ALSO + assign_svalue diff --git a/doc/internal/array/copy_array b/doc/internal/array/copy_array new file mode 100644 index 0000000000..dca42ea65f --- /dev/null +++ b/doc/internal/array/copy_array @@ -0,0 +1,14 @@ +NAME + copy_array - copy an array + +SYNTAX + #include "array.h" + + struct array *copy_array(struct svalue *a); + +DESCRIPTION + This function returns a copy of the array 'a'. It is not recursive, + arrays within 'a' will only get extra references. + +KEYWORDS + array diff --git a/doc/internal/array/push_array_items b/doc/internal/array/push_array_items new file mode 100644 index 0000000000..6cc0910c54 --- /dev/null +++ b/doc/internal/array/push_array_items @@ -0,0 +1,19 @@ +NAME + push_array_items - push array contents on stack + +SYNTAX + #include "array.h" + + void push_array_items(struct array *a) + +DESCRIPTION + 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->refs++ first if you want to use the array after + calling this function. This function also calls check_stack properly. + +KEYWORDS + array + +SEE ALSO + aggregate_array, check_stack diff --git a/doc/internal/array/resize_array b/doc/internal/array/resize_array new file mode 100644 index 0000000000..a2d20770ac --- /dev/null +++ b/doc/internal/array/resize_array @@ -0,0 +1,22 @@ +NAME + resize_array - change the size of an array destructively + +SYNTAX + #include "array.h" + + struct array *resize_array(struct array *a, INT32 new_size); + +DESCRIPTION + 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. + +KEYWORDS + array + +SEE ALSO + array_insert, array_remove + diff --git a/doc/internal/array/slice_array b/doc/internal/array/slice_array new file mode 100644 index 0000000000..9d914fb0e4 --- /dev/null +++ b/doc/internal/array/slice_array @@ -0,0 +1,14 @@ +NAME + slice_array - slice a pice of an array + +SYNTAX + #include "array.h" + + struct array *slice_array(struct array *a, INT32 start, INT32 end); + +DESCRIPTION + This is the equivialent of the pike operation a[start..end]. A new + array will be returned with one reference. + +KEYWORDS + array diff --git a/doc/internal/pike/types b/doc/internal/pike/types new file mode 100644 index 0000000000..25fad092ce --- /dev/null +++ b/doc/internal/pike/types @@ -0,0 +1,33 @@ +NAME + types - how to describe types internally + +DESCRIPTION + 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: + + type you write: + int "int" + float "float" + string "string" + mapping "mapping(mixed:mixed)" or "mapping" + array of int "array(int)" or "int *" + function(int:int) "function(int:int)" + varargs function "function(int ...:int)" + int or string "int|string" + + 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: + + "!function(string:mixed)&function(mixed:int)|function(string:string)" + + The & and ! operators work as you might expect but are only useful + together. + +KEYWORDS + internals + +SEE ALSO + add_function, add_efun \ No newline at end of file diff --git a/doc/internal/program/add_function b/doc/internal/program/add_function new file mode 100644 index 0000000000..a7024554d6 --- /dev/null +++ b/doc/internal/program/add_function @@ -0,0 +1,26 @@ +NAME + add_function - add a function to the program + +SYNTAX + #include "program.h" + + void add_function(char *name, + void (*fun)(INT32), + char *type, + INT16 flags) + +DESCRIPTION + 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. + +KEYWORDS + program + +SEE ALSO + start_new_program, types \ No newline at end of file diff --git a/doc/internal/program/add_storage b/doc/internal/program/add_storage new file mode 100644 index 0000000000..e9beb3cf9c --- /dev/null +++ b/doc/internal/program/add_storage @@ -0,0 +1,19 @@ +NAME + add_storage - allocate space for object-local data + +SYNTAX + #include "program.h" + + void add_storage(INT32 size); + +DESCRIPTION + 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->current_storage will point to this area. + +KEYWORDS + program + +SEE ALSO + start_new_program, frame diff --git a/doc/internal/program/end_c_program b/doc/internal/program/end_c_program new file mode 100644 index 0000000000..ca7616776f --- /dev/null +++ b/doc/internal/program/end_c_program @@ -0,0 +1,22 @@ +NAME + end_c_program - finish building a 'struct program' + +SYNTAX + #include "program.h" + + struct program *end_c_program(char *name); + +DESCRIPTION + This function finishes up the process of building a 'struct program'. + It initializes the struct program and calls + master()->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. + +KEYWORDS + program + +SEE ALSO + start_new_program, add_function diff --git a/doc/internal/program/set_exit_callback b/doc/internal/program/set_exit_callback new file mode 100644 index 0000000000..a548ee9b56 --- /dev/null +++ b/doc/internal/program/set_exit_callback @@ -0,0 +1,20 @@ +NAME + set_exit_callback - set function to call att destruct() + +SYNTAX + #include "program.h" + + void set_exit_callback(void (*exit)(struct object *) fun); + +DESCRIPTION + 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->current_storage region. + The function will be called with the object about to be destructed + as argument. + +KEYWORDS + program + +SEE ALSO + start_new_program, set_init_callback diff --git a/doc/internal/program/set_init_callback b/doc/internal/program/set_init_callback new file mode 100644 index 0000000000..1a0aaaef44 --- /dev/null +++ b/doc/internal/program/set_init_callback @@ -0,0 +1,20 @@ +NAME + set_init_callback - set function to call att clone() + +SYNTAX + #include "program.h" + + void set_init_callback(void (*init)(struct object *) fun); + +DESCRIPTION + 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->current_storage region. + The initalizer function will be called with the newly cloned + object as argument. + +KEYWORDS + program + +SEE ALSO + start_new_program, set_exit_callback diff --git a/doc/internal/program/start_new_program b/doc/internal/program/start_new_program new file mode 100644 index 0000000000..5750928bb6 --- /dev/null +++ b/doc/internal/program/start_new_program @@ -0,0 +1,17 @@ +NAME + start_new_program - start building a new 'struct program' + +SYNTAX + #include "program.h" + + void start_new_program(void); + +DESCRIPTION + This function initalizes a new 'struct program' to be be fitted + with functions, variables, inherits etc. etc. + +KEYWORDS + program + +SEE ALSO + end_c_program, add_function, add_storage -- GitLab