ZLib 12 Updates!
Tiny update: added abs(), for both ints and floats.
Much bigger update: There have been several requests for (and I've seen quite a few other scripters implementing) wrappers for print() that depend on a "verbosity" setting. In addition, I don't like the all-too-common situation of
PHP:
if (condition) {
print("message");
return true / false;
}
just to be able to return a boolean with user feedback. I added the error() command to ZLib a while ago as a way around this, but only for false.
ZLib's new
vprint() is a way to kill all the birds with one stone:
boolean vprint(string message, string color, int level)
boolean vprint(string message, int level)
The parameters
message and
color behave exactly the same as in print(), so let's talk about
level.
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.
Conversion
NOTE:
This function deprecates error(), since vprint(message,-X) is identical. I'll give everyone a month or so to make the changes, and then will be removing error() from ZLib.
I will be converting all of my scripts to use this system, and recommend that others who import ZLib do the same, for consistency of user experience. To convert your script, replace every instance of print(), abort(), and error() with the new vprint() for a new level of universal user control over script feedback! I also recommend replacing every "return true" and "return false" with a more meaningful vprint() command.