NAME

ICE - ifMUD Client Engine

SYNOPSIS

  use ICE;

  my $ifmud = ICE->new(Host    => 'ifmud.port4000.com',
                       Port    => 4000,
                       Timeout => 60);

  $ifmud->login('username', 'password');
  $ifmud->lounge('tiptoes into the lounge.');
  $ifmud->public_say('Hey there!', 'katre');
  $ifmud->mail_send('inky', 'Hi', 'How are you?');
  $ifmud->quit;

DESCRIPTION

ICE is a class implementing an exhaustive interface to the ifMUD in Perl. It provides wrappers for a large subset of the MUD's commands as well as an extensive parser for lines output from the MUD.

OVERVIEW

The ifMUD is a Perlmud-based multi-user dimension which was created for the discussion of interactive fiction. It has close ties to the USENET newsgroups rec.games.int-fiction and rec.arts.int-fiction. The MUD itself runs at ifmud.port4000.com port 4000 and is open to the public.

All transfers to and from the ifMUD are plaintext, as it is intended to be able to be used via a low-bandwidth telnet connection, if needed. However, MUD clients make using the ifMUD simpler and more elegant. The primary goal in creating ICE was to simplify the creation of an ifMUD- specific client in the future.

CONSTRUCTOR

new ( ARGS )

This is the constructor for a new ICE object. No arguments are required, but there are three possible arguments which can be supplied in hash-like key/value pairs. They are:

Host - The name or IP address of the remote machine to which the ICE object will attempt to connect. The default value is 'ifmud.port4000.com'.

Port - The port on the remote host to which the ICE object will attempt to connect. The default value is 4000.

Timeout - The number in seconds of the connection timeout value. The default value is 30.

Filename - The name of a file containing the names of all the users of the MUD, one name per line (for use by the is_user() function). Defaults to $HOME/.ifmudnames.

If the constructor fails to connect to the remote host as specified within the timeout period, undef will be returned.

METHODS

GENERAL-PURPOSE METHODS

send_raw ( STRING )

Sends STRING followed by a newline character to the MUD.

get_line ( )

Gets a single line of text from the MUD, processes it via the parse_line() function, and returns the resulting hash, or undef if the function fails. If a handler function is set for the type of the resulting hash, get_line() will first call that function using the parsed hash as the only argument and then return the parsed hash.

set_handler ( STRING, FUNCTION )

Sets the handler for a certain type of MUD output. If a handler function is created and set for the 'LOGIN_PROMPT' type, when the get_line() function encounters a line that matches the 'LOGIN_PROMPT' type, it will automatically call the specified handler function in the calling script.

respond ( HASH, USERNAME, RESPONSE )

HASH is a previously-parsed line from the MUD to which the script wants to respond in kind: a public statement for a public statement, a page for a page, a whisper for a whisper, etc. USERNAME is the username the script is using, and RESPONSE is the message to be sent back. respond() works for all statements and queries, whether directed, undirected, channeled, or public, and also whispers and pages.

login ( USERNAME, PASSWORD [, QUIET ] )

Logs into the MUD with the given username and password. If a 1 is sent as the third parameter to the function, it will qconnect to the MUD which supresses the user's connect and disconnect messages.

quit ( )

Logs off the MUD, closes the connection, and undefines the instance.

finger ( USERNAME )

Fingers the given username on the MUD.

who ( [ FLAGS ] )

Sends a 'who' command followed by the given flags, as follows.

The following four flags can be preceded by either a plus (+) or minus (-) sign, indicating whether the resulting information should be sorted in ascending or descending order.

  byon - sorts players by time on the MUD.
  byidle - sorts players by their idle time.
  byname - sorts players by their name.
  bydoing - sorts players by their @doing message.

#channel - show only users online in a specific channel.

username [ username ... ] - show information on given users

If no flags are supplied, the who command will list all players currently online.

from ( [ USERNAME ] )

Displays the IP address and port for the given username, or if a username is not given, for all connected users.

set_poll ( STRING )

Sets the poll to the value given. The string has to be 52 characters or less to be successfully set.

get_poll ( )

Requests the current poll and pollster.

is_user ( USERNAME )

Checks a local file to see if the given username is actually an ifMUD user. Before this function can be used, the file must exist on the system and its full path and name must be stored in the object's filename key.

is_online ( USERNAME )

Checks the object's userlist key to see if the given username is on the MUD at that time. The userlist must be built by the calling program.

userlist_add ( USERNAME )

Adds a username to the object's userlist key.

userlist_delete ( USERNAME )

Removes a username from the object's userlist key.

channellist_add ( CHANNEL )

Adds a channel to the object's channels key.

channellist_delete ( CHANNEL )

Removes a channel from the object's channels key.

go ( EXIT )

Used for navigation around the MUD.

lounge ( [ MESSAGE ] )

Sends the user to the lounge, with an optional olounge message.

home ( )

Sends the user home.

where ( [ USERNAME ] )

Finds out where the rest of the online users are on the MUD.

gag ( USERNAME )

Gags a user.

ungag ( USERNAME )

Ungags a gagged user.

ignore ( USERNAME )

Ignores a user for the rest of the session.

unignore ( USERNAME )

Stops ignoring a user.

help ( [ TOPIC ] )

Asks the MUD for help on a certain topic.

doing ( STRING )

Sets the user's doing field to the supplied string. The string must be under 52 characters in length or the MUD will return an error message.

time ( )

Gets the current MUD time.

statistics ( [ USERNAME ] )

Gets statistics on either the given username, or, if no username is given, the MUD as a whole.

password ( PASSWORD [, USERNAME ] )

Sets the password for the given username (if the calling player is a wizard) or, when used without a username argument, sets the password of the current player.

setoption ( OPTION )

Sets an option on the player.

Options can be one of:

  autopoll     Display poll whenever it changes
  chanchange   Notify when default channel changes
  checkmail    Check/read MUDmail when checking bb.
  gagprivate   Make @gag also gag whispers/pages
  joinnolast   @joinch doesn't change lastchannel
  muteconn     No connect messages.
  mutedisc     No disconnect messages.
  muteunzone   No zoned flag clearing notification.
  mutezone     No zoned flag setting notification.
  nohomemsg    Don't see others' ohomemsg.
  nounzone     No zoned flag clearing upon activity
  nozone       No zoned flag setting after idle.
  pastenotrim  @paste does not trim initial whitespace
  quickpost    Allow old bb posting syntax
  smartresolve Resolve channel ambiguities

clearoption ( OPTION )

Unsets an option on the player. See above for valid options.

OUTPUT PARSING METHODS

parse_line ( STRING )

Parses any given line of output from the MUD into a hash value. See THE PARSE_LINE FUNCTION later in this document for a more in-depth explanation of this function.

parse_time ( STRING )

Parses a MUD-style time string into components. Returns a hash with the following keys:

  Raw      The raw time string.
  Seconds  The number of seconds in the time string.
  Minutes  The number of minutes in the time string.
  Hours    The number of hours in the time string.
  Days     The number of days in the time string.

OBJECT METHODS

setfield ( OBJECT, FIELD, VALUE ): Sets a field on the given object to the given value.
getfield ( OBJECT, FIELD ): Requests the contents of a field on the given object.
clearfield ( OBJECT, FIELD ): Clears the value of a field on the given object.
setflag ( OBJECT, FLAG ): Sets a flag on the given object.
unsetflag ( OBJECT, FLAG ): Unsets a flag on the given object.
look ( [ OBJECT ] ): Causes the player to look. If an object is given, the player looks at that object. If an object is not given, the player looks at the room he or she is in.
examine ( OBJECT ): Causes the player to examine an object. If the player owns the object, full field and flag information on the object will be printed. If the player does not own the object, information on the owner will be printed.
take ( OBJECT ): Causes the player to pick up the object.
drop ( OBJECT ): Causes the player to drop the object.
inventory ( ): Tells the MUD to list the player's inventory.
give ( OBJECT, USERNAME ): Gives the object to the username.
sign ( OBJECT, MESSAGE ): Signs the message to the object.
unsign ( OBJECT ): Removes a signing from a previously signed object.
tail ( OBJECT ): Lists the last several hundred characters of an object's description.
dig ( OBJECT ): Digs a new room, named OBJECT.
create ( OBJECT ): Creates a new item, named OBJECT.
describe ( OBJECT [, DESCRIPTION ] ): Sets an object's description field. If called with no DESCRIPTION parameter, clears the object's description field.
name ( OBJECT, NAME ): Changes an item's name.
change_owner ( OBJECT, PLAYER ): Changes an item's owner to the given player. A player can chown anything set chownok to him or herself, but only wizards can chown an object to another player.
teleport ( DESTINATION [, OBJECT ] ): Teleports an object to the given destination. If no object is given, the player itself is teleported.
link ( OBJECT, HOME ): Sets an object's home.
exit_open ( EXIT, DESTINATION ): Opens a new exit pointing to the given destination.
action ( ACTION, OBJECT, DESTINATION ): Creates a new action on the given object with the given destination.
setfail ( OBJECT, MESSAGE ): Sets an object's fail field to the given message.
clearfail ( OBJECT ): Clears an object's fail field.
setofail ( OBJECT, MESSAGE ): Sets an object's ofail field to the given message.
clearofail ( OBJECT ): Clears an object's ofail field.
setdrop ( OBJECT, MESSAGE ): Sets an object's drop field to the given message.
cleardrop ( OBJECT ): Clears an object's drop field.
setodrop ( OBJECT, MESSAGE ): Sets an object's odrop field to the given message.
clearodrop ( OBJECT ): Clears an object's odrop field.
setsuccess ( OBJECT, MESSAGE ): Sets an object's success field to the given message.
clearsuccess ( OBJECT ): Clears an object's success field.
setosuccess ( OBJECT, MESSAGE ): Sets an object's osuccess field to the given message.
clearosuccess ( OBJECT ): Clears an object's osuccess field.
setlock ( OBJECT, LOCK ): Sets an object's lock field to the given lock.
clearlock ( OBJECT ): Clears an object's lock field.
backlinks ( [ OBJECT ] ): Shows an object's backlinks. If no object is given, shows the backlinks for the current room.
clean ( ): Cleans the room the player is in by sending all the items to their homes.
find ( [ OBJECT ] ): Attempts to locate the given object. If no object is given, finds all objects owned by the player.
recycle ( OBJECT ): Recycles the given object.
unrecycle ( OBJECT ): Retrieves the given object from the recycle bin.

WIZARD METHODS

boot ( USERNAME ): Boots the given user from the MUD.
toad ( USERNAME ): Turns the given user into a toad.
dump ( ): Tells the MUD to dump its database to disk.
player_create ( USERNAME, PASSWORD ): Creates a player with the given username and password.

COMMUNICATION METHODS

public_say ( MESSAGE [, RECIPIENT ] ): Says a message. If a recipient is given, directs the message to that recipient.
public_emote ( ACTION [, RECIPIENT ] ): Emotes an action. If a recipient is given, directs the emotion to that recipient.
public_spoof ( MESSAGE ): Spoofs a message.
public_paste ( STRING [, PREFIX ] ): Pastes a string. If a prefix is given, adds it to the beginning of each line of the string. If no prefix is given, the default ``:|'' is used.
holler_say ( MESSAGE {, RECIPIENT ] ): Hollers a message. If a recipient is given, directs the message to that recipient.
holler_emote ( ACTION [, RECIPIENT ] ): Hollers an emote. If a recipient is given, directs the emotion to that recipient.
rimshot ( ): Does a rimshot: ba-dum-bum-tish!
amusing ( ): Displays a list of amusing things to try.
private_say ( RECIPIENT, MESSAGE ): Whispers a message to a recipient.
private_emote ( RECIPIENT, ACTION ): Privately emotes an action to a recipient.
private_paste ( RECIPIENT, STRING [, PREFIX ] ): Privately pastes a string to a recipient. If a prefix is given, adds it to the beginning of each line of the string. If no prefix is given, the default ``:|'' is used.
page ( RECIPIENT [, MESSAGE ] ): Pages a recipient. If a message is given, the message is paged. If not, the player's location is paged.
channel_say ( CHANNEL, MESSAGE [, RECIPIENT ] ): Says a message on a channel. If a recipient is given, directs the message to the recipient.
channel_emote ( CHANNEL, ACTION [. RECIPIENT ] ): Emotes an action on a channel. If a recipient is given, directs the emotion to the recipient.
channel_spoof ( CHANNEL, MESSAGE ): Spoofs a message to a channel.
channel_paste ( CHANNEL, STRING [, PREFIX ] ): Pastes a string to a channel. If a prefix is given, adds it to the beginning of each line of the string. If no prefix is given, the default ``:|'' is used.

CHANNEL METHODS

channel_join ( CHANNEL )

Joins the given channel.

channel_part ( CHANNEL )

Leaves the given channel.

channel_settopic ( CHANNEL [, TOPIC ] )

Sets the topic on a channel to the given topic. If no topic is given, clears the channel's topic.

channel_setflag ( CHANNEL, FLAG )

Sets a flag on a channel.

channel_unsetflag ( CHANNEL, FLAG )

Unsets a flag on a channel.

channel_addpope ( CHANNEL, USERNAME )

Gives pope status to a user on a channel.

channel_delpope ( CHANNEL, USERNAME )

Removes pope status from a user on a channel.

channel_addcardinal ( CHANNEL, USERNAME )

Gives cardinal status to a user on a channel.

channel_delcardinal ( CHANNEL, USERNAME )

Removes cardinal status from a user on a channel.

channel_invite ( CHANNEL, USERNAME )

Adds a user to a channel.

channel_kick ( CHANNEL, USERNAME )

Removes a user from a channel.

channel_create ( CHANNEL )

Creates a new channel.

channel_delete ( CHANNEL )

Deletes an existing channel.

channel_list ( FLAGS )

Lists channels on the MUD based on the provided flags.

Flags are as follows:

  -name (don't trim long channel names)
  -topic (display name + topic (this is the default))
  -last (display name + last message time)
  -created (display name + create time)
  -byname  (sort by name)
  -bycreated (display channels from earliest-created
              to most-recently created, instead of
              alphabetically.)
  -bylast (display channels from least-used to most-
           recently-used, instead of alphabetically)
  -all (display all channels)
  -member (display channels of which you're a member)
  -nomember (display channels of which you're not a
             member)
  -tail <n> (display only last <n> lines of output)
  -categories (display all categories, or all
               categories in argument)
  -recent [<n>] (display the last 10 (or <n>) talked-
                 on channels; this is precisely an
                 abbreviation for -all -bylast
                 -tail <n>)

channel_mutetoggle ( CHANNEL )

Toggles the mute status of a channel.

channel_rename ( CHANNEL, NAME )

Renames a channel.

channel_category_add ( CATEGORY )

Creates a new category for channels.

channel_category_delete ( CATEGORY )

Deletes an existing channel category.

channel_statistics ( CHANNEL )

Retrieves channel statistics.

BULLETIN BOARD METHODS

bb_list ( [ CHANNEL [, RANGE ] ] )

Lists the messages on a bulletin board. If a channel is provided, reads from that channel's bulletin board. If a range is supplied, lists only the messages within that range.

bb_post ( ARGS )

Posts a message to a bulletin board. Args are formatted as hash-style key/value pairs.

Subject - (REQUIRED)

  The subject of the post.

Message

  The body of the post.

Channel

  The channel bulletin board to which the post is posted.

bb_modify ( ARGS )

Modifies a message already on a bulletin board. Args are formatted as hash-style key/value pairs.

MessageID - (REQUIRED)

  The ID of the message being modified.


B<Body> - (REQUIRED)

  The new body of the message.

Channel

  The channel bulletin board to which this message has been posted.


B<Subject>

  The new subject of the message.

bb_read ( ARGS )

Reads a message or series of messages from a bulletin board. Args are formatted as hash-style key/value pairs.

StartID - (REQUIRED)

  The first message to read.

EndID

  The last message to read.

Channel

  The channel bulletin board from which to read messages.

bb_delete ( ARGS )

Deletes a message or series of messages from a bulletin board. Args are formatted as hash-style key/value pairs.

StartID - (REQUIRED)

  The first message to delete.

EndID

  The last message to delete.

Channel

  The channel bulletin board from which to delete messages.

bb_undelete ( ARGS )

Undeletes a message or series of messages from a bulletin board. Args are formatted as hash-style key/value pairs.

StartID - (REQUIRED)

  The first message to undelete.

EndID

  The last message to undelete.

Channel

  The channel bulletin board from which to undelete messages.

bb_check ( [ CHANNEL ] )

Tells you if there are new messages on any bulletin board to which you are subscribed. If a channel is provided, lists new messages for that channel only.

bb_clear( )

Erases the new flag on all messages on any bulletin boards to which you are subscribed.

MUDMAIL METHODS

mail_send ( RECIPIENT, SUBJECT [, MESSAGE ] ): Sends a MUDmail to a recipient with the given subject and, if a message is provided, the given message.
mail_view ( ): Lists all MUDmails in the player's inbox.
mail_read ( RANGE ): Reads a message or series of messages from the player's inbox.
mail_delete ( RANGE ): Deletes a message or series of messages from the player's inbox.

THE PARSE_LINE FUNCTION

The parse_line function is by far the biggest part of the ICE module. When given a line of text output by the MUD, parse_line compares it to over 150 regular expressions to determine the type of line it appears to be. When it decides, it returns a hash structure containing the important information from the line.

Every hash returned is guaranteed to contain at least two key/value pairs:

  The 'Type' key, which contains a string of uppercase characters and possibly
  underscores. This string is a unique identifier which can be used to determine
  the remainder of the existing keys in the hash.


  The 'Raw' key, which contains the text of the line as it was output by the MUD.

Once the Type is determined, the calling script will know what other keys will exist in the hash. Possible values contained may include a username, a recipient, a channel, or one of many other types of data. The user can read the ICE.pm source to determine these values.

Channeled lines will have a Type value that begins with ``CHANNEL,'' followed by a secondary parsed Type value. Spoofed lines will have a Type value that begins with ``SPOOF,'' followed by a secondary parsed Type value. Any statement that contains a spoof is not guaranteed to have a logical Type past the ``SPOOF'' type. For instance, a line like the following:

(From Joe) [linux] (From Sam) (From Bob) Pam says, ``Hi!''

would have the following Type value:

SPOOF,CHANNEL,SPOOF,SPOOF,STATEMENT

OTHER USES AND IDEAS

MUD Bots: Bots of all types can make use of this library to simplify command-sending and input parsing on the MUD.
Statistics: The parse_line function could be used to analyse MUD output and determine usage statistics (who talks most, what channels are most active, when most people are on the MUD, etc.).

KNOWN BUGS AND LIMITATIONS

It's easy to fool the parse_line function by using the @tellroom function or by making objects print messages that look like other things. A script that uses ICE must take this into account and attempt to determine whether the parse_line function has reported the correct type or not based on preceding or following lines of text or sent commands.

The is_user function depends on the creation of a file that contains a list of MUD users by an outside source. Unfortunately, there's no better way to implement this function as far as I can tell.

REPORTING BUGS

When reporting bugs/problems please be as specific and include as much information about your script and setup as possible. Including a small sample script that reproduces the errant behaviour will help expediate a timely and accurate solution to the problem.

MORE INFORMATION

ifMUD: http://ifmud.port4000.com

Interactive fiction: http://interactfiction.about.com

ICE: http://www.corknut.org/code/ICE/

AUTHOR

Ryan N. Freebern <rfreebern@corknut.org>

CREDITS

Sarah M. Freebern <sarah@corknut.org> - for being my wife.

Everyone on ifMUD #perl and #mud-bots - for answering all my questions.