@lpc-lang/core 1.1.2-5.1

package/src/efuns/fluffos/contrib.h

@@ -0,0 +1,805 @@
+// contrib.h
+
+/**
+ * zonetime - returns ctime(int) for timezone string
+ *
+ * returns ctime(int) for timezone string.
+ *
+ */
+string zonetime(string timezone, int timestamp);
+
+/**
+ * variables - returns array of global variable names
+ *
+ * int == 0:
+ * returns array of global variable names
+ * 
+ * int != 0
+ * returns array of arrays of variable name & type
+ * @param {object} ob - object to query
+ * @param {int} flag (optional) defaults to 0
+ */
+mixed *variables(object ob, int flag);
+
+/**
+ * upper_case() - returns a string with every letter supplied in the source
+capitalised.
+ *
+ * Returns a new string with every character in <text> converted to upper case.
+ *
+ * string text = upper_case( "I like cheese." ) ; // "I LIKE CHEESE."
+ *
+ */
+string upper_case(string text);
+
+/**
+ * test_load - test if a file is loadable
+ *
+ * Tests if a file is loadable. Will return 1 if a file is loadable,
+ * otherwise 0. If a file attempting to be loaded contains errors,
+ * they will be reported, in which case, you may need to wrap the
+ * function call in a catch statement to retrieve the 0 result.
+ *
+ */
+int test_load( string filename );
+
+/**
+ * terminal_colour() - return a wrapped and indented string where the driver
+substitutes %^KEY%^ in the string with the matching VALUE of KEY in the
+supplied mapping.
+ *
+ * string: to be parsed for '%^KEY%^' sequences
+ * mapping: 'KEY:value' pairs
+ * 1st int: wrap after int printed symbols
+ * if int < 0 fillout lines with blank's
+ * 
+ * wrap = 4:
+ * '12\n345'
+ * wrap = -4:
+ * '12 \n345 '
+ * 
+ * minwrap: 2
+ * 
+ * 2nd int: indent by int blanks
+ * maxindent: wrap-2
+ * 
+ * returns wrapped and indented string with each '%^KEY%^' replaced by KEY's value
+ * or original string if no '%^KEY%^' sequence is found
+ * (shouldn't it at least be wrapped and indented?)
+ *
+ */
+string terminal_colour(string, mapping, int | void, int | void);
+
+/**
+ * string_difference - return levenshtein difference
+ *
+ * returns levenshtein difference
+ *
+ */
+int string_difference(string, string);
+
+/**
+ * store_variable - store a value in an object's global variable
+ *
+ * This efun stores the value in the global variable variable_name in `ob`.
+ * 
+ * `variable_name` is name of the global variable.
+ * `value` is the data to be stored in the global variable.
+ * `ob` defaults to this_object() if not specified.
+ * 
+ * If `ob` is not specified, then `variable_name` can be any global variable
+ * in the inheritance hierarchy, regardless of scope.  If `ob` is specified,
+ * then `variable_name` must be public scope.
+ * 
+ * This is a potential security hazard and, therefore, you may wish to overload
+ * this function to perform security checks.
+ *
+ * store_variable( "weight", 150, this_player() ) ;
+ *
+ */
+void store_variable(string variable_name, mixed value, void|object ob);
+
+/**
+ * store_class_member
+ *
+ * Store <value> in the <class_element>th member of an <instantiated_class>.
+ * 
+ * Returns an updated version of the <instantiated_class>.
+ *
+ * class person {
+ * string name ;
+ * int age ;
+ * string city ;
+ * }
+ * 
+ * void fun()
+ * {
+ * class person me = new(class person) ;
+ * 
+ * me->name = "Foo" ;
+ * me->age = 42 ;
+ * me->city = "Fooville" ;
+ * 
+ * write( sprintf("%O\n", me) ) ;
+ * 
+ * // Result:
+ * // CLASS( 3 elements
+ * //   "Foo",
+ * //   42,
+ * //   "Fooville"
+ * //  )
+ * 
+ * me = store_class_member( me, 1, 43 ) ;
+ * 
+ * write( sprintf("%O\n", me) ) ;
+ * 
+ * // Result:
+ * // CLASS( 3 elements
+ * //   "Foo",
+ * //   43,
+ * //   "Fooville"
+ * //  )
+ * }
+ *
+ */
+mixed store_class_member(mixed instantiated_class, int class_element, mixed value);
+
+/**
+ * shuffle
+ *
+ * randomly reorders the elements of the given array (changes original!!!)
+ *
+ */
+mixed *shuffle(mixed *arr);
+
+/**
+ * 
+ *
+ * 
+ *
+ */
+
+
+/**
+ * send_nullbyte - sends '\0' to interactive
+ *
+ * sends '\0' to interactive, returns -2 in case of error 1 otherwise
+ *
+ */
+int send_nullbyte(object);
+
+/**
+ * roll_MdN() - dice roll generator where you specify the number of dice and
+the number of sides to each die, with bonus if supplied.
+ *
+ * rolls `sides`-sided die `rolls` number of times and returns the sum
+ * of all rolls
+ * 
+ * if `bonus` is supplied, will add the bonus and return the result.
+ *
+ * // roll a 1d4
+ * roll_MdN(1, 4)
+ * 
+ * // roll 2d6
+ * roll_MdN(2, 6)
+ * 
+ * // roll 1d10 and add 15
+ * roll_MdN(1, 10, 15)
+ * @param {int} rolls - number of dice
+ * @param {int} sides - number of sides on each die
+ * @param {int} bonus - (optional) bonus to add to the roll, defaults to 0
+ */
+int roll_MdN(int rolls, int sides, int bonus);
+
+/**
+ * restore_from_string() - like restore_object(), but restores variables from
+a string where the string is in the same format as from restore_object()
+ *
+ * uses string as restore_object uses file meaning of int the same
+ * @param {string} str - string to restore from
+ * @param {int} flag - defaults to 0
+ */
+void restore_from_string(string str, int flag);
+
+/**
+ * replaceable - check if object is replaceable
+ *
+ * string *func defaults to ({ "create", "__INIT" }) and contains a list of
+ * functions which may be ignored for checking
+ * 
+ * checks if object defines any functions itself (beside create)
+ * 
+ * returns 1 if no and object is not simul_efun object and not ???
+ * 0 otherwise
+ *
+ */
+int replaceable(object, void | string *func);
+
+/**
+ * repeat_string() - repeat a string a certain number of times.
+ *
+ * returns a new string
+ * 
+ * - repeats <= 0: ""
+ * - repeats > 0 original string repeated either int times or the maximum
+ * number of times without getting greater than the maximum string length
+ * 
+ * maxstrlen = 5:
+ * repeat_string("ab", 3) = "abab"
+ * 
+ * maxstrlen >=6:
+ * repeat_string("ab", 3) = "ababab"
+ *
+ */
+string repeat_string(string str, int repeats);
+
+/**
+ * remove_shadow() - remove all shadows from the specified object, or remove
+a specified shadow from another object. does not destruct the shadow.
+ *
+ * ob defaults to this_object()
+ * returns 0 if object is either destroyed or is no shadow and isn't shadowed
+ * returns 1 otherwise
+ * 
+ * ob <- shadow1 <- shadow2
+ * 
+ * remove(shadow2): ob <- shadow1 shadow2
+ * remove(shadow1): ob <- shadow2 shadow1
+ * remove(ob): shadow1 <- shadow2 ob
+ * 
+ * #ifndef NO_SHADOWS
+ *
+ */
+int remove_shadow(object ob);
+
+/**
+ * remove_interactive - removes the interactive object
+ *
+ * If the argument object is interactive and not destructed, cause it to be
+ * disconnected and lose interactive status. Returns 1 when the operation is
+ * successful.
+ * 
+ * This function requires PACKAGE_CONTRIB to be defined in the options file.
+ *
+ */
+int remove_interactive(object interactive);
+
+/**
+ * remove_get_char() - cancels active input_to
+ *
+ * cancels active input_to
+ * set's interactive->carryover = NULL
+ * set's interactive->num_carry = 0
+ * 
+ * returns -3 if argument missing
+ * -2 if object destroyed or not interactive
+ * -1 if no input_to active
+ * 1 otherwise
+ *
+ */
+int remove_get_char(object interactive);
+
+/**
+ * remove_charmode() - switches interactive object into linemode
+ *
+ * switches interactive object into linemode
+ * 
+ * returns -1 if argument missing
+ * -2 in case of error (object destroyed or not interactive)
+ * current input_to flags with char_mode unset
+ *
+ */
+int remove_charmode(object);
+
+/**
+ * real_time
+ *
+ * returns local server time
+ *
+ */
+int real_time();
+
+/**
+ * query_replaced_program
+ *
+ * obiect defaults to this_object()
+ * 
+ * if object called replace_program this function returns the path to the object
+ * it was replaced with
+ *
+ */
+string query_replaced_program(void | object);
+
+/**
+ * query_num
+ *
+ * Warning: English only!!!
+ * 
+ * Converts `num` into a string representation. If `many` is greater than 0
+ * and `num` is greater than `many`, the resulting string is "many".
+ * 
+ * Any `num` greater than 99,999 is always "many", the same for any `num` less
+ * than 0.
+ * @param {int} num - number to convert
+ * @param {int} many - (optional) defaults to 0
+ */
+varargs string query_num(int num, int many);
+
+/**
+ * query_notify_fail
+ *
+ * returns current notify_fail setting (funcp or string)
+ * #ifndef NO_ADD_ACTION
+ *
+ */
+mixed query_notify_fail();
+
+/**
+ * query_ip_port - returns local_port of connection
+ *
+ * object defaults to this_player()
+ * 
+ * returns local_port of connection or 0 if object not interactive
+ *
+ */
+int query_ip_port(void | object);
+
+/**
+ * query_charmode
+ *
+ * returns -1 if argument missing
+ * -2 in case of error (object destroyed or not interactive)
+ * 0 if interactive object is in line mode
+ * !0 otherwise (actual value depends on compile time define)
+ *
+ */
+int query_charmode(object);
+
+/**
+ * program_info
+ *
+ * object defaults to ALL objects
+ * 
+ * returns mapping consinsting of:
+ * 
+ * - header size : int
+ * - code size : int
+ * - function size : int
+ * - var size : int
+ * - class size : int
+ * - inherit size : int
+ * - saved type size : int
+ * - total size : int
+ *
+ */
+mapping program_info(void | object);
+
+/**
+ * pluralize - return plural form
+ *
+ * for english only!
+ * 
+ * returns plural form:
+ * 'a red house' -> 'red houses'
+ * 'a sack of rice' -> 'sacks of rice'
+ *
+ */
+string pluralize(string);
+
+/**
+ * num_classes - returns the number of classes used by object
+ *
+ * returns the number of classes used by object
+ *
+ */
+int num_classes(object);
+
+/**
+ * network_stats
+ *
+ * returns mapping:
+ * 
+ * - incoming packets total : int
+ * - incoming volume total : int
+ * - outgoing packets total : int
+ * - outgoing volume total : int
+ * 
+ * - incoming packets port X : int
+ * - incoming volume port X : int
+ * - outgoing packets port X : int
+ * - outgoing volume port X : int
+ * 
+ * #ifdef PACKAGE_SOCKETS:
+ * 
+ * - incoming packets sockets : int
+ * - incoming volume sockets : int
+ * - outgoing packets sockets : int
+ * - outgoing volume sockets : int
+ *
+ */
+mapping network_stats();
+
+/**
+ * named_livings - return named livings
+ *
+ * returns all those livings [see efun::livings()] which have
+ * set_living_name and enable_command called #ifndef NO_ADD_ACTION
+ *
+ */
+object *named_livings( void );
+
+/**
+ * min() - searches for the minimum value inside an array
+ *
+ * Searches  minimum value for (int|float|string) arrays.  If flag is 0 or
+ * omitted the minimum value will be returned, otherwise the  first  index
+ * of its occurrence.
+ *
+ */
+mixed min(mixed * arr);
+mixed min(mixed * arr, int flag);
+
+/**
+ * memory_summary()
+ *
+ * returns mapping:
+ * ([
+ * "prog1" : ([
+ * "var1" : mem_usage,
+ * ...
+ * ]),
+ * ...
+ * ])
+ *
+ */
+mapping memory_summary();
+
+/**
+ * max() - searches for the maximum value inside an array
+ *
+ * Searches  maximum value for (int|float|string) arrays.  If flag is 0 or
+ * omitted the maximum value will be returned, otherwise the  first  index
+ * of its occurrence.
+ *
+ */
+mixed max(mixed * arr); 
+mixed max(mixed * arr, int flag);
+
+/**
+ * is_daylight_savings_time
+ *
+ * returns 1 if given time in given timezone is within daylight saving region
+ * 0 if not
+ * -1 on error
+ *
+ */
+int is_daylight_savings_time(string, int);
+
+/**
+ * heart_beats - returns an array of all objects with enabled heartbeat
+ *
+ * returns an array of all objects with enabled heartbeat
+ *
+ */
+object *heart_beats( void );
+
+/**
+ * get_garbage() - get all clones without environments or inventories which are
+not shadowing.
+ *
+ * returns array of all (up to **MAX_ARRAY_SIZE**) those cloned(!) objects which
+ * have neither environment nor inventory and aren't shadowing another object
+ * and haven't object->super set
+ *
+ */
+object *get_garbage();
+
+/**
+ * functions() - returns a string array of function names or mixed* array of
+information for all functions in a passed object.
+ *
+ * Returns an array of strings containing the function names found in
+ * <ob>. The functions returned will include all functions, whether public,
+ * protected, or private. The <flag> parameter is by default zero.
+ * 
+ * Flag: 0
+ * Returns: a string array containing function names, including all inherited
+ * functions.
+ * ({ "func1", "func2", "func3", "func4", ... })
+ * 
+ * Flag: 1
+ * Returns: A two-dimensional array of mixed arrays containing additional
+ * information about each function, including all inherited functions.
+ * 
+ * ({
+ * ({
+ * "func1",    // function name
+ * 2,          // number of parameters in function
+ * "int",      // return type of function
+ * "object",   // the first parameter
+ * "string *", // the second parameter
+ * }),
+ * ...
+ * })
+ * 
+ * Flag: 2
+ * Like Flag 0, but excludes inherited functions.
+ * 
+ * Flag: 3
+ * Like Flag 1, but excludes inherited functions.
+ *
+ * @param {object} ob - object to query
+ * @param {int} flag (optional) defaults to 0
+ */
+mixed *functions(object ob, int flag);
+
+/**
+ * function_owner - returns the object defining the given function
+ *
+ * returns the object defining the given function.
+ *
+ */
+object function_owner(function);
+
+/**
+ * file_length - return the line count of a file
+ *
+ * returns
+ * 
+ * - line count
+ * - -1 in case of error (e.g insufficient privs)
+ * - -2 if file is directory
+ *
+ */
+int file_length(string);
+
+/**
+ * fetch_variable - fetch a value stored in an object's global variable
+ *
+ * This efun returns the value stored in the global variable `variable_name`
+ * in ob.
+ * 
+ * `variable_name` is name of the global variable.
+ * `ob` defaults to this_object() if not specified.
+ * 
+ * If `ob` is not specified, then `variable_name` can be any global variable
+ * in the inheritance hierarchy, regardless of scope.  If `ob` is specified,
+ * then `variable_name` must be public scope.
+ * 
+ * This is a potential security hazard and, therefore, you may wish to overload
+ * this function to perform security checks.
+ *
+ * int weight = fetch_variable( "weight", this_player() ) ;
+ * printf("%d\n", weight") ;
+ * 
+ * // result: 150
+ *
+ */
+mixed fetch_variable(string variable_name, void|object ob);
+
+/**
+ * fetch_class_member() - return the value of a specified, indexed member of
+an instantiated class.
+ *
+ * Given an <instantiated_class>, return the value of the <index>th
+ * member. This is particularly useful when you have an anonymous
+ * class with no labels for the data members.
+ *
+ * mixed me = assemble_class( ({ "Foo", 42, "Fooville" }) ) ;
+ * int age ;
+ * string name, city ;
+ * 
+ * name = fetch_class_member( me, 0 ) ;
+ * age = fetch_class_member( me, 1 ) ;
+ * city = fetch_class_member( me, 2 ) ;
+ *
+ */
+mixed fetch_class_member( mixed instantiated_class, int index );
+
+/**
+ * event() - call event_* in other objects with specified parameters. similar
+to call_other, but with no return type.
+ *
+ * Calls "event_" + event_name in target. "event_" + event_name must be a
+ * public function.
+ * 
+ * Target can be a single object or an array of objects.
+ * 
+ * If the target is a single object, the event efun will first call the event
+ * function in the object and then it will call the event function all of the
+ * objects in the target's all_inventory().
+ * 
+ * If the target is an array of objects, the event efun will call the event
+ * function in all of the objects specified. Unlike the single-target version,
+ * it will not cascade to each of the object's inventories.
+ * 
+ * The efun will pass as its first argument the calling object followed by
+ * all of the specified arguments.
+ *
+ * // In a room
+ * 
+ * // will call event_heal_up on the room, and then every object in the room
+ * event( this_object(), "heal_up", 50, 50 ) ;
+ * 
+ * // will call event_heal_up in the results of users() efun
+ * event( users(), "heal_up", 25, 25 ) ;
+ * 
+ * // In a player object
+ * 
+ * // To take advantage of this event, write an event_heal_up in the player
+ * // object to receive the call
+ * void event_heal_up(object source, int health, int mana)
+ * {
+ * message("heal", sprintf("You were healed %d health and %d mana by %O.\n", health, mana, source), this_object()) ;
+ * }
+ *
+ */
+void event(object | object * target, string event_name, mixed *args...);
+
+/**
+ * element_of() - returns random elememt of given array
+ *
+ * returns random elememt of given array
+ *
+ */
+mixed element_of(mixed *arr);
+
+/**
+ * disassemble_class() - given an instantiated class, returns a mixed* array
+with elements comprised of the values of each member of the class.
+ *
+ * Given an <instantiated_class>, return a mixed array containing the
+ * values of all of the members.
+ *
+ * class person {
+ * string name ;
+ * int age ;
+ * string city ;
+ * }
+ * 
+ * void fun()
+ * {
+ * mixed *result ;
+ * class person me = new(class person);
+ * 
+ * me->name = "Foo" ;
+ * me->age = 42 ;
+ * me->city = "Fooville" ;
+ * 
+ * result = disassemble_class( me ) ;
+ * 
+ * write( sprintf("%O\n", result ) ) ;
+ * 
+ * // ({ /* sizeof() == 3 *\/
+ * //   "Foo",
+ * //   42,
+ * //   "Fooville"
+ * // })
+ * }
+ *
+ */
+mixed *disassemble_class( mixed instantiated_class );
+
+/**
+ * debug_message() - logs a debug message
+ *
+ * Prints  the  given message on the <stderr> file desciptor of the driver
+ * and appends it to the debug log.
+ *
+ */
+void debug_message(string msg);
+
+/**
+ * mixed copy(mixed arg) - return a deep copy of an array, buffer, class, or
+mapping
+ *
+ * arg is either one of:
+ * 
+ * - array
+ * - buffer (if compiled into driver)
+ * - class
+ * - mapping
+ * 
+ * returns deep copy
+ * 
+ * This is particularly useful when you wish to have data that is passed
+ * by reference, but do not want to alter the original.
+ *
+ */
+mixed copy(mixed arg);
+
+/**
+ * compressedp() - returns if interactive connection uses telopt compress
+ *
+ * returns if interactive connection uses telopt compress
+ * #ifdef PACKAGE_COMPRESS
+ *
+ */
+int compressedp(object ob);
+
+/**
+ * classes() - return names of classes used by object
+ *
+ * Return a string array consisting of names of classes used by <ob>.
+ * 
+ * The <verbose> parameter is optional and by default 0.
+ * 
+ * If <verbose> is non-zero, then  additional  information  will  be
+ * returned.
+ *
+ * string *classes_used = classes( ob ) ;
+ * // ({ "class_name", }) ;
+ * 
+ * mixed *classes_used = classes( ob, 1 ) ;
+ * 
+ * // ({
+ * //     ({
+ * //         "class_name",
+ * //         ({
+ * //             "member_name",
+ * //             "type"
+ * //         }),
+ * //         ...
+ * //     }),
+ * //     ...
+ * // })
+ *
+ */
+mixed *classes(object ob, int verbose);
+
+/**
+ * base_name - return the base name without object id (OID)
+ *
+ * In the first version, return the segment of the <text> up to, but
+ * not including the first occurrence of #.
+ * 
+ * Like the first version, but performs file_name on <ob> first.
+ * 
+ * Like the second version, but the object is this_object().
+ *
+ * string path = base_name( "/std/object#123" ) ;  // "/std/object"
+ * 
+ * object ob = new("/std/object) ;
+ * string path = base_name( ob ) ;                 // "/std/object"
+ * 
+ * // in /std/object
+ * string path = base_name() ;                     // "/std/object"
+ *
+ */
+string base_name(string text);
+string base_name(object ob);
+string base_name();
+
+/**
+ * assemble_class() - provided an array, return a class composed of the members
+of that array.
+ *
+ * Takes an array of <elements> and returns an instantiated class.
+ *
+ * mixed *elements = ({ "Foo", 42, "Fooville" }) ;
+ * mixed cl = assemble_class( elements ) ;
+ * 
+ * write( sprintf( "%O\n", cl ) ) ;
+ * 
+ * // CLASS( 3 elements
+ * //   "Foo",
+ * //   42,
+ * //   "Fooville"
+ * //  )
+ *
+ */
+mixed assemble_class( mixed *elements );
+
+/**
+ * abs() - return the absolute value of a number
+ *
+ * Returns the absolute value of the supplied <number>.
+ *
+ * int value = abs( 10 );      // 10
+ * int value = abs( -10 );     // 10
+ * float value = abs( 3.14 );  // 3.140000
+ * float value = abs( -3.14 ); // 3.140000
+ *
+ */
+mixed abs( int | float number );
+