Detecting and Handling Failures in Matching
-------------------------------------------

:object_match_failed(match_result, name)
	Test whether or not a :match_object() call failed and print messages if so.
:player_match_failed(match_result, name)
	Test whether or not a :match_player() call failed and print messages if so.
:player_match_result(match_results, names)
	...similar to :player_match_failed, but does a whole list at once.

:read()              -- Read one line of input from the player and return it.
:yes_or_no([prompt]) -- Prompt for and read a `yes' or `no' answer.
:read_lines()        -- Read zero or more lines of input from the player.
:dump_lines(lines)   -- Return list of lines quoted so that feeding them to 
:read_lines()        -- will reproduce the original lines.

:running_out_of_time()    -- Return true if we're low on ticks or seconds.
:suspend_if_needed(time)  -- Suspend (and return true) if we're running out of time.

:suspend(args) -- Handle PREFIX and SUFFIX for clients in long commands.

An optional 3rd arg gives an identifying string to prefix to each of the nasty messages.

Returns E_PERM if the current task is not a command task that has never called suspend().
========== Alterado para aceitar clientes java ==============

Returns a list of strings, the (up to MAX, if given) lines typed by the player. Returns E_PERM if the current task is not a command task that has never called suspend().
In order that one may enter arbitrary lines, including "@abort" or ".", if the first character in an input line is `.' and there is some nonwhitespace afterwords, the `.' is dropped and the rest of the line is taken verbatim, so that, e.g., ".@abort" enters as "@abort" and ".." enters as ".".

Similar to :read_lines() except that help is available and one may specify other escape sequences to terminate the read. escapes should be either a string or list of strings; this specifies which inputs other from `.' or `@abort' should terminate the read (... don't use anything beginning with a `.'). help should be a string or list of strings to be printed in response to the player typing `?'; the first line of the help text should be a general comment about what the input text should be used for.

Successive lines should describe the effects of the alternative escapes.
Returns {end,list-of-strings-input} where end is the particular line that terminated this input or 0 if input terminated normally with `.'. Returns E_PERM if the current task is not a command task that has never called suspend().
@abort and lines beginning with `.' are treated exactly as with :read_lines()

Proper usage:
The first time you want to suspend, use output_delimiters = $command_utils:suspend(time, x); where x is some non-zero number. Following, use $command_utils:suspend(time, output_delimiters);
To wrap things up, use $command_utils:suspend(time, output_delimiters[2]);

You'll probably want time == 0 most of the time.
Note: Using this from verbs called by other verbs could get pretty weird.

Properties:
  .genders  -- list of standard genders
  .pronouns -- list of pronoun properties
  .ps .po .pp .pq .pr .psc .poc .ppc .pqc .prc 
            -- lists of pronouns for each of the standard genders

  If foo is of gender this.gender[n], then the default pronoun foo.p is
this.p[n] (where p is one of ps/po/pp/pq...)

Verbs:
  :set(object,newgender)             -- changes pronoun properties to match new gender.
  :add(object[,perms[,owner]])       -- adds pronoun properties to object.

  :get_pronoun     (which,object)    -- return pronoun for a given object
  :get_conj*ugation(verbspec,object) -- return appropriately conjugated verb

This is a package for maintaining huge persistent (sorted) lists in a format that is less likely to spam the server (which runs into a certain amount of trouble dealing with long ordinary lists --- btw we use `biglist' to refer to the huge data structure we're about to describe and `list' to refer to ordinary MOO lists {...}). The biglist in question lives on a particular object, to which we will refer in the discussion below as the `home' object, and its various elements appear as leaves of a tree whose nodes are kept in properties of the home object. It should be noted that the home object does not need to be (and in fact should *not* be) a descendant of this one; this object merely provides utilities for manipulating the properties on the home object that are used in a particular biglist manipulation.

All of the utilities below refer to `caller' to locate the home object. Thus verbs to manipulate a given biglist must be located on or inherited by its home object itself. The home object needs to define the following verbs

  :_make(@args)     => new property on home object with value args
  :_kill(prop)      delete a given property that was created by :_make
  :_get(prop)       => home.prop
  :_put(prop,@args) set home.prop = args
  :_ord(element)    given something that is of the form of a biglist element
                    return the corresponding ordinal (for sorting purposes).

See #5546 (Generic Biglist Resident) or $big_mail_recipient for examples.

Those of the following routines that take a biglist argument are expecting either {} (empty biglist) or some biglist returned by one of the other routines

  :length(biglist)          => length(biglist) (i.e., number of elements)
  :find_nth(biglist,n)      => biglist[n]
  :find_ord(biglist,k,comp) => n where n is the largest such that
                    home:(comp)(k,home:_ord(biglist[n])) is false, or the smallest such that
                    home:(comp)(k,home:_ord(biglist[n+1])) is true.

  :start(biglist,s,e)  => {biglist[s..?],@handle} or {}
  :next(@handle)       => {biglist[?+1..??],@newhandle} or {}

        for elt in (biglist[first..last])
          ...
        endfor
     is
        handle = :start(biglist,first,last);
        while(handle)
          for elt in (handle[1])
            ...
          endfor
          handle = :next(@listdelete(handle,1));
        endwhile

  :set_nth(L,n,value)      =>  L[n] = value
     replaces the indicated element
	 
  :insert_before(L,M,n)    => {@L[1..n-1],@M,@L[n..length(L)]}
  :insert_after (L,M,n)    => {@L[1..n],  @M,@L[n+1..length(L)]}

  :extract_range(L,m,n) => {{@L[1..m-1],@L[n+1..]}, L[m..n]} 
     breaks the given biglist into two distinct biglists.

  :delete_range(L,m,n[,leafkiller]) => {@L[1..m-1],@L[n+1..]}
  :keep_range  (L,m,n[,leafkiller]) => L[m..n]
     like extract_range only we destroy what we don't want.

  :insertlast(L,value)  => {@L,value}
     inserts a new element at the end of biglist.

  :kill(L[,leafkiller]) 
     destroys all nodes used by biglist.  
     Calls home:leafkiller on each element.

append            (list,list,..) => result of concatenating the given lists
reverse           (list)         => reversed list
remove_duplicates (list)         => list with all duplicates removed
compress          (list)         => list with consecutive duplicates removed
setremove_all     (list,elt)     => list with all occurrences of elt removed
find_insert       (sortedlist,e) => index of first element > e in sorted list
sort              (list[,keys])  => sorted list
count             (elt,list)     => count of elt found in list.
flatten           (list)         => flatten all recursive lists into one list

make              (n[,e])        => list of n copies of e
range             (m,n)          => {m,m+1,...,n}

arrayset   (list,val,i[,j,k...]) => array modified so that list[i][j][k]==val

-- Mapping functions (take a list and do something to each element):

map_prop ({o...},prop)              => list of o.(prop)            for all o
map_verb ({o...},verb[,args)        => list of o:(verb)(@args)     for all o
map_arg  ([n,]obj,verb,{a...},args) => list of obj:(verb)(a,@args) for all a

An association list (alist) is a list of pairs (2-element lists), though the following functions have been generalized for lists of n-tuples (n-element lists). In each case i defaults to 1.

assoc        (targ,alist[,i]) => 1st tuple in alist whose i-th element is targ
iassoc       (targ,alist[,i]) => index of same.
assoc_prefix (targ,alist[,i]) => ... whose i-th element has targ as a prefix
iassoc_prefix(targ,alist[,i]) => index of same.
slice             (alist[,i]) => list of i-th elements
sort_alist        (alist[,i]) => alist sorted on i-th elements.