$string_utils
defines a number of
verbs useful for performing operations on strings.
{Verb} list explode (list subject [, str break])
This verb is used to explode a string into a list of substrings separated by runs of break as the delimiting character. If break is not specified it defaults to space. As an example:
$string_utils:explode("This is a test");
will return the list
{"This", "is", "a", "test"2
{Verb} str from_list (list list [, str separator])
This verb is used to implode the string representations of the elements
of a list into a single string, each pair being separated by
separator. which defaults to the empty string. This function is
essentially the inverse of :explode
. Note that the elements of
list need not be strings themselves, as the function tostr
is applied to each element before it is catenated. As an example, to
reassemble the list above into the original string, with just one space
between words, you could write:
oldstr = $string_utils:from_list({"This", "is", "a", "test"2, " ");
{Verb} object match (str string [, list obj-list, str prop-name]*)
This verb is used to search for a match to string in all the
specified properties of all the specified objects, returning either
object, $ambiguous_match
or $failed_match
.
Each obj-list should be a list of objects or a single object, which is treated as if it were a list of that object. Each prop-name should be a string naming a property on every object in the corresponding obj-list. The value of that property in each case should be either a string or a list of strings.
The argument string is matched against all of the strings in the property values.
If it exactly matches exactly one of them, the object containing that
property is returned. If it exactly matches more than one of them,
$ambiguous_match
is returned.
If there are no exact matches, then partial matches are considered, ones
in which the given string is a prefix of some property string. Again,
if exactly one match is found, the object with that property is
returned, and if there is more than one match, $ambiguous_match
is returned.
Finally, if there are no exact or partial matches, then
$failed_match
is returned.
{Verb} str from_value (item value [, str quote_strings [, num list_depth]])
This verb is used to print the given value into a string. Note that
quote_strings defaults to 0 (false), and list_depth
defaults to 1. This is best described by example:
$string_utils:from_value(v) gives: value result 5 "5" 5 + 3 "8" "5 + 3" "5 + 3" {2 "{2" {1,2,32 "{1, 2, 32" {1, {2, 32, 42 "{1, {list2, 42" {"1", {2, 32, 42 "{1, {list2, 42" $string_utils:from_value(value, 1) gives: value result 5 "5" 5 + 3 "8" "5 + 3" "\"5 + 3\"" {2 "{2" {1,2,32 "{1, 2, 32" {1, {2, 32, 42 "{1, {list2, 42" {"1", {2, 32, 42 "{\"1\", {list2, 42" $string_utils:from_value(value, 0, 2) gives: value result 5 "5" 5 + 3 "8" "5 + 3" "5 + 3" {2 "{2" {1,2,32 "{1, 2, 32" {1, {2, 32, 42 "{1, {2, 32, 42" {"1", {2, 32, 42 "{1, {2, 32, 42" $string_utils:from_value( value, 1, 2 ) gives: value result 5 "5" 5 + 3 "8" "5 + 3" "\"5 + 3\"" {2 "{2" {1,2,32 "{1, 2, 32" {1, {2, 32, 42 "{1, {2, 32, 42" {"1", {2, 32, 42 "{\"1\", {2, 32, 42"
It is interesting to note that :from_value
calls itself
recursively, to evaluate lists.
{Verb} str pronoun_sub (str text [, obj who])
This verb is used to substitute the pronoun properties of who in
all occurances of %s,%o,%p,%r in text. who is optional, and
defaults to player. Also `%n', `%d', `%i', `%t',
`%%' are substituted by player
, dobj
, iobj
,
this
and %
respectively. Further, `%(propname)' is
substituted by who.propname
. Capitalised versions of each
of these are: `%S', `%O', `%P', `%R',
`%N',`%D', `%I', `%T' and `%(Propname)'. The
full list is given below:
Code Property Pronoun Defaults ---- -------- ------- ------- %% % %s who.ps subjective he, she, it %S who.psc subjective He, She, It %o who.po objective him, her, it %O who.poc objective Him, Her, It %p who.pp possessive his, her, its %P who.ppc possessive His, Her, Its %r who.pr reflexive himself, herself, itself %R who.prc reflexive Himself, Herself, Itself %n who.name %N who.name (capitalised) %d dobj.name %D dobj.name (capitalised) %i iobj.name %I iobj.name (capitalised) %t this.name %T this.name (capitalised) %(xyz) who.xyz %(Xyz) who.xyz (capitalised)
{Verb} str space (num num [, str str])
This verb returns a string of num occurences of str. str is optional, and defaults to space (" ").
:space(8) returns " " :space(8, "z") returns "zzzzzzzz" :space(4, "<>") returns "<><><><>"
{Verb} str right (str text, num len [, str fill])
This verb is used to right justify text in a string of length
len. fill is the optional fill character, which defaults to
space. This function calls $string_utils:space
(described above).
It is interesting to note that text need not be a string, as
tostr()
is applied to it before justification.
:right("help", 9) returns " help" :right("me", 9, ".") returns ".......me" :right(200, 9, "*") returns "******200" :right({1,22, 9) returns " {list2"
{Verb} str centre (str text, num len [, str fill])
This verb (aka $string_utils:center
) is used to centre text
in a string of length len. fill is the optional fill
character, which defaults to space. This function calls
$string_utils:space
, (described above).
:centre("help", 9) returns " help " :centre("me", 9, ".") returns "...me...." :centre(200, 9, "*") returns "***200***" :centre({1,22, 9) returns " {list2 "
{Verb} str left (str text, num len [, str fill])
This verb is used to left justify text in a string of length
len. fill is the optional fill character, which defaults to
space. This function calls $string_utils:space
, (described
above). It is interesting to note that text need not be a string, as
tostr()
is applied to it before justification.
:left("help", 9) returns "help " :left("me", 9, ".") returns "me......." :left(200, 9, "*") returns "200******" :left({1,22, 9) returns "{list2 "
{Verb} str english_list (list list [str empty str and str sep str penum])
This verb is used to return a list of things as an english sentence.
Note that tostr()
is applied, so things in the list need not
necessarily be strings.
The optional arguments allow you to control how the list is presented. empty is the string returned if the list is empty. The default is `nothing'. and is the string to use instead of ` and ' in the list. A common usage of this is replace ` and ' with ` or '. sep is the separator to use between words, the default being ` ,'. Finally, penum is the string to use after the penultimate elements, before the `and'. The default is to have a comma without a space.
:english_list({2) = "nothing" :english_list({"cat"2) = "cat" :english_list({"cat","dog"2) = "cat and dog" :english_list({"cat","dog","pig"2) = "cat, dog, and pig" :english_list({12) = "1" :english_list({{1, 2, 32, "Hi", 3002) = "{list2, Hi, and 300"
{Verb} str from_seconds (num secs)
This verb is used to return a string showing time in units of days, hours, minutes or seconds.
:from_seconds(0) returns "0 seconds" :from_seconds(2) returns "2 seconds" :from_seconds(61) returns "a minute" :from_seconds(130) returns "2 minutes" :from_seconds(7000) returns "an hour" :from_seconds(1000000) returns "11 days"
{Verb} num find_prefix (str subject, list choices)
This verb is used to find a string from a list of choices which has the prefix subject.
For example, if choices = {"hat", "hand", "face", "help"2 then...
:find_prefix("f", choices) == 3 :find_prefix("g", choices) == 0 :find_prefix("h", choices) == $ambiguous_match :find_prefix("he", choices) == 4 :find_prefix("ha", choices) == $ambiguous_match
{Verb} str trim (str text [, str what])
This verb is used to trim leading and trailing characters from the string text. what is the optional character to trim, and defaults to space.
:trim("help") returns "help" :trim(" help ") returns "help" :trim(">> help <<", ">") returns " help <<"
{Verb} str capitalise (str text)
{Verb} str capitalize (str text)
{Verb} str cap_fast (str text)
This verb is used to capitalise its argument. Note that it depends on
strcmp()
returning the difference of the first non-matching
letters!
:cap_fast("hello") returns "Hello" :cap_fast("Ezeke") returns "Ezeke"
{Verb} str strip_chars (str subject, str stripped)
This verb is used to remove the characters in the string stripped from the string subject.
:strip_chars("The quick brown fox", " ") = "Thequickbrownfox" :strip_chars("The quick brown fox", "aeiou") = "Th qck brwn fx"
{Verb} list match_player (str name, ..., [obj meobj)
{Verb} obj match_player (str name, obj meobj)
This verb is used to match one or more names to player objects in
the database. Note that name need not be complete, nor in the
same case as the player's actual name. If the name given is
`me', then the value of player
, or meobj is returned.
If meobj is not a player, then $failed_match
is returned.
In the case where a name is not matched against a player name or alias,
the value $failed_match
is returned. If a name matches more than
one player, then the value $ambiguous_match
is returned.
For example:
Verb Call Returned --------- -------- :match_player("blip") #35 :match_player("bli") #35 :match_player("blip", "Fred") {#35, $failed_match2 :match_player("blip", "Ezeke") {#35, #992 :match_player("me", #35) #35 :match_player("me", #1234) $failed_match :match_player("b") $ambiguous_match
This assumes that players named `blip' and `Ezeke' exist in the database, but `Fred' doesn't. Additionally, there is more than one player whose name starts with `b'.
{Verb} list words (str text)
This verb is used to split a piece of text into words, in the same
wat that the command line parser turns args
into argstr
.
This verb differs from using, for example, $string_utils:explode
in that it recognises a quoted piece of text as being one word. For
example:
Verb Call Returned --------- -------- :words ("There is a dog.") {"There", "is", "a", "dog."2 :words ("A \"red nose\"") {"A", "red nose"2 :words ("") {2 :words ("Hello") {"Hello"2
{Verb} str cap_property (obj what, str prop, [, num ucase]))
This verb returns what.prop, but capitalised if either
ucase is true, or the property name specified is capitalised. If
prop is blank, the verb returns the value of
what:title()
. If prop is not specified on what
or is otherwise irretrievable, then an error is returned.
If capitalisation is indicated by ucase being true, we return
what.propc
if that exists, otherwise
what.prop is capitalised in the normal fashion using
$string_utils:capitalise
. A special case exists if we are trying
to retrieve the name of a player. This is never capitalised.
{Verb} num index_delimited (str string, str target [, num casem])
This verb works in the same way as the primitive index()
, except
that it only matches on occurrences of target in string that
are delimited by word boundaries. That is, it will not match on
occurrences that are preceded or followed by an alphanumeric.
For example,
Verb Call Returned --------- -------- :index_delimited ("Hi there", "he") 0 :index_delimited ("Hi there", "hi") 1 :index_delimited ("Hi there", "hi", 1) 0 :index_delimited ("Hi there", "Hi", 1) 1
{Verb} num to_value (str expr)
This verb is used to convert a string into a value. It is the opposite
operation to $string_utils:from_value
. As with that verb, this
is best explained by examples:
$string_utils:to_value(s) gives: s result "5" 5 "5 + 3" "5 + 3" {2 error--> {1,2,32 error--> "{1,2,32" {1,2,32
{Verb} list columnize columnise (list items, num n [, num width])
This verb is used to turn a one-column list of items into an n column list. width is the last character position that may be occupied; it defaults to a standard screen width of 79 characters.
For example, to tell a player a list of number in three columns, use the following code:
player:tell_lines($string:utils:columnise ({1, 2, 3, 4, 5, 6, 72, 3));
{Verb} list parse_command (str command, who)
This verb is used to parse a command line, in the same way that the built in command line parser does the job. It returns an horrendous list of stuff, that I'm not quite sure about yet.
{Verb} list match_str*ing (str input, str match, ...)
This verb performs wildcard matching of `match' to input,
using the `*' character as a wildcard. It returns a list of what
the *
s actually matched. Note that this verb will not catch
every match, if there are several different ways to parse the input.
More than one wildcard string may be given. If a numeric argument is
given, it is taken to indicate whether case sensitivity should be used.
For example:
;$string_utils:match_string(\"Jack waves to Jill\",\"* waves to *\") -|{\"Jack\", \"Jill\"2
{Verb} str uppercase lowercase (str string)
This verb returns either the uppercase or lowercase version of string, as appropriate.
No properties are defined on the $string_utils
class.