@lpc-lang/core 1.1.2-5.1

package/src/efuns/fluffos/arrays.h

@@ -0,0 +1,205 @@
+// arrays.h
+
+#undef ALL_ARRAY_TYPES
+#define ALL_ARRAY_TYPES string*|int*|float*|object*|mixed*|function*
+#undef ALL_PRIMITIVE_TYPES
+#define ALL_PRIMITIVE_TYPES string|int|float|object|mixed|function
+
+/**
+ * unique_array() - partitions an array of objects into groups
+ *
+ * Groups objects together for which the 'separator' function returns  the
+ * same  value.  'obarr'  should  be  an array of objects, other types are
+ * ignored.  The 'separator' function is called only once in  each  object
+ * in  'obarr'.   THe  optional  'skip'  parameter enables a pre-filter on
+ * 'obarr', skipping elements which match 'skip'.  The second form works a
+ * bit differently.  each element of the array is passed to f and the ele‐
+ * ments are partitioned based on the return value of f.   In  particular,
+ * the array does not need to be composed of objects.
+ *
+ * @template {object} T
+ * @param {T*} obarr The array of objects to partition
+ * @param separator The function to use to partition the array
+ * @param {T} skip The value to skip
+ * @returns {<T*>*} The partitioned array
+ */
+varargs mixed unique_array(object *obarr, string separator, mixed skip);
+
+/**
+ * @template T, Y
+ * @callback uniqueArrayCallback
+ * @param {T} element The element to test
+ * @returns {Y} The map callback return value
+ */
+
+
+/**
+ * unique_array() - partitions an array of objects into groups
+ *
+ * Groups objects together for which the 'separator' function returns  the
+ * same  value.  'obarr'  should  be  an array of objects, other types are
+ * ignored.  The 'separator' function is called only once in  each  object
+ * in  'obarr'.   THe  optional  'skip'  parameter enables a pre-filter on
+ * 'obarr', skipping elements which match 'skip'.  The second form works a
+ * bit differently.  each element of the array is passed to f and the ele‐
+ * ments are partitioned based on the return value of f.   In  particular,
+ * the array does not need to be composed of objects.
+ *
+ * @template T
+ * @param {T*} arr The array of objects to partition
+ * @param {uniqueArrayCallback<T,Y>} f The function to use to partition the array
+ * @param {T|void} skip The value to skip
+ * @returns {<T*>*} The partitioned array
+ */
+varargs <mixed*>* unique_array(mixed *arr, function f, mixed skip );
+
+/**
+ * sort_array() - sort an array
+ *
+ * The  first  form  returns an array with the same elements as 'arr', but
+ * quicksorted in ascending order according to the rules  in  'ob->fun()'.
+ * 'ob->fun()'  will  be  passed  two  arguments for each call.  It should
+ * return -1, 0, or 1, depending on the relationship of the two  arguments
+ * (lesser, equal to, greater than).
+ * 
+ * The second form does the same thing but allows a function pointer to be
+ * used instead.
+ * 
+ * The third form returns an array with the same elements  as  'arr',  but
+ * quicksorted using built-in sort routines.  A 'direction' of 1 or 0 will
+ * quicksort in ascending order, while a 'direction' of -1 will  quicksort
+ * in  descending  order.   A  limitation of the built-in sort routines is
+ * that the array must be homogeneous, composed entirely of a single type,
+ * where  that type is string, int, or float.  Arrays of arrays are sorted
+ * by sorting based on the first element, making database sorts possible.
+ * @template {ALL_ARRAY_TYPES} T
+ * @param {T} arr The array to sort
+ * @returns {T} The sorted array
+ */
+mixed *sort_array( mixed *arr, string fun, object ob );
+mixed *sort_array( mixed *arr, function f );
+mixed *sort_array( mixed *arr, int direction );
+
+/**
+ * shuffle() - Rearrange the elements in the array in random order
+ *
+ * Shuffle the array and return.
+ * @template {ALL_ARRAY_TYPES} T
+ * @param {T} arr The array to shuffle
+ * @returns {T} The shuffled array
+ */
+mixed *shuffle(mixed *arr);
+
+/**
+ * pointerp() - identifies whether a given variable is an array
+ * @param {mixed} arg The argument to check 
+ * @returns {arg is mixed*} 1 if 'arg' is an array, otherwise returns 0.
+ * @example
+ * int is_array = pointerp( ({ 1, 2, 3, 4 }) ); // 1
+ * int is_array = pointerp( "Foo" ); // 0
+ *
+ */
+int pointerp( mixed arg );
+
+/**
+ * member_array()  -  returns  index of an occurence of a given item in an
+array or string
+ *
+ * Returns the index of the first occurence of 'item' in array  'arr',  or
+ * the  first  occurence  at  or after 'start'.  If the item is not found,
+ * then -1 is returned.
+ * 
+ * Note, if the second argument is a string, the first parameter must be an int
+ * representing the character you are looking for in the provided string.
+ * @example
+ * ```c
+ * member_array( "red", ({ "red", "blue", "red", "green", "red", }) ) ;
+ * // 0
+ * 
+ * member_array( "red", ({ "red", "blue", "red", "green", "red", }) , 1) ;
+ * // 2
+ * 
+ * member_array( "blue", ({ "red", "blue", "red", "green", "red", }) , 3) ;
+ * // -1
+ * 
+ * member_array( "purple", ({ "red", "blue", "red", "green", "red", }) ) ;
+ * // -1
+ * 
+ * member_array('F', "Drink the FluffOS Kool-Aid!") ;
+ * // 10
+ * 
+ * member_array('Z', "Drink the FluffOS Kool-Aid!") ;
+ * // -1
+ * ```
+ */
+varargs int member_array( mixed item, mixed * | string arr, void | int start );
+
+/**
+ * map_array() - modify an array of elements via application of a function
+ *
+ * Returns  an  array  holding  the  items  of 'arr' mapped through either
+ * 'ob->fun()' or 'f'.  The function is called for each element  in  'arr'
+ * with that element as a parameter. A second parameter 'extra' is sent in
+ * each call if given.  Principal function:
+ * ```c
+ * foreach (index) arr[index] = ob->fun(arr[index],extra);
+ * ```
+ * The value returned by 'ob->fun(arr[.index.], extra)' replaces the existing
+ * element in the array. If 'arr' is not an array, then 0 will be returned.
+ *
+ */
+mixed *map_array( mixed *arr, string fun, object ob, mixed extra... );
+mixed *map_array( mixed *arr, function f, mixed extra... );
+
+/**
+ * filter_array() - return a selective sub-array
+ *
+ * filter_array() returns an array holding the items of <arr> which passed
+ * sucessfully through the function <fun> found in object <ob>.  The func‐
+ * tion  <fun>  is  called  for each element in <arr> with that element as
+ * parameter.  The second parameter <extra> and following  parameters  are
+ * sent  in  each  call  if given.  An object is considered to have passed
+ * sucessfully through <fun> (and hence is included in the  return  array)
+ * if  <fun>  returns  1.  If f is passed it is used instead of ob->fun().
+ * If <arr> is not an array, then 0 will be returned.
+ *
+ */
+mixed *filter_array( mixed *arr, string fun, object|string ob, mixed extra... );
+mixed *filter_array( mixed *arr, function f, mixed extra... );
+
+/**
+ * element_of() - Return an element randomly from the array
+ *
+ * Returns a random element from an array.
+ *
+ */
+mixed element_of(mixed *arr);
+
+/**
+ * arrayp() - identifies whether a given variable is an array
+ *
+ * Returns 1 if 'arg' is an array, otherwise returns 0.
+ * 
+ * @param {mixed} arg The argument to check
+ * @returns {arg is mixed*} 1 if 'arg' is an array, otherwise returns 0.
+ * @example
+ * int is_array = arrayp( ({ 1, 2, 3, 4 }) ); // 1
+ * int is_array = arrayp( "Foo" ); // 0  
+ */
+int arrayp( mixed arg );
+
+/**
+ * allocate() - allocate an array
+ *
+ * Allocate an array of <size> elements. The number of elements must be
+ * >= 0 and not bigger than a system maximum (usually ~10000). All elements
+ * are initialized to 0 by default.
+ * 
+ * If the optional second argument is provided, the values are initialized
+ * to that argument, unless the second argument is a functional. In that case,
+ * the functional will be evaluated for each array element, with the first
+ * argument passed to the functional being the number of the array element.
+ *
+ */
+varargs mixed *allocate( int size, void | mixed value );
+

package/src/efuns/fluffos/async.h

@@ -0,0 +1,84 @@
+// async.h
+
+/**
+ * async_write() - appends a string to a file then executes a callback
+ *
+ * Append  the string 'str' into the file 'file'. If flag is 1, write_file
+ * overwrites instead of appending.
+ * 
+ * Unlike write_file, which returns 0 for failure or 1 for success, this efun
+ * will return -1 for failure and 0 for success to the callback.
+ * 
+ * The callback should follow this format:
+ * 
+ * function (int res) {
+ * // -1 for failure
+ * //  0 for success
+ * }
+ *
+ */
+void async_write( string file, string str, int flag, function callback );
+
+/**
+ * async_read() - read a file into a string then executes a callback
+ *
+ * Read  a  line  of text from a file into a string.  Normally, read_file
+ * takes a second and third arguments for start_line and number_of_lines to
+ * read, but async_read will return the entire file to the callback.
+ * 
+ * The callback should follow this format:
+ * 
+ * function(mixed res) {
+ * // -1 for file not read
+ * // string file contents otherwise
+ * }
+ *
+ */
+void async_read( string file, function callback );
+
+/**
+ * async_getdir() - returns information pertaining to a filesystem directory
+ *
+ * If  'dir' is a filename ('*' and '?' wildcards are supported), an array
+ * of strings is returned to the callback containing all filenames that match
+ * the specification. If 'dir' is a directory name (ending with a slash--ie:
+ * "/u/", "/adm/", etc), all filenames in that directory are returned.
+ * 
+ * Unlike the get_dir routine, this efun does not take an integer second
+ * argument to specify more information (filename, filesize, last touched).
+ * 
+ * The callback should follow this format:
+ * 
+ * function(mixed res) {
+ * // 0 when directory doesn't exist
+ * // empty array when no matching files exist
+ * // array of matching filenames
+ * }
+ *
+ */
+void async_getdir( string dir, function callback );
+
+/**
+ * async_db_exec() - executes an sql statement then executes a callback
+ *
+ * This function will execute the passed sql statement for the given data‐
+ * base handle.
+ * 
+ * Returns the database handle to the callback function provided.
+ * 
+ * The callback should follow this format:
+ * 
+ * ```c
+ * async_db_exec(
+ * handle,
+ * sql_query,
+ * function (int rows) { // number of matched rows
+ * mixed *results = db_fetch(handle, 1);
+ * db_close(handle);
+ * }
+ * );
+ * ```
+ *
+ */
+void async_db_exec( int handle, string sql_query, function callback );
+

package/src/efuns/fluffos/buffers.h

@@ -0,0 +1,80 @@
+// buffers.h
+
+/**
+ * write_buffer() - write a buffer to a file, or read into a buffer from a
+source
+ *
+ * If 'dest' is a file, then 'source' must be an int (and will be  written
+ * to the file in network-byte-order), a buffer, or a string, and 'source'
+ * will be written to the file 'dest' starting at byte # 'start'.
+ * 
+ * If 'dest' is a buffer, then 'source' will be written  into  the  buffer
+ * starting  at  byte  # 'start' in the buffer.  If 'source' is an int, it
+ * will be written in network-byte-order.
+ *
+ */
+int write_buffer( string | buffer dest,
+                  int start,
+                  mixed source );
+
+/**
+ * read_buffer() - read from a file and return a buffer, or return part of
+a buffer as a string
+ *
+ * If 'src' is a string (filename), then the filename will be read, start‐
+ * ing  at  byte # 'start', for 'len' bytes, and returned as a buffer.  If
+ * neither argument is given, the entire file is read.
+ * 
+ * If 'src' is a buffer, then characters are read from the  buffer  begin‐
+ * ning  at  byte  #  'start' in the buffer, and for 'len' # of bytes, and
+ * returned as a string.
+ * 
+ * Note that the maximum number of bytes you can read from a file and into
+ * a buffer is controlled via the 'maximum byte transfer' parameter in the
+ * runtime config file.
+ *
+ */
+string | buffer read_buffer( string | buffer src,
+                             int start,
+                             int len );
+
+/**
+ * crc32() - compute the cycle redundancy code for a buffer or string
+ *
+ * Computes  and  returns  the CRC-32 code for the given buffer or string, 'x'.
+ *
+ */
+int crc32( buffer | string x );
+
+/**
+ * bufferp() - identifies whether a given variable is a buffer
+ *
+ * Return 1 if 'arg' is a buffer value and zero (0) otherwise.
+ *
+ * int is_buffer = bufferp( allocate_buffer(10) ); // 1
+ * int is_buffer = bufferp( "Foo" ); // 0
+ *
+ */
+int bufferp( mixed arg );
+
+/**
+ * buffer_transcode() - transcode a buffer from one encoding to another
+ *
+ * Transcode given buffer from encoding 'from_encoding' to encoding
+ * 'to_encoding'.
+ *
+ */
+buffer buffer_transcode(buffer src,
+                        string from_encoding,
+                        string to_encoding);
+
+/**
+ * allocate_buffer() - allocate a buffer
+ *
+ * Allocate  a  buffer of <size> elements.  The number of elements must be
+ * >= 0 and not bigger than a system maximum (usually ~10000).   All  ele‐
+ * ments are initialized to 0.
+ *
+ */
+buffer allocate_buffer( int size );
+

package/src/efuns/fluffos/calls.h

@@ -0,0 +1,275 @@
+// calls.h
+
+/**
+ * throw() - forces an error to occur in an object.
+ *
+ * The  throw()  efun may be used to force an error to occur in an object.
+ * When used in conjunction, throw() and catch() allow the  programmer  to
+ * choose  what  error  message  is displayed when a runtime error occurs.
+ * When throw() is used,  it  should  be  used  in  conjunction  with  the
+ * catch(3) efun.  Here is a typical usage:
+ * 
+ * string err;
+ * int rc;
+ * 
+ * err = catch(rc = ob->move(dest));
+ * if (err) {
+ * throw("move.c: ob->move(dest): " + err + "\n");
+ * return;
+ * }
+ *
+ */
+void throw(mixed);
+
+/**
+ * this_object() - return the object pointer of the calling object
+ *
+ * Return the object pointer of this object.  This function is useful when
+ * an object wants to call functions that are not in the same source  file
+ * but are in the same object (via inheritance).
+ *
+ */
+object this_object( void );
+
+/**
+ * shadow() - shadow one or more functions in some object
+ *
+ * If  'flag'  is  1  or missing, then current object will shadow 'ob'. If
+ * 'flag' is 0, then either 0 will be returned,  or  the  object  that  is
+ * already shadowing 'ob'.
+ * 
+ * The master object defines the function "valid_shadow()".  If it returns
+ * 1 the target object can't be shadowed, and the "shadow()" function will
+ * return 0 instead of 'ob'.
+ * 
+ * If  an object 'a' shadows an object 'b', then all "call_other(func)" to
+ * 'b' will be redirected to 'a'. If object 'a' has not defined the  func‐
+ * tion,  then  the  call  will  be  forwarded to 'b' (as if there were no
+ * shadow).  There is only one object that can call functions in 'b'  with
+ * call_other(),  and  that is 'a'. Not even object 'b' can "call_other()"
+ * itself. All normal (internal) function calls inside  'b'  will  however
+ * remain internal to 'b'.
+ * 
+ * There  are  two  ways  to remove the shadow. Either destruct it, or the
+ * object that was shadowed. In the latter case, the shadow will  also  be
+ * destructed automatically.
+ * 
+ * The result is that it is possible to hide an object behind another one,
+ * but everything can be  totally  transparent.   The  shadow()  efunction
+ * makes  it possible to change the behavior of an object without changing
+ * the code for the object in question.  One possible use for shadow()  is
+ * to  add  special  capabilities  to  various  classes of players (thief,
+ * fighter, mage, etc).  This usage would make it  possible  to  keep  the
+ * player object much simpler than it could be if the code for the various
+ * classes had to be in the player object itself.
+ *
+ */
+varargs object shadow( object ob, int flag );
+
+/**
+ * remove_call_out() - remove a pending call_out
+ *
+ * In  the  first form this function removes the next pending call out for
+ * function <fun> in the current object.  The return  value  is the number
+ * of  seconds  remaining  before  the callback was to be called, or -1 if
+ * there was no call out pending to this function.
+ * 
+ * In the second form, this function removes a pending call out identified
+ * by  the  <handle>  returned  from the  call_out()  function. The return
+ * value is the number of remaining seconds before the call_out was to  be
+ * called,  or -1  if  there  was  no  valid  call_out  identified  by the
+ * specified <handle>.
+ * 
+ * In the third form all pending call outs for the current object will be
+ * removed. In this case the return value is always 0.
+ *
+ */
+int remove_call_out( string fun );
+int remove_call_out( int handle );
+int remove_call_out();
+
+/**
+ * shadowp()  -  determine  whether  or  not  a  given object it shadowing
+another
+ *
+ * Returns the object that 'ob' is shadowing, or zero (0)  if  it  is  not
+ * shadowing any object.
+ *
+ */
+object shadowp( object ob );
+
+/**
+ * previous_object() - returns the object(s) that called the current func‐
+tion
+ *
+ * Returns an object pointer to the object, if any,  that  called  current
+ * function.   Note that local function calls do not set previous_object()
+ * to the current object, but leave it unchanged.  If  passed  a  positive
+ * integer, it goes back the given number of previous objects in the call‐
+ * ing chain.  previous_object(0) is the same as previous_object(), previ‐
+ * ous_object(1)  is the previous object's previous_object(), etc.  previ‐
+ * ous_object(-1) returns an array containing all of the previous objects.
+ *
+ */
+mixed previous_object( int | void );
+
+/**
+ * origin() - determine how the current function was called
+ *
+ * Returns  an  integer  specifying  how  the current function was called.
+ * Current values are:
+ * 
+ * 1    Driver (heart_beats, etc)
+ * 2    Local function call
+ * 4    call_other()
+ * 8    simul_efun object via a simul_efun call
+ * 16    call_out()
+ * 32    called by an efun (sort_array, etc)
+ * 64    function_pointer
+ * 128    functional
+ *
+ */
+int origin( void );
+
+/**
+ * catch() - catch an evaluation error
+ *
+ * Evaluate  <expr>.  If  there  is no error, 0 is returned. If there is a
+ * standard error, a string (with a leading '*') will be returned.
+ * 
+ * The function throw() can also be used to immediately return any  value,
+ * except 0. catch() is not really a function call, but a directive to the
+ * compiler.
+ * 
+ * The catch() is somewhat costly, and should not be used  just  anywhere.
+ * Rather, use it at places where an error would destroy consistency.
+ *
+ * void example1() {
+ * object ob ;
+ * mixed err ;
+ * 
+ * err = catch( ob = load_object("/obj/weapon/sword") ) ;
+ * if(err) throw("There was an error loading the specified file.") ;
+ * }
+ * 
+ * void example2() {
+ * mixed err = catch {
+ * string file, *files = ({
+ * "/u/g/gesslar/one",     // good file
+ * "/u/g/gesslar/two",     // bad file
+ * "/u/g/gesslar/three",   // good file
+ * }) ;
+ * 
+ * foreach(file in files) load_object(file) ;
+ * } ;
+ * 
+ * if(err) printf("ERR: %O", err) ;
+ * }
+ * 
+ * // ERR: "*Error in loading object '/u/g/gesslar/two'"
+ *
+ */
+
+// This will be handled through the parser
+// mixed catch( mixed expr );
+
+/**
+ * call_stack - returns information about the functions involved in calling
+this function
+ *
+ * If the int `option` argument is 0, call_stack() returns an array of the
+ * names of the on the call stack, with the first one being the most recent
+ * (i.e. the currently running program).  If the int argument is 1, call_stack
+ * returns the objects in which that program is executing.  If it is 2, the
+ * name of the functions are returned.  If it is 3, the value of origin() in
+ * that frame is returned. If it is 4, the value will be the full file path
+ * and the line number.
+ *
+ */
+varargs string *call_stack(int option);
+
+/**
+ * call_out_walltime - delayed function call in same object
+ *
+ * This efun is identical to call_out except it does not schedule the
+ * call on the game loop. Rather, in real seconds. The delay can be in
+ * seconds or fraction of a second.
+ *
+ */
+int call_out_walltime( string | function fun, int | float delay, mixed arg ... );
+
+/**
+ * call_out - delayed function call in same object
+ *
+ * Schedule a future call of function <fun> in this_object(). The call will
+ * take place in <delay> seconds, with each of the arguments <arg> provided.
+ * <arg> can be of any type.
+ * 
+ * If the gametick in the runtime config is less than 1000, you may specify
+ * a <delay> as a float in milliseconds (gametick / 1000) representing a
+ * value that is divisible by the gametick. A <delay> which is not equally
+ * divisible by the gametick value will be rounded up to the next game tick.
+ * A <delay> of 0 is special, see below.
+ * 
+ * For example, if your gametick is set to 250ms in the runtime config,
+ * you may perform callouts with a granularity of a quarter of a second.
+ * call_out( "function", 0.75 ) will execute the <fun> in 3 game ticks
+ * (750 milliseconds), thereby affording more precision over timing
+ * when calling out.
+ * 
+ * A <delay> of 0 (or 0.0), will perform <fun> on the same gametick in which
+ * it was called after all previous call_outs have been executed. The number
+ * of call_outs(0)s which may be executed on the same gametick may be
+ * configured via the "call_out(0) nest level" property in the runtime config.
+ * 
+ * Please note that you can't rely on write() or say() in <fun> since
+ * this_player() is set to 0. Use tell_object() instead.
+ * 
+ * The runtime config value "this_player in call_out" exists to remedy the
+ * above problem.
+ * 
+ * The return value is an integer representing the handle of the call_out
+ * which may be used as an argument to remove_call_out().
+ *
+ */
+int call_out( string | function fun, int | float delay, mixed arg ... );
+
+/**
+ * call_other() - call a function in another object
+ *
+ * Calls  a  function in another object, with [optional] argument(s).  The
+ * return value is returned from the other object, so it cannot  be  known
+ * at  compile  time  and may need to be cast if using type checking.  The
+ * function named 'func' will be called in 'ob', with arguments 3, 4,  etc
+ * given as arguments 1, 2, etc to 'func' in 'ob'.  call_other will return
+ * the return value of 'func'.  If the first argument is an array  instead
+ * of  an object, then the call will be done in all elements of that array
+ * (all elements should be of type object), and an array of  returns  will
+ * be  returned.   If argument 2 is an array instead of a string, then the
+ * first element in the array should be a string, the  function  to  call,
+ * and all other elements will be passed to the function in the order they
+ * appear in the array.
+ * 
+ * There is a much more attractive way to do call_others:
+ * 
+ * object ob | object *obs -> func ( ... );
+ * 
+ * ie,
+ * 
+ * call_other(ob, "query", "name");
+ * 
+ * could be written as:
+ * 
+ * ob->query("name");
+ * 
+ * Using an array as second argument, the same call could be written:
+ * 
+ * call_other(ob, ({ "query", "name" }));
+ * 
+ * An example of using an array as the first argument:
+ * 
+ * users()->quit();
+ *
+ */
+mixed call_other( object|object* ob, string|mixed * funcArgs... );
+