diff options
Diffstat (limited to 'lib/help/lua_util.txt')
-rw-r--r-- | lib/help/lua_util.txt | 898 |
1 files changed, 0 insertions, 898 deletions
diff --git a/lib/help/lua_util.txt b/lib/help/lua_util.txt deleted file mode 100644 index 8886a2b4..00000000 --- a/lib/help/lua_util.txt +++ /dev/null @@ -1,898 +0,0 @@ -|||||oy - -#####R /----------------------------------------\ -#####R < util.pkg functions helper file > -#####R \----------------------------------------/ - ----------------------------------------------------------------------- - -#####R=== bst === - -#####GDeclaration - s32b bst(s32b what, s32b t); - -#####GFile - util.c - -#####GComment -/* - * Break scalar time - */ - -#####GDescription -Return the minute, hour, day, or year for turn "t". One turn takes 7.5 -seconds. - -#####GParameters -> "what" is the unit to be returned and must be one of - MINUTE (number of turns per minute, which is 8) - HOUR (number of turns per hour, which is 480) - DAY (number of turns per day, which is 11,520) - YEAR (number of turns per year, which is 4,204,800) -> "t" is the number of turns. - ----------------------------------------------------------------------- - -#####R=== path_build === - -#####GDeclaration - errr path_build(char *buf, int max, cptr path, cptr file); - -#####GFile - util.c - -#####GComment -/* -* Create a new path by appending a file (or directory) to a path -* -* This requires no special processing on simple machines, except -* for verifying the size of the filename, but note the ability to -* bypass the given "path" with certain special file-names. -* -* Note that the "file" may actually be a "sub-path", including -* a path and a file. -* -* Note that this function yields a path which must be "parsed" -* using the "parse" function above. -*/ - -#####GDescription -Append file "file" to path "path" and return the result in "buf". The -length of "buf" is a maximum of "max" characters. If "file" starts -with '~' then return "file". If "file" starts with the path separator -and the path separator is not blank then return "file". If there is no -path then return "file". Otherwise return "path" + path separator + -"file". The path separator is defined in "H-config.h". - -#####GParameters -> "buf" contains the new path. -> "max" is the maximum number of characters allowed in "buf". -> "path" is the original path. -> "file" is the original file. - ----------------------------------------------------------------------- - -#####R=== move_cursor === - -#####GDeclaration - void move_cursor(int row, int col); - -#####GFile - util.c - -#####GComment -/* -* Move the cursor -*/ - -#####GDescription -Move the cursor to row "row" and column "col". - -#####GParameters -> "row" is the row the cursor is to be moved to. -> "col" is the column the cursor is to be moved to. - ----------------------------------------------------------------------- - -#####R=== inkey === - -#####GDeclaration - char inkey(void); - -#####GFile - util.c - -#####GComment -/* -* Get a keypress from the user. -* -* This function recognises a few "global parameters". These are variables -* which, if set to TRUE before calling this function, will have an effect -* on this function, and which are always reset to FALSE by this function -* before this function returns. Thus they function just like normal -* parameters, except that most calls to this function can ignore them. -* -* If "inkey_xtra" is TRUE, then all pending keypresses will be flushed, -* and any macro processing in progress will be aborted. This flag is -* set by the "flush()" function, which does not actually flush anything -* itself, but rather, triggers delayed input flushing via "inkey_xtra". -* -* If "inkey_scan" is TRUE, then we will immediately return "zero" if no -* keypress is available, instead of waiting for a keypress. -* -* If "inkey_base" is TRUE, then all macro processing will be bypassed. -* If "inkey_base" and "inkey_scan" are both TRUE, then this function will -* not return immediately, but will wait for a keypress for as long as the -* normal macro matching code would, allowing the direct entry of macro -* triggers. The "inkey_base" flag is extremely dangerous! -* -* If "inkey_flag" is TRUE, then we will assume that we are waiting for a -* normal command, and we will only show the cursor if "hilite_player" is -* TRUE (or if the player is in a store), instead of always showing the -* cursor. The various "main-xxx.c" files should avoid saving the game -* in response to a "menu item" request unless "inkey_flag" is TRUE, to -* prevent savefile corruption. -* -* If we are waiting for a keypress, and no keypress is ready, then we will -* refresh (once) the window which was active when this function was called. -* -* Note that "back-quote" is automatically converted into "escape" for -* convenience on machines with no "escape" key. This is done after the -* macro matching, so the user can still make a macro for "backquote". -* -* Note the special handling of "ascii 30" (ctrl-caret, aka ctrl-shift-six) -* and "ascii 31" (ctrl-underscore, aka ctrl-shift-minus), which are used to -* provide support for simple keyboard "macros". These keys are so strange -* that their loss as normal keys will probably be noticed by nobody. The -* "ascii 30" key is used to indicate the "end" of a macro action, which -* allows recursive macros to be avoided. The "ascii 31" key is used by -* some of the "main-xxx.c" files to introduce macro trigger sequences. -* -* Hack -- we use "ascii 29" (ctrl-right-bracket) as a special "magic" key, -* which can be used to give a variety of "sub-commands" which can be used -* any time. These sub-commands could include commands to take a picture of -* the current screen, to start/stop recording a macro action, etc. -* -* If "angband_term[0]" is not active, we will make it active during this -* function, so that the various "main-xxx.c" files can assume that input -* is only requested (via "Term_inkey()") when "angband_term[0]" is active. -* -* Mega-Hack -- This function is used as the entry point for clearing the -* "signal_count" variable, and of the "character_saved" variable. -* -* Hack -- Note the use of "inkey_next" to allow "keymaps" to be processed. -* -* Mega-Hack -- Note the use of "inkey_hack" to allow the "Borg" to steal -* control of the keyboard from the user. -*/ - -#####GDescription -Get a keypress from the user. - ----------------------------------------------------------------------- - -#####R=== cmsg_print === - -#####GDeclaration - void cmsg_print(byte color, cptr msg); - -#####GFile - util.c - -#####GComment -/* -* Output a message to the top line of the screen. -* -* Break long messages into multiple pieces (40-72 chars). -* -* Allow multiple short messages to "share" the top line. -* -* Prompt the user to make sure he has a chance to read them. -* -* These messages are memorised for later reference (see above). -* -* We could do "Term_fresh()" to provide "flicker" if needed. -* -* The global "msg_flag" variable can be cleared to tell us to -* "erase" any "pending" messages still on the screen. -* -* XXX XXX XXX Note that we must be very careful about using the -* "msg_print()" functions without explicitly calling the special -* "msg_print(NULL)" function, since this may result in the loss -* of information if the screen is cleared, or if anything is -* displayed on the top line. -* -* XXX XXX XXX Note that "msg_print(NULL)" will clear the top line -* even if no messages are pending. This is probably a hack. -*/ - -#####GDescription -In color "color", output message "msg" to the top line of the screen. -If the message is blank or has more than 1000 characters, nothing is -printed. Long messages are split after the 40th character and before -the 72nd character. - -#####GParameters -> "color" is the color of the message. - *****fields.txt*0[colors] -> "msg" is the message. - ----------------------------------------------------------------------- - -#####R=== msg_print === - -#####GDeclaration - void msg_print(cptr msg); - -#####GFile - util.c - -#####GComment -/* Hack -- for compatibility and easy sake */ - -#####GDescription -Print message "msg" in white (see cmsg_print() above). - -#####GParameters -> "msg" is the message. - ----------------------------------------------------------------------- - -#####R=== screen_save === - -#####GDeclaration - void screen_save(void); - -#####GFile - util.c - -#####GComment -/* - * Save the screen, and increase the "icky" depth. - * - * This function must match exactly one call to "screen_load()". - */ - -#####GDescription -Save a screen shot. - ----------------------------------------------------------------------- - -#####R=== screen_load === - -#####GDeclaration - void screen_load(void); - -#####GFile - util.c - -#####GComment -/* - * Load the screen, and decrease the "icky" depth. - * - * This function must match exactly one call to "screen_save()". - */ - -#####GDescription -Load a previously saved screen shot. - ----------------------------------------------------------------------- - -#####R=== c_put_str === - -#####GDeclaration - void c_put_str(byte attr, cptr str, int row, int col); - -#####GFile - util.c - -#####GComment -/* -* Display a string on the screen using an attribute. -* -* At the given location, using the given attribute, if allowed, -* add the given string. Do not clear the line. -*/ - -#####GDescription -Put string "str" at row "row" and column "col" with attribute "attr". - -#####GParameters -> "attr" is the color of the message. - *****fields.txt*0[colors] -> "msg" is the message. -> "row" is the row the message is to be printed at. -> "col" is the column the message is to be printed at. - ----------------------------------------------------------------------- - -#####R=== c_prt === - -#####GDeclaration - void c_prt(byte attr, cptr str, int row, int col); - -#####GFile - util.c - -#####GComment -/* -* Display a string on the screen using an attribute, and clear -* to the end of the line. -*/ - -#####GDescription -Clear row "row" from column "col". Put string "str" at "row", "col" -with attribute "attr". - -#####GParameters -> "attr" is the color of the message. - *****fields.txt*0[colors] -> "msg" is the message. -> "row" is the row the message is to be printed at. -> "col" is the column the message is to be printed at. - ----------------------------------------------------------------------- - -#####R=== clear_from === - -#####GDeclaration - void clear_from(int row); - -#####GFile - util.c - -#####GComment -/* -* Clear part of the screen -*/ - -#####GDescription -Clear the screen from row "row" onwards. - -#####GParameters -> "row" is the first row of the screen to be cleared. - ----------------------------------------------------------------------- - -#####R=== askfor_aux === - -#####GDeclaration - bool askfor_aux(char *buf, int len); - -#####GFile - util.c - -#####GComment -/* -* Get some input at the cursor location. -* Assume the buffer is initialized to a default string. -* Note that this string is often "empty" (see below). -* The default buffer is displayed in yellow until cleared. -* Pressing RETURN right away accepts the default entry. -* Normal chars clear the default and append the char. -* Backspace clears the default or deletes the final char. -* ESCAPE clears the buffer and the window and returns FALSE. -* RETURN accepts the current buffer contents and returns TRUE. -*/ - -#####GDescription -Get string "buf" from the screen. "buf" is to be no more than "len" -bytes. The string starts at the current cursor position. The length -can not exceed the number of bytes from the cursor to the end of the -line. Accept user input until the escape or return key is pressed. - -#####GParameters -> "buf" is the string returned from the screen. -> "len" is the length of the string. If it is <1 it is forced to 1. - ----------------------------------------------------------------------- - -#####R=== get_string === - -#####GDeclaration - bool get_string(cptr prompt, char *buf, int len); - -#####GFile - util.c - -#####GComment -/* -* Get a string from the user -* -* The "prompt" should take the form "Prompt: " -* -* Note that the initial contents of the string is used as -* the default response, so be sure to "clear" it if needed. -* -* We clear the input, and return FALSE, on "ESCAPE". -*/ - -#####GDescription -Print prompt "prompt" at the top-left corner of the screen and return -response "buf" which will have a maximum length "length". If ESCAPE -is entered, the function returns FALSE, otherwise it returns TRUE. - -#####GParameters -> "prompt" is the prompt for input. -> "buf" is the returned response. -> "len" is the maximum length of the string. - ----------------------------------------------------------------------- - -#####R=== get_check === - -#####GDeclaration - bool get_check(cptr prompt); - -#####GFile - util.c - -#####GComment -/* -* Verify something with the user -* -* The "prompt" should take the form "Query? " -* -* Note that "[y/n]" is appended to the prompt. -*/ - -#####GDescription -Ask the user question "prompt" which requires a yes/no answer. The -prompt appears in the top-left corner of the screen. A response of -'Y' (either case) returns TRUE. A response of 'N' (either case) or -ESCAPE returns FALSE. - -#####GParameters -> "prompt" is the question asked. It has a maximum length of 70 - characters. - ----------------------------------------------------------------------- - -#####R=== get_com_lua === - -#####GDeclaration - bool get_com_lua @ get_com(cptr promtp, int *com); - -#####GFile - util.c - -#####GComment -/* -* Prompts for a keypress -* -* The "prompt" should take the form "Command: " -* -* Returns TRUE unless the character is "Escape" -*/ - -#####GDescription -Ask the user for command "prompt" and return the key press "com". A -response of ESCAPE returns FALSE. All other responses return TRUE. - -#####GParameters -> "prompt" is the prompt for the key press. -> "com" is the returned key press. - ----------------------------------------------------------------------- - -#####R=== get_quantity === - -#####GDeclaration - s32b get_quantity(cptr prompt, s32b max); - -#####GFile - util.c - -#####GComment -/* -* Request a "quantity" from the user -* -* Hack -- allow "command_arg" to specify a quantity -*/ - -#####GDescription -Ask the user for quantity "prompt" of maximum value "max" and return -a quantity. If the user quantity is higher than the maximum then the -maximum is returned. If the response is a letter then the maximum is -returned. If the user quantity is negative then zero is returned. - -#####GParameters -> "prompt" is the prompt for a quantity. -> "max" is the maximum value allowed. - ----------------------------------------------------------------------- - -#####R=== test_monster_name === - -#####GDeclaration - int test_monster_name(cptr name); - -#####GFile - util.c - -#####GComment -/* - * Given monster name as string, return the index in r_info array. Name - * must exactly match (look out for commas and the like!), or else 0 is - * returned. Case doesn't matter. -GSN- - */ - -#####GDescription -Return the monster index for monster with name "name". If no match is -found then zero is returned. - -#####GParameters -> "name" is the monster name. - ----------------------------------------------------------------------- - -#####R=== test_item_name === - -#####GDeclaration - int test_item_name(cptr name); - -#####GFile - util.c - -#####GComment -/* - * Given item name as string, return the index in k_info array. Name - * must exactly match (look out for commas and the like!), or else 0 is - * returned. Case doesn't matter. -DG- - */ - -#####GDescription -Return the item index for item with name "name". If no match is found -then zero is returned. - -#####GParameters -> "name" is the item name. - ----------------------------------------------------------------------- - -#####R=== luck === - -#####GDeclaration - int luck(int min, int max); - -#####GFile - xtra1.c - -#####GComment -/* - * Return a luck number between a certain range - */ - -#####GDescription -Return a number for luck between minimum "min" and maximum "max". The -value begins with the player's current luck. The value is forced to -be between -30 and +30. 30 is added to give a value between 0 and 60. -The value is multiplied by the range (maximum - minimum) and divided -by 60. The value is increased by the minimum. The value is returned. - -For example, if the player's current luck is 15, the minimum is -10, -and the maximum is 10 (range 20), then the value returned is -(45 * 20) / 60 which is 900 / 60 which is 15 + the minimum -10 gives -a returned value of 5. - -#####GParameters -> "min" is the minimum luck. -> "max" is the maximum luck. Beware: this should be greater than the - minimum but it is not checked! - ----------------------------------------------------------------------- - -#####R=== get_player_race_name === - -#####GDeclaration - cptr get_player_race_name(int pr, int ps); - -#####GFile - util.c - -#####GComment -(none) - -#####GDescription -Return the name for player race "pr" and player sub-race "ps". - -#####GParameters -> "pr" is the index for player race. -> "ps" is the index for player sub-race. - ----------------------------------------------------------------------- - -#####R=== quit === - -#####GDeclaration - void quit(cptr str); - -#####GFile - z-util.c - -#####GComment -/* - * Exit (ala "exit()"). If 'str' is NULL, do "exit(0)". - * If 'str' begins with "+" or "-", do "exit(atoi(str))". - * Otherwise, plog() 'str' and exit with an error code of -1. - * But always use 'quit_aux', if set, before anything else. - */ - -#####GDescription -Quit the game. If "str" is a string then write the string to the -error file or screen. If "str" is a number then exit with the -number as the exit code. - -#####GParameters -> "str" is an error message or exit code. - ----------------------------------------------------------------------- - -#####R=== dump_hooks === - -#####GDeclaration - void dump_hooks(); - -#####GFile - plots.c - -#####GComment -(none) - -#####GDescription -Print the name and type (C or Lua) of hooks in the hook list. - ----------------------------------------------------------------------- - -#####R=== add_hook_script === - -#####GDeclaration - void add_hook_script(int h_idx, char *script, cptr name); - -#####GFile - plots.c - -#####GComment -(none) - -#####GDescription -To hook list with index "h_idx", add a script with script file -"script" and name "name" as a Lua hook if a hook with that name -does not already exist. - -#####GParameters -> "h_idx" is the index of the hook list in the array of hook lists. -> "script" is the name of the script file. -> "name" is the name of the hook to be added. - ----------------------------------------------------------------------- - -#####R=== del_hook_name === - -#####GDeclaration - void del_hook_name(int h_idx, cptr name); - -#####GFile - plots.c - -#####GComment -(none) - -#####GDescription -Search hook list with index "h_idx" and remove the hook with name -"name". - -#####GParameters -> "h_idx" is the index of the hook list in the array of hook lists. -> "name" is the name of the hook to be removed. - ----------------------------------------------------------------------- - -#####R=== pern_dofile === - -#####GDeclaration - bool pern_dofile(char *file); - -#####GFile - script.c - -#####GComment -(none) - -#####GDescription -Parse the Lua script file "file". - -#####GParameters -> "file" is the Lua script file to be parsed. - ----------------------------------------------------------------------- - -#####R=== intMod === - -#####GDeclaration - s32b intMod(s32b a, s32b b); - -#####GFile - script.c - -#####GComment -(none) - -#####GDescription -Return the result of operation "a" mod "b" (a % b). - -#####GParameters -> "a" is a number. -> "b" is a number. - ----------------------------------------------------------------------- - -#####R=== intAnd === - -#####GDeclaration - s32b intAnd(s32b a, s32b b); - -#####GFile - script.c - -#####GComment -(none) - -#####GDescription -Return the result of bitwise operation "a" AND "b" (a & b). - -#####GParameters -> "a" is a number. -> "b" is a number. - ----------------------------------------------------------------------- - -#####R=== intOr === - -#####GDeclaration - s32b intOr(s32b a, s32b b); - -#####GFile - script.c - -#####GComment -(none) - -#####GDescription -Return the result of bitwise operation "a" OR "b" (a | b). - -#####GParameters -> "a" is a number. -> "b" is a number. - ----------------------------------------------------------------------- - -#####R=== intXor === - -#####GDeclaration - s32b intXor(s32b a, s32b b); - -#####GFile - script.c - -#####GComment -(none) - -#####GDescription -Return the result of bitwise operation "a" XOR "b" (a ^ b). - -#####GParameters -> "a" is a number. -> "b" is a number. - ----------------------------------------------------------------------- - -#####R=== intShiftl === - -#####GDeclaration - s32b intShiftl(s32b a, s32b b); - -#####GFile - script.c - -#####GComment -(none) - -#####GDescription -Return the result of bitwise operation "a" << "b". - -#####GParameters -> "a" is a number. -> "b" is a number. - ----------------------------------------------------------------------- - -#####R=== intShiftr === - -#####GDeclaration - s32b intShiftr(s32b a, s32b b); - -#####GFile - script.c - -#####GComment -(none) - -#####GDescription -Return the result of bitwise operation "a" >> "b". - -#####GParameters -> "a" is a number. -> "b" is a number. - ----------------------------------------------------------------------- - -#####R=== intBitNot === - -#####GDeclaration - s32b intBitNot(s32b b); - -#####GFile - script.c - -#####GComment -(none) - -#####GDescription -Return the result of bitwise operation NOT "b" (~ b). - -#####GParameters -> "b" is a number. - ----------------------------------------------------------------------- - -#####R=== register_savefile === - -#####GDeclaration - void register_savefile(int num); - -#####GFile - loadsave.c - -#####GComment -/* - * Add num slots to the savefile - */ - -#####GDescription -Add "num" slots to the save file. - -#####GParameters -> "num" is the number of slots to add to the savefile. If num is <0 - then "num" is forced to zero. - ----------------------------------------------------------------------- - -#####R=== save_number_key === - -#####GDeclaration - void save_number_key(char *key, s32b val); - -#####GFile - util.c - -#####GComment -(none) - -#####GDescription -Save the length of key "key", the key itself, and the value "val" as -bytes in the savefile. - -#####GParameters -> "key" is the key string for the value. -> "val" is the value to be saved. - ----------------------------------------------------------------------- - - - -Back to the *****lua.hlp*0[lua help index] . - - - [[[[[gThis file by Chris Hadgis] - |