Zlib

About Zarqon's Useful Function Library

Behold, a single function library containing most of zarqon's most useful functions, which will be used by most of his scripts. He grew tired of tweaking a function that was in multiple scripts and making sure he had changed them all. It would be nice, he thought in his customary italics, to have it in just one place.

In choosing which functions to include, he have tried to select only those functions which are a) super useful, or 2) needed by another of the included functions. It's a bit less efficient in terms of individual scripts, but in terms of repeated code across a family of scripts it is far simpler.

Functions

excise

string excise(string source ,string start ,string end )

• The original source string
• start after this string
• end before this string

This function returns a portion of the source string, from after the first occurrence of start to just before the first occurrence of end. If either start or end are missing, it will return an empty string. You can also supply either start or end as blank strings to specify the actual start or end of the source string.

normalized

string normalized(string mixvar ,string type )

• mixvar is the string to normalize
• type is the datatype to normalize to

Returns mixvar, normalized to the specified mafia type, which can be any primitive type or ASH datatype constant. For example, normalized("badger", "familiar") would return "Astral Badger".

rnum

string rnum(int n )

string rnum(float n )

string rnum(float n ,int place )

• n is a number
• place is the number of decimal places to round to

Returns your number n as a human-readable string. For ints, this means it adds commas where appropriate. For floats, it also rounds to the nearest place after the decimal. Default place for the float-only version is 2, although it may display fewer digits if they are 0's. Examples: rnum(12580) => "12,580", rnum(3.14152964,3) => "3.142", rnum(4.00008) => "4", rnum(123456789.87654321) => "123,456,789.88". Recommended as a substitute for to_string().

set_avg

void set_avg(float to_add ,string which_prop )

• to_add is the data point to add
• which_prop is the property to add data to

Useful for adding spading to scripts. Adds one more statistic to an average value being stored in a property. For example, calling this script three times with the values 2, 4, and 6 for to_add would result in the property which_prop containing "4.0:3", with 4.0 being the average of the three numbers added and 3 being the amount of numbers averaged.

get_avg

float get_avg(string which_prop )

• which_prop is the property to access

Returns an average value set by set_avg().

eval

float eval(string expression ,float [string]  values )

• expression is the base expression
• values is a map of values to replace

By Jason Harper. Evaluates expression as a math expression, and allows you to substitute values for variables, as described in much greater detail here. A brief version of this documentation is also included in ZLib. (NB: This section needs more infoz.)

vprint

boolean vprint(string message ,int level )

boolean vprint(string message ,string color ,int level )

• message and color are used as in the function print()
• level is a verbosity reference

Wrapper for print() and abort(), prints message depending on vars["verbosity"] setting. It has a boolean return value so it can replace { print(message); return t/f; } if level == 0: abort with message if level > 0: prints message if verbosity >= level, returns true if level < 0: prints message if verbosity >= abs(level), returns false

First, level controls the return value -- if level is positive, vprint will return true; if negative, it will return false. If level is 0, vprint() will abort with the specified message. You can see now that vprint already replaces both abort() and error(). I recommend using it in place of abort() in case a savvy user wishes to avoid or otherwise handle aborts somehow.

So this takes care of my annoyance with needing brackets and two commands just to return a boolean along with user feedback. How about the verbosity issue?

Ladies and gentlement, there is now a new ZLib setting "verbosity" (integer). If the absolute value of level is more than verbosity, the message will not be printed. This allows users to control the chattiness of scripts, and allows authors to include debug print statements which can be shown by setting verbosity high.

Recommendations for Verbosity Levels in vprint()

0: abort error

+/- 1: absolutely essential (and non-cluttering) information -- use very sparingly, since a verbosity of 1 is basically "silent mode"

+/- 2: important and useful info -- this should generally be your base level for your most important messages

+/- 4: interesting but non-essential information

+/- 6: info which an overly curious person might like to see on their CLI

+/- 10: details which are only helpful for debugging, such as "begin/end functionname()" or "current value of variable: value"

This will allow users who want extra levels of detail printed to see that detail without cluttering the CLI for users who don't prefer to see all the details. In addition, it allows users to specify a verbosity of 0 to see ONLY mafia output (no script output at all), which could prove handy.

There is also a version of vprint() without the color parameter. The default color is black for positive values of level, and red for negative values. So, basically you don't need to use the version with color unless you want to specify a different color or override the default colors.

vprint_html

boolean vprint_html(string message ,int level )

• message is used as in the function print_html()
• level is a verbosity reference

Same as vprint() above, but wraps print_html().

abs

int abs(int n )

float abs(float n )

• n is a number of either int or float type.

Returns the absolute value of the number n in the same datatype as supplied.

minmax

float minmax(float a ,float min ,float max )

• a is the original number
• min is the minimum return value
• max is the maximum return value

Returns a, but no less than min and no more than max.

string check_version(string soft, string prop, string thisver, int thread)

Server-friendly once-daily version-checking. (Also hyphen-friendly.) If the user hasn't checked yet today, visits the specified thread in this forum to find the current version of your script. The thread must include "soft version" for the version info to be successfully parsed. Optionally, you may include "[requires revision XXXX]" in the post if you want to indicate a required minimum revision of mafia. If a new version is available, alerts the user in large text and provides an update link, then waits for a sufficiently annoying interval in case the user wishes to abort operation to go update the script. The return value is a blank string unless an update is found, in which case it is a

containing the update message. This allows this function to work equally well for relay scripts. The current version is stored to a daily property, standardized to "_version_"+prop. Example:

Code:

check_version("Hardcore Checklist","checklist","1.2.7",1045);

boolean load_current_map(string fname, aggregate dest) Allows scripts to automatically update data files. Loads a map named fname.txt, either from disk or from the Map Manager if an update is available. (Yes, this means you shouldn't include ".txt" in the parameter.) The first time you try to load a given map on a given day, it checks if your version is current. If so, it merely loads it from disk. If not, it overwrites your local map with the map stored on the Map Manager.

int setvar(string varname, mixed dfault) Allows you to define a per-character script setting to be used across all scripts that use ZLib. The first time the script is run, the variable will be set to dfault. To reference this setting, use vars[varname] in any script that includes ZLib, keeping in mind that this will always be a string. Detailed information posted here.

int have_item(string tolookup) A residual function, used by the following and probably in several other scripts. Returns the amount of an item you have both in your inventory and equipped.

float has_goal(item whatsit) Returns the chance that an item is or results in a goal. If is_goal(item) == true or it's a bounty item, returns 1.0. Otherwise, returns the chance that you would get a goal from using the item. For example, with a goal of black pepper, has_goal($item[black picnic basket]) would return 0.58. Many thanks to aqualectrix for creating and sharing the container items results map.

float has_goal(monster m) Making use of the above function, returns the percent chance that encountering a given monster will result in a goal, taking into account +items, pickpocket availability (and +pickpocket), and Torso. For instance, with no +item and black pepper as a goal, has_goal($monster[black widow]) would return 0.087 (0.58 basket contains pepper * 0.15 basket drop rate). Also note that it will add multiple goals together, so with white pixels as a goal, a Blooper would return 2.1.

float has_goal(location l) Returns the chance that adventuring at a given location will yield a goal. For our black pepper example, has_goal($location[black forest]) would return 0.0174 (0.2 black widow appearance rate * 0.087 chance that a widow has black pepper). Presently this accounts for combat frequency modifiers but not Olfaction, and it will be off for areas with noncombats that grant goals, because it assumes that all noncombats do not yield items.

boolean obtain(int n, string cond, location locale) Attempts to get n (-existing) of cond, either by purchasing (if you have the mafia preference set), pulling from Hangk's, or adventuring at locale. It also works with choiceadvs.

boolean use_upto(int n, item doodad, boolean purchase) Gets (if purchase is true) and uses n doodads if possible. Otherwise, uses as many as you have up to n.

boolean resist(element req, boolean reallydoit) Returns whether you are able to resist a given element, or if reallydoit is true, attempts to actually achieve that resistance (casting buffs, changing gear, or equipping your Exotic Parrot), and returns its success.

int my_defstat() Returns the value of your buffed defense stat, taking into account Hero of the Half-Shell.

int get_safemox(location wear) Using mafia's location/monster data, returns the safe moxie of a given zone.

boolean auto_mcd(int safemox) boolean auto_mcd(monster mob) boolean auto_mcd(location place) If your automcd setting is true, automatically adjusts your mind-control device for maximum stat gains based on safemox (or the safe moxie for place or mob) and your threshold setting. Does not adjust for MCD-sensitive areas (certain bosses, Slime Tube), or areas with no known combats.

familiar best_fam(string ftype) Returns your heaviest familiar of a given type (currently possible: items, meat, produce, stat, delevel). If your is_100_run setting is anything other than $familiar[none], returns that familiar (so you don't have to make the check in your script).

boolean send_gift(string to, string message, int meat, int[item] goodies, string insidenote) boolean send_gift(string to, string message, int meat, int[item] goodies) Self-explanatory, really. Sends a gift to a player, able to split large amounts of items, useful return value.

boolean kmail(string to, string message, int meat, int[item] goodies, string insidenote) boolean kmail(string to, string message, int meat, int[item] goodies) boolean kmail(string to, string message, int meat) Sends a kmail to a player, returning true if the kmail is successfully sent. Handles splitting the message into multiple messages if the number of item types is too large. Returns the result of send_gift() if the intended recipient is unable to receive the message due to being in HC or somesuch. Note that you can also specify the message to be used inside gifts in that case. Use "\n" to specify a new line in the message.

Making use of Zlib

To include this library in your script, simply add the following towards the top of your script:

import "zlib.ash";

Then all these functions will be available in your script. Have fun!

More Information

See the thread for ZLib on the mafia forum here.