who documentation

TITLE

uwho; ufinger; urooms; unick; da.who.muf - universal "who" program

SYNOPSIS

Command line:

uwho - list online users
uwho player - list player's connections
uwho -format - change display format
uwho -sort - change sort order
uwho -cull - change list culling options
uwho -header - change list header
uwho -footer - change list footer

Properties:

_uwho/action/header: (set on player or trigger) List header lines as typed into action -header. Default is "fields line".
_uwho/action/footer: (set on player or trigger) List footer lines as typed into action -header. Default is "line count".
_uwho/action/format: (set on player or trigger) Format as typed into action -format. Default is "hflag name login idle space nojump room:-1".
_uwho/action/indent: (set on player or trigger) Indentation for wrapped lines. Default is "30". Changed automatically when action -format is run.
_uwho/action/sort: (set on player or trigger) Format as typed into action -sort. Default is "room idle".
_uwho/action/cull: (set on player or trigger) Culling options as typed into action -cull. Default is the empty string.
sex: (set on player) Player's sex.
_species: (set on player) Player's species.
_volunteer: (set on player) Player's volunteer speciality.
_private: (set on player or room) Set to "yes" if a player cannot be located. (shown as "<Location Private>" in room format field).
_doing: (set on player) Player's "doing" string (shown with doing format field).
_nojump: (set on room) Set to "yes" if a room cannot be jumped to (shown with nojump format field).
_pinfo.OOC.Name: (set on player) Player's "pinfo" out-of-character name (shown with rlname format field).
_pinfo.OOC.Email: (set on player) Player's "pinfo" out-of-character email address (shown with email format field).
_TermWidth: (set on player) Player's screen width in characters; determines length of rows of hyphens in the "line" header and footer.

DESCRIPTION

da.who.muf (#5196) is a customisable connection-listing program. More than one global action is linked linked to the program; each has different default format but is otherwise the same. This document will refer to them all as uwho; substitute whichever action name you like for this.

da.who.muf displays information about each connection currently found on the Muck. It first removes certain connections if asked to do so, sorts the remaining connections based on some criterion, then displays certain information (in a customisable way) to the screen.

You can alter the sorting behaviour with the command uwho -sort. You can alter the display format with the command uwho -format. You can alter the list culling options with uwho -cull. To change the header or footer to the list, type uwho -header or uwho -footer. On global actions (those in room #0), the settings are stored on your player, otherwise they are stored on the action itself. This allows you to use a global action's defaults, yet alter them for your own personal taste.

List culling

If you wish, you can make uwho suppress displaying of certain connections. You might want to do this if you want to list a player who is connected several times by only showing its least idle connection, for instance.

There are few culling options available presently. The syntax has been designed so that they are extensible in a future version of da.who.muf. These are the currently recognised culling options:

room=here: Only include players in the room with you (cull those in other rooms).
name!=nickname: Only include players who have set a nickname used in the "%n" pronoun substitution.
!private: Only include players who are not set private (cull those set private or in private rooms).
!hflag: Only include players who are not set HAVEN.
!nojump: Only include players who can be jumped to.
cflag: Only include players who are designated Hosts (have their CHOWN_OK flag set).
vflag: Only include players who have declared themselves Volunteers (have a non-blank _Volunteer property).
leastidle: Only include a player's least idle connection if they are connected more than once. This option is useful in conjunction with the concount display field.
eachroom: Only include one player (at random) from each room, and cull all private players. This option implies !private. This option is useful in conjunction with a display format such as "room roomowner roomcount with".

To combine the effects of more than one of the above options, separate the words with spaces. Culling is done from first to last in the list you give; this usually makes no difference, but it can if you use "eachroom" after another word. Words other than those above are ignored.

Sorting

Connections are sorted according to one or more fields before they are displayed. This allows you to group together all players in the same room, or to have players who connected most recently near the top of the list. You can sort on more than one field, so that connections which compare equal on one field (say, room) can have the tie broken by comparing on another field (say, idle time). Separate each field with a space when you type it in. If you want to reverse the sense of the sort, precede the word with a single hyphen (-).

These are the valid fields for sorting:

name: Player name, in ascending case-insensitive order.
nickname: Player's nickname as set for "%n" pronoun substitution, in ascending case-insensitive order.
room: The room a player is in, in ascending case-insensitive order. All private players (as indicated by the _private property) appear at the end.
hflag: Place all HAVEN players after all non-HAVEN players.
cflag: Place all Hosts at the top of the list.
vflag: Place all Volunteers at the top of the list.
volunteer: A player's Volunteer speciality, in ascending case-insensitive order.
nojump: Place all players who cannot be jumped to after all other players.
idle: Connection idle time, in ascending order (least idle near top).
login: Connection time, in ascending chronological order (oldest connections near top).
onfor: Time a connection has been in use, in ascending chronological order (most recent connections near top). Clearly this is the opposite of login.
doing: Player's "doing" string, in ascending case-insensitive order.
status: Player's access level, in order PLAYER, BUILDER, MUCKER, WIZARD.
concount: Number of times a player is connected, in ascending numerical order.
roomcount: Number of visible (non-private) players in the same room with a player, in ascending numerical order.
roomowner: Owner of the room a player is in, in ascending case-insensitive order. For private players this information cannot be determined, and such players are listed after all others, as with room.
sex: The value of a player's sex property, in ascending case-insensitive order.
species: The value of a player's _species property, in ascending case-insensitive order.
rlname: Player's out-of-character real name, as given in their pinfo -ooc information.
email: Player's out-of-character email address, as given in their pinfo -ooc information.

Any other words are ignored for sorting.

Header and footer

You can customise which information is printed before and after the list. Each of the words below causes a line to be printed in the header or footer. While some of the lines are more suited to headers than footers, or vice versa, they are all available for both. To print more than one line, type each word in the order you'd like them to appear in, separated by spaces.

The allowed words are:

fields: The headers for each field in the list.
line: A horizontal line of hyphens to the width of your terminal.
count: A summary of the number of connections on the Muck.

All other words are ignored.

Display format

You can specify which of the following fields are to be displayed for each connection. You do this by giving uwho -format one or more of the following words, separated by spaces. All other words in your format are copied as-is into every line. You may want to place line-drawing characters in your format to give a table appearance to your list, for instance. White space is ignored. If you want to put a space in your format, use the space word.

Each of these fields has a default width. If the width is positive, then the string will be padded with spaces to the right to make it that width, or truncated to that width if it is longer. If the width is negative, then the string will be padded with spaces to the left, to right-align the field (note that you should probably put a space field between adjacent negative- and positive-width fields so that they don't run together). If the width is -1, then the field is not justified at all. This is really only useful for the last field in a format line.

You can alter the default width of a field by appending a colon (:) and the width you'd like it to be, such as "name:12". You can use positive, negative or the special -1 width. If you use a width of zero the default will be used instead.

These are the words used to give information fields in the display format:

space (width 1): A space. You can join lots of spaces by specifying a new width.
name (width 16): Player name.
nickname (width 30): Player nickname, used in pronoun substitution at "%n".
room (width 40): The room a player is in, or "<Location Private>" if the player is set private. Rooms set ABODE or LINK_OK or owned by you have their dbref and flags shown. For Wizards not set QUELL running this program, all rooms dbrefs are shown and privacy is ignored.
roomneat (width 40): The room a player is in, or "<Location Private>" if the player is set private. No rooms have their dbref and flags shown.
login (width 6): The local time that a connection was started; the time a player logged in to the Muck. This uses your short time format as you set with date -format.
idle (width -5): Idle time, in seconds, minutes or hours, or blank if zero.
onfor (width 6): Time that a connection has been in progress, in hours and minutes. Historically this field has been left-justified but probably should be right-justified.
nojump (width 1): Equal to the string "+" if the room a player is in has the _nojump property set to "yes", or the player has its JUMP_OK flag cleared and the room the player is in has the JUMP_OK flag cleared. Otherwise blank. (This field was previously called iflag for historical reasons; that name still works but is discouraged.)
hflag (width 1): Equal to the string "*" if a player is set HAVEN. Otherwise blank.
cflag (width 1): Equal to the string "@" if a player is a Host (has the CHOWN_OK flag set). Otherwise blank.
vflag (width 1): Equal to the string "^" if a player is a Volunteer (has a non-blank _Volunteer property). Otherwise blank.
volunteer (width 40): A player's _Volunteer property string, describing the volunteer's specialities.
status (width 8): The string "Player", "Builder", "Mucker" or "Wizard", showing the most powerful player-access bit the player has.
doing (width 40): The player's "doing" string, as set by @doing.
sex (width 7): The player's sex property.
species (width 7): The player's _species property.
concount (width 1): The number of active connections a player has on the Muck. If equal to 1, the field is blanked for legibility. This field is recommended for use with the leastidle culling option.
roomcount (width -2): The number of players in the room that a player is in. If the player is private, the field is blanked. Private and sleeping players in the same room are not counted. This field is recommended for use with the eachroom culling option.
roomowner (width 16): The owner of a room the player is in. Private players have this field blanked. This field is recommended for use with the eachroom culling option.
with (width 40): A space-separated list of non-private awake characters in the same room as a player, in order from longest in the room to most recently arrived. The list does not undergo any culling. This field is recommended for use with the eachroom culling option.
rlname (width 40): The player's out-of-character real name, as set by pinfo -ooc.
email (width 40): The player's out-of-character email address, as set by pinfo -ooc.

BUGS

Sorting on multiple fields can be slow, especially if many of them must be compared all the time before finding a difference between connections (as would happen with hflag, nojump or status where most players will have the same value). Don't go overboard on sorting.

AUTHOR

Deborah Pickett (<Ariel> on FDCMuck).