& TCL
& @tcl
PennMUSH TCL Enhancements
  PennMUSH TCL patch by Thorvald Natvig (slicer@bimbo.hive.no)
  PennMUSH TCL web page is at: http://slicer.hive.no/tcl/
  Helpfiles edited by Jonathan Booth (kamikaze@imsa.edu)
  Last update: March 31, 1999

  TCL commands that interface to the MUSH. TinyMUSH compatable
  commands have a '*' appended:

  addcmd	addfunc		addhook		ansi		attrib
  connection	debug		getattrib*	html		mushfunc*
  notify	object		pemit*		setattrib*
  
  MUSH Functions and Commands defined by PennMUSH TCL:

  evaltime()	tcl()		tclclear()	tcleval()	tclparams()
  tclregs()	@tcl

  Attributes used by PennMUSH TCL:

  TCLBOOT

  Note that in specifying dbrefs, tcl will take either '#1' or '1' to
  mean what you would express as #1 in MUSH code.
  
  For more help, see 'help TCL <item>'
& TCL getattrib
  getattrib object attribute

  Return the value of attribute on object.
  
  Example:
    if { [getattrib $player sex] == "Male" } {
      pemit $player "Wow, you are a male!";
    } else {
      pemit $player "Oops, I guess you aren't a male!";
    }
& TCL mushfunc
  mushfunc <mush function code>

  Returns the evaluation of <mush function code> by the regular MUSH
  parser.

  Example:
    pemit $player "This PennMUSH's name is: [mushfunc mudname()]";
& TCL pemit
  pemit object message

  Send message to object. Return nothing.
  
  Example:
    for { set i 1 } { $i <= 10 } { incr i } {
      pemit $player "Hi this is pass #$i of 10";
    }
& TCL setattrib
  setattrib object attr value

  Set attribute attr on object to to the value of value. Return nothing.
  
  Example:
    setattrib $player sex "Male";
& TCL addcmd
  addcmd <MUSH CmdName> <TCL ProcName> <flags>
  Restricted to Wizards.

  Adds a command CmdName that calls procedure ProcName. ProcName must
  not be the same as CmdName, and the procedure ProcName must be in the
  same interpreter as the call to addcmd. The <flags> field allows the
  command to have some basic info that all hardcoded PennMUSH commands
  do. For a list of valid falgs, see 'help tcl addcmd flags'.

  Example:
    proc cmd_mudname { enactor caller switches argleft } {
      pemit $enactor "You are the enactor on [mushfunc mudname()]";
      pemit $caller "You are the caller of @mudname. You gave the \
                     following switches: $switches";
      if { [string length $argleft] != 0 } {
        pemit $enactor "You gave '$argleft' as arguments to me.";
      }
    }
    addcmd @mudname cmd_mudname "nogag";

  Continued in 'help tcl addcmd2'.
& TCL addcmd2
  Second example using the EQSPLIT flag:

    proc cmd_substr { enactor caller switches substr1 substr2 } {
      pemit $enactor "The first substr is $substr1, the second substr \
                      is $substr2.";
    }
    addcmd @substr cmd_substr "nogag eqsplit"

  Note that even if you '@substr' this command will still run, just with
  null arguments for substr1 and substr2 (argleft and argright of the
  equal sign respectivally).
& TCL addcmd flags
  The valid flags for the <flags> field are:

  NOGAG   makes it so gagged players can't use it
  NOGUEST makes it so guests can't use it
  WIZARD  making it so that only Wizards can use it
  ADMIN   making it so that only Royalty and Wizards can use it
  GOD     making it so that only #1 can use it
  EQSPLIT splitting the command into 2 different args at the equal 
          sign
  LNP     causes everything on the left side of the equal sign not 
          to be parsed
  RNP     same as lnp except for the right rather than left side
  LA      parse everything on the left side of the equal sign into 
          seperate attribs by seperation by ' '
  RA      same as la only for the right rather than left side.

  You can combine two or more of these together, to increase functionality.
& TCL addfunc
  addfunc <MUSH FunName> <TCL ProcName> <min args> <max args> <eval type>
  Restricted to Wizards.

  Adds a function called FunName to the MUSH similar to '@function'ed
  function that calls ProcName when invoked. Procedure ProcName must be
  defined and in the same interpreter as the addfunc call. Min args and
  Max args are integers representing the minimum and maximum number of
  arguments the function will accept. The eval type is a indication to
  the MUSH if the arguments should be parsed or not, and may have the
  following values:

  REG		Causes the arguments to be parsed
  NOPARSE	Causes the arguemtns not to be parsed
  
  Example:
    proc func_test_args { enactor caller switches arguments } {
      if { [llength $arguments] > 2 } {
        pemit $enactor "Wow you entered more than half the possible \
                        arguments."
      }
    }
    addfunc test_args func_test_args 1 4 reg

    > think test_args(1, 2, 3)
    Wow you entered more than half the possible arguments. 

  Note that since functions can't have switches, that field will always
  be empty. The arguments variable is passed as a TCL list of all the
  arguments supplied to the calling MUSH function.
& TCL addhook
  addhook <hook> <TCL ProcName>
  Restricted to Wizards.

  Adds in a 'hook' or call to procedure proc into the specified hook. An 
  important note: the procedure proc must be a procedure defined within
  the interpreter that calls addhook.
  
  This command has the following options for <hook>:
  clone		connect		create		dbdump
  disconnect	free		shutdown	startup
  timer
  
  Example:
    proc message {} {
      pemit 1 "Did you know that at this moment the DB is dumping?!"
    }
    addhook dbdump message

  See 'help TCL addhook <option> for details'.
& TCL addhook clone
  addhook clone <TCL ProcName>

  Adds a call to the procedure into the object cloning sequence. 
  The procedure will be passed 2 arguments, the dbrefs of the new and
  old object.
& TCL addhook connect
  addhook connect <TCL ProcName>

  Adds a call to the procedure into the player connection code.
  The procedure will be passed 1 argument, which is the dbref of the
  player who is connecting.
& TCL addhook create
  addhook create <TCL ProcName>

  Adds a call to the procedure into the object creation sequence.
  The procedure will be passed 1 arguement, which is the dbref of the
  new object.
& TCL addhook dbdump
  addhook dbdump <TCL ProcName>

  Adds a call to the procedure into the database dumping sequence for 
  the MUSH. The procedure will be passed no arguments.
& TCL addhook disconnect
  addhook disconnect <TCL ProcName>

  Adds a call to the procedure into the player disconnection code.
  The procedure will be passed 1 argument, which is the dbref of the
  player who is disconnecting.
& TCL addhook free
  addhook free <TCL ProcName>

  Adds a call to the procedure into the object freeing(destruction)
  sequence. The procedure will be passed 1 argument, which is the dbref
  of the object.
& TCL addhook shutdown
  addhook shutdown <TCL ProcName>

  Adds a call to procedure into the shutdown sequence for the MUSH.
  The procedure will be passed no arguments.
& TCL addhook startup
  addhook startup <TCL ProcName>

  Adds a call to procedure into the startup sequence for the MUSH. 
  The procedure will be called after the database is read and
  everything is setup.  The procedure will be passed no arguments.
& TCL addhook timer
  addhook timer <TCL ProcName>

  Adds a call to the procedure into the PennTCL tick timer. The
  procedure will be passed no arguments.
& TCL ansi
  ansi <color> <string>

  This command workst just like the builtin MUSH ansi() function.
  The color codes used are the same. It does respect the COLOR and
  ANSI flags, as well, so you don't need to explicitly check for
  those.

  Example:
    pemit 1 [ansi gh "This is green!"]

  Will show #1 the string in bold green "This is green!"
& TCL attrib
  attrib <option> [<args>]

  Performs one of several attribute operations, depending on what option
  is selected.
  
  This command has the following possible options:
  canget	canset		get		getp
  has		hasp		haspv		hasv
  set		flags		list
  
  Example:
    notify object 1 [attrib get 1 describe];
  
    if [attrib has #1 describe] {
      notify object #1 "You have a describe attribute";
    }
  
    foreach atr [attrib list #1 *] {
      notify object 1 "$atr ([attrib flags #1 $atr]) [attrib get 1 $atr]";
    }
  
  See 'help TCL attrib <option>' for details.
& TCL attrib canget
  attrib canget <dbref> <attribute>

  Return 1 if the TCL code running can get the attribute on dbref, 0
  otherwise.
& TCL attrib canset
  attrib canset <dbref> <attribute>

  Return 1 if the TCL code running can set the attribute on dbref, 0
  otherwise.
& TCL attrib get
  attrib get <dbref> <attribute>

  Return the contents of dbref's attribute. This command does not check
  dbref's parents for the attribute.
& TCL attrib getp
  attrib getp <dbref> <attribute>

  Return the contents of dbref's attribute. This command does check
  dbref's parents for the attribute.
& TCL attrib has
  attrib has <dbref> <attribute>

  Return 1 if dbref has attribute, otherwise 0. This command does not
  check dbref's parents for the attribute.
& TCL attrib hasp
  attrib hasp <dbref> <attribute>

  Return 1 if dbref has attribute, otherwise 0. This command does check
  dbref's parents for the attribute.
& TCL attrib haspv
  attrib haspv <dbref> <attribute>

  Return 1 if dbref has attribute and attribute is not empty, otherwise
  0. This command does check dbref's parents for the attribute.
& TCL attrib hasv
  attrib hasv <dbref> <attribute>

  Return 1 if dbref has attribute and attribute is not empty, otherwise
  0. This command does not check dbref's parents for the attribute.
& TCL attrib set
  attrib set <dbref> <attribute> [<value>]

  If value is specified, this command will attempt to set dbref's
  attribute to value. Otherwise dbref's attribute will be wiped. This
  command returns nothing.
& TCL attrib flags
  attrib flags <dbref> <attribute> [<value>]

  If value is specified, this command will attempt to add or remove a
  flab from dbref's attribute. Otherwise it will return the list of
  flags on dbref's attribute.
& TCL attrib list
  attrib list <dbref> <pattern>

  Returns a list of all attributes on dbref that match pattern (glob
  style matching).
& TCL connection
  connection <option> [<args>]

  Performs one of several connection operations, depending on what
  option is selected.
  
  This command has the following possible options:
  connected	doing		hidden		idle
  list		mortallist	poll
  
  Example:
    foreach p [connection list] {
      notify object 1 "[format %-30s [object name $p]] Online [clock format \
        [connection connected $p] -format "%Hh %Mm %Ss"] Idle [clock format \
        [connection idle $p] -format "%Hh %Mm %Ss"]";
    }

  See 'help TCL connection <option>' for details.
& TCL connection connected
  connection connected <dbref>

  Return the number of seconds that dbref has been connected, or -1 if
  the player is not currently connected.
& TCL connection doing
  connection doing <dbref>

  Returns dbref's @doing.
& TCL connection hidden
  connection hidden <dbref>
  
  Return 1 if the dbref is hidden and you have privs to see them while
  hidden (mortals can't use this command on roy/wiz), otherwise return
  0.
& TCL connection idle
  connection idle <dbref>

  Returns the number of seconds dbref has been idle, or -1 if dbref
  isn't connected.
& TCL connection list
  connection list

  Return a list of the dbrefs of connected players.
& TCL connection mortallist
  connection mortallist

  Return a list of the dbrefs of connected players, as if run by a
  mortal.
& TCL connection poll
  connection poll [<message>]

  If message is specified, set the @poll to message.

  Returns the current @poll.
& TCL debug
  debug <level>

  Sets up debugging. Unsure as to exactly what it does.
& TCL html
  html <option> <arg1> [<args>]

  Formats HTML output. Option may be one of, endtag, tag, and
  tagwrap. These functions act like their mush counterparts, so for
  more information on their use, see 'help endtag', 'help tag', and
  'help tagwrap'.
& TCL object
  object <option> [<args>]

  Object control commands from TCL. Most or all of these corrispond
  to a function in pennmush, and you should access the help on the
  PennMUSH function to get what they do. They work just the same,
  but with the slightly different syntax adapted for TCL rather than
  the PennMUSH parser.

  Those noted as DNE do not have a MUSH equilivant, but it should be
  obvious what they do.

  Object command and syntax:				PennMUSH function:
    cansee <looker> <lookee>				visible()
    clone <object>					clone()
    contents <object>					lcon()
    controls <controler> <controlee>			controls()
    create <name>					create()
    destroy <object>					DNE
    elock <object> <locktype> <actor>			elock()
    exits <object>					lexits()
    firstcontent <object>				first(lcon())
    firstexit <object>					first(lexits())
    flags <object> [<flag to add>|!<flag to remove>]	set()
    link <object> [<new link value>]			link()
    locate <object> <name> <paramaters>			locate()
    location <object> [<new location value>]		loc()
    lock <object> <locktype> [<new lock value>]		lock()
    name <object>					name()
    nearby <looker> <lookee>				nearby()
    next <object>					complex
    owner <object> [<new owner>]			owner() and DNE
    parent <object> [<new parent>]			parent()
    powers <object> [<power to add>|!<power to remove>]	power() and DNE
    zone <object> [<new zone>]				zone()
& TCL notify
  notify <class> <target list> <message>

  Notify the player, room, or zone with message. (like @emit)
  
  This command has the following possible options:
  channel	object		room		zone 
  
  Example:
   if { $player == 22 } { 
     notify room 0 "[object name $player] is a traitor against us.";
   } else {
     notify object $player "Man, did you see those bogies on our tail?"
     notify object $player "That was close."
   }

  See 'help TCL notify <option>' for details.
& TCL notify channel
  notify channel <channel> <message>

  Notifies the channel with message. Works like @cemit.
  Returns nothing.
& TCL notify object
  notify object <dbref> [<dbref> ...] <message>

  Notifies the list of dbrefs with the specified message.
  Reutrns nothing.
& TCL notify room
  notify room <dbref> [<exception>] <message>

  Notifies the contents of dbref room except for exception with message.
  Specify exception as -1 if everyone in dbref room should be notified.
  Returns nothing.
& TCL notify zone
  notify zone <dbref> <message>

  Notifies the contents of all the rooms in dbref zone with message.
  Returns nothing.
& TCL @tcl
  @tcl?/switch? ?args?

  Manipulate interpreters. If no switch is present, execute commandspecified 
  in args. God can specify /master to evauate in the masterinterpreter.
  
  This command has the switches:
  debug		kill		list		load
  reload	status
  
  Example:
    > @tcl expr 2 + 2
    Result: 4

  See 'help TCL @tcl <option>' for details.
& TCL @tcl debug
  @tcl/debug [<interpreter>]

  Toggle debug status for interpreter (your own if unspecified). 
  To increase the debugging level, use the TCL command 'debug'.
& TCL @tcl kill
  @tcl/kill [<interpreter>]

  Kill interpreter and unload it (your own if unspecified).
& TCL @tcl list
  @tcl/list

  Show a list of all active TCL interpreters you can see.
& TCL @tcl load
  @tcl/load[/master] <file>

  Load file into the a TCL interpreter for the MUSH. If /master is
  specified, the file will be loaded into the master interpreter.

  File is a filename relative to where the PennMUSH was started
  (whatever the directory of the restart script is).

  This command is restriced to God.
& TCL @tcl reload
  @tcl/reload <file>

  Kill and reload an interpreter that was loaded from file.
  
  This command is restriced to God.
& TCL @tcl status
  @tcl/status [<interpreter>]

  Return status for interpreter (your own if unspecified). If the
  procedure 'status' is defined in that interpreter, evaluate it and
  print it's result as well.
& TCL evaltime()
  evaltime(<pennmush code>[,<repetitions>])

  Times the evaluation of <pennmush code>, and will run it <repetitions>
  times if you specify it, or a default number otherwise. The
  command doesn't tell you what each number is, but I believe them
  to be:

  (lowest time) (highest time) (average time)
& TCL tcl()
  tcl(<TCL code>[,<arg 1> ...])

  Evaluate a piece of TCL code. The arguments after the code will be
  available in the in array indexed from 0 to 9.
  
  Example:
    > think tcl(expr $in(0) + $in(1),2,3)
    5
    > think tcl(object name $in(0),num(me))
    God
& TCL tclclear()
  tclclear(<dbref>)

  Will try to remove the TCL interpreter for dbref.
  
  Example:
    > @tcl expr 2 + 2
    Result: 4
    > think tclclear(num(me))
    <nothing returned>
    > @tcl/list
    <nothing returned>
& TCL tcleval()
  tcleval([<dbref>/]<attribute>)

  Retrieve dbref's (or your if dbref unspecified) attribute and evaluate
  it as TCL code.

  Example:
    > &TCL_ADD me=expr 2 + 2
    God/TCL_ADD - Set.
    > think tcleval(tcl_add)
    4
& TCL tclparams()
  tclparams(<arg 0>[,<arg 1>[...<arg 9>]])

  Will set arguments in the TCL interpreter's mushparams array so that
  they are available to TCL code about to be executed (probably via
  tcleval()). Each argument is available via it's number in the
  mushparams array.
  
  Example:
    > &TCL_PAR me=return $mushparams(2)
    God/TCL_PAR - Set.
    > think [tclparams(1,2,3,4)][tcleval(tcl_par)]
    3
& TCL tclregs()
  tclregs()

  Will map the MUSH registers %q0 through %q9 into the TCL interpreter's
  mushregs array (mushregs(0) through mushregs(9)).
  
  Example:
    > &TCL_PAR me=return $mushregs(0)
    God/TCL_PAR - Set.
    > think [setq(0,HeyHey)][tclregs()][tcleval(tcl_par)]
    HeyHey
& TCL TCLBOOT 
  The TCLBOOT0, TCLBOOT1, ... attributes on an object are executed when
  an interpreter is first spawned for that object. For example:

    > &TCLBOOT0 me=set default "hi"
    God/TCLBOOT0 - Set.
    > &CODE me=pemit 1 "Default is set to $default right now."
    God/CODE - Set.
    > think [tcleval(code)]
    Default is set to hi right now.