       The MUF Cheat-Sheet, as seen by Sammael (Arthur, The., etc)
                              -or-
           Reference manual for MUCK Forth ("MUF")  -terse
  
                                                 v2.2fb4.0 July 29, 1990

ENTERING EDITING MODE
        @program <program name>    (creates a new program if none match)
        @edit <program name or number>
  
EDITING COMMANDS
        <number> i                              insert before <number>
        .                                       exit insert mode
        c                                       compile
        <number1> <number2> l                   list
        <number1> <number2> d                   delete
        <letter> <letter>   a                   show macros (abridged)
        <letter> <letter>   s                   show macros (long)
        <program#> v                            view program header
        <program#> p                            list prog's public functs.
        h                                       help on edit mode
        u                                       uncompile
        q                                       quit editor mode
  

COMPILER DIRECTIVES
  
        $echo <string>                          Echos <string> during compile
        $define <defname> <defin.> $enddef      Defines <defname> to <defin.>
	$def <defname> <defin.>                 Same, but stops at end of line
        $undef <defname>                        Undefines <defname>
        $include <obj>                          Load $defines from <obj>
        $ifdef <defname>[<comparison>]          Starts $ifdef clause.
        $ifndef <defname>[<comparison>]         Starts $ifndef clause.
        $else                                   Compile if $if[n]def failed.
        $endif                                  Marks end of $if[n]def clause
  
        note:  __version is a standard $define, containing the server version.

  
STRUCTURES

        A function has the format of
            : <funcname> <instruction> [<instruction> ... ] ;

        If-then statements use the structure
            <comparisons> if <cmds_if_true> [else <cmds_if_false>] then

        Loops can use two different structures.
            begin
              <instructions>
              <comparisons>
            until   (repeats loop until comparison is true)
            begin
              <instructions>
            repeat  (repeat loop)

        Both types of loops can contain as many of the following as needed.
            <comparison> while  (if comparison is false, exit the loop)
            break               (exit the loop.  Often used inside if-thens)
            continue            (go to the start of the loop. used in if-thens)


PRIMITIVE TERMINOLOGY
  
        v                                       type variable
        d                                       type dbref
        i                                       type int (boolean)
        s                                       type string
        a                                       type address (word)
  

SYNTAX
  
        ( ... )                                 commments
        :                                       begin user-def word
        ;                                       end user-def word
        var <VARNAME>                           variable declaration
        lvar <VARNAME>                          local variable declaration.
        public <FUNCNAME>                       declares a function public.
  
	checkargs       ( s -- )           checks stack against 's' arg. desc.

        if              ( i -- )
        else            ( -- )
        then            ( -- )

        begin           ( -- )             defines the beginning of loops.
        while           ( i -- )           break out of loop if value is false
        break           ( -- )             break out of loop.
        continue        ( -- )             jump to beginning of loop.
        until           ( i -- )           ends begin-until. repeats if false.
        repeat          ( -- )             ends begin-repeat. jumps to begin.

        jmp             ( a -- )           jumps execution to given address.
        exit            ( -- )             exit the current subroutine.
	abort           ( s -- )           stop MUF prog w/ given error mesg.
        execute         ( a -- ??? )       call a given subroutine by address.
        call            ( d -- ??? )       call remote program
                     or ( d s -- ??? )     call public function in remote prog

        preempt         ( -- )             stops multitasking.
        background      ( -- )             starts multitasking, no blocking.
        foreground      ( -- )             starts multitasking, blocking user
                                            input for that user.
  
        sleep           ( i -- )           pause the program for i seconds
        fork            ( -- i )           forks off BG muf process.  Returns
                                            pid to parent and 0 to child.
        queue           ( i d s -- i )     queue event to run prog d after i
                                            seconds with s on the stack.
                                            Returns pid of queued process.
        kill            ( i -- )           kills process of given pid.
	ispid?          ( i -- i )         processID -- process_exists?

        pop             ( x -- )
        dup             ( x -- x x )
        swap            ( x y -- y x )
        over            ( x y -- x y x )
        rot             ( x y z -- y z x )
        rotate          ( ni ... n1 i -- n(i-1) ... n1 ni )
        pick            ( ni ... n1 i -- n1 ni )
        put             ( ni ... n1 x i -- x ... n1 )
  
        !               ( x v -- )              store value x in var v.
                                                 value may be any type data
        @               ( v -- x )              fetch value x from var v
        atoi            ( s -- i )              string --> integer
        intostr         ( i -- s )              integer || dbref --> string
        dbref           ( i -- d )              integer --> dbref
        int             ( x -- i )              VAR || object --> integer
        variable        ( i -- v )              integer --> VAR ref
  
        + - * / %       ( i1 i2 -- i )          
        < > = <= >=     ( i1 i2 -- i )
        strcmp,
           stringcmp    ( s1 s2 -- i )          strcmp == case sens.
	stringpfx       ( s1 s2 -- i )          return 0 if s2 is prefix of s1
        strncmp         ( s1 s2 n -- i )        compares only n letters
        number?         ( s -- i )
        dbcmp           ( d1 d2 -- i )
        and  or         ( i1 i2 -- i )
        not             ( i -- i' )
  
        strlen          ( s -- i )
        strcat          ( s1 s2 -- s )
        instr           ( s1 s2 -- i )          finds s2 in s1.  0 if !found
        strcut          ( s i -- s1 s2 )        cuts string at pos. i
        explode         ( s1 s2 -- ... i )      s2 is the partition, len >0
        subst           ( s1 s2 s3 -- s )       string, replacement, tobesub
        pronoun_sub     ( d s -- s' )           does % subs a la osucc/ofail
  
        read            ( -- s )
        notify          ( d s -- )              player, message 
        notify_except   ( d1 d2 s -- )          place, player, message 
        notify_exclude  (s dn..d1 i dr-- )     Send s to all players in room
                                                dr except for the i players
                                                listed in d1 through dn.

        pennies         ( d -- i )
        addpennies      ( d i -- )              player, pennies
        random          ( -- i )
  
        getpropval      ( d s -- i )            zero if none
        getpropstr      ( d s -- s )            "" if none
        addprop         ( d s1 s2 i -- )        ignores i unless s2 is ""
        remove_prop     ( d s -- )
  
        desc, name, succ,
        fail, drop, osucc,
        ofail, odrop:           ( d -- s )      retrieve message
  
        setname, setdesc,
        setsucc, setfail,
        setdrop, setosucc,
        setofail:               ( d s -- )      set message
  
        player?, thing?,
        room?, program?,
        exit?, ok?:             ( d -- i )      boolean
  
        location                ( d -- d' )
        owner                   ( d -- d' )
        moveto                  ( d1 d2 -- )    moves d1 to d2
        set                     ( d s -- )      object, string (flag)
        flag?                   ( d s -- i )    object, string -- boolean
	mlevel                  ( d -- i )      object -- mucker level.
        match                   ( s -- d )      thing, dbref (#-1 = NOTHING,
                                                #-2 = AMBIGUOUS, #-3 = HOME)
        rmatch                  ( d s -- d )    object, thing, dbref           
	part_pmatch             ( s -- d )      partial name -- dbref
        copyobj                 ( d -- d' )     returns dbref of new object
        contents                ( d -- ... i )  returns stack of dbrefs and i
  
	time            ( -- i i i)        seconds, minutes, hours
	date            ( -- i i i)        monthday, month,  year
        systime         ( -- i )           system time in secs since
                                            00:00 1/1/70 GMT
        timesplit       ( i -- 8 ints)     sec, m, hr, dy, mnth, yr, wkdy, yrdy
        timefmt         ( s i -- s )       format, systime -- timestring
	gmtoffset       ( -- s )           seconds offset from GMT time.
  
        setlink         ( d d -- )         object, dest
        setown          ( d d -- )         object, newowner
        newobject       ( d s -- d )       location, name  -- new objref
        newroom         ( d s -- d )       parent, name  -- new objref
        newexit         ( d s -- d )       attached-to, name  -- new objref
        recycle         ( d -- )           item to recycle
        stats           ( d -- 7 ints)     owner -- totalowned, #rooms, #exits,
                                                  #things, #programs, #players,
                                                  #garbage.
  
        int?            ( ? -- i )         is top stack item an integer?
        string?         ( ? -- i )         is top stack item a string?
        dbref?          ( ? -- i )         is top stack item a dbref?
        nextprop        ( d s -- s )       object, propname -- next propname
        propdir?        ( d s -- i )       object, propname--is it a propdir?
  
        awake?          ( d -- i )         player -- number of connections
        online          ( -- dN ... d1 N ) all connected players w/ count
        concount        ( -- i )           # of connections to the server
        condbref        ( i -- d )         connection number -- player
        conidle         ( i -- i )         conn. # -- idle time in secs
        contime         ( i -- i )         conn. # -- online time in secs
        conhost         ( i -- s )         conn. # -- hostname
        conboot         ( i -- )           connection number
        connotify       ( i s -- )         connection number, string
        condescr        ( i -- i )         connection# -- descriptor#
	descrcon        ( i -- i )         descriptor# -- connection#
	nextdescr       ( i -- i )         descriptor# -- next descriptor#
	descriptors     ( d -- ix..i1 i )  plyr -- descriptors... count
  
        bitor           ( i i -- i )       int, int -- bitwise or result
        bitxor          ( i i -- i )       int, int -- bitwise exclusive-or
        bitand          ( i i -- i )       int, int -- bitwise and result
        bitshift        ( i i -- i )       int, #bits -- bitwise shift
  
        version         ( -- s )           Version String
        depth           ( -- i )           stack depth
        dbtop           ( -- d )           top of database + 1 item.
        prog            ( -- d )           this program's dbref
        trig            ( -- d )           a secure form of trigger @
        caller          ( -- d )           the program that called this one.
  
        force           ( d s -- )         player, force string
        localvar        ( i -- l )         local var num -- localvar
  
        locked?         ( d d -- i )       player, object -- is object locked?
        getlockstr      ( d -- s )         object -- lockstring
        setlockstr      ( d s -- i )       object, lockstr -- successful?
  
        toupper         ( s -- s )         uppercases all letters in the string
        tolower         ( s -- s )         lowercases all letters in the string
        instring        ( s s -- i )       case insensitive version of instr
        rinstring       ( s s -- i )       case insensitive version of rinstr
        striplead       ( s -- s )         Strip leading spaces from string.
        striptail       ( s -- s )         Strip tail spaces from string.
        strip           ( s -- s )         Basically 'striplead striptail'
        unparseobj      ( d -- s )         object -- name-and-flags-string.
        smatch          ( s s -- i )       string, smatch string -- matched?
        envpropstr      ( d s -- d s )     startobj, propname -- obj strval
  
LIBRARIES
    How to use a library:
        1) Use "@register lib" to list what libraries exist.
        2) Use "@view $lib/<libraryname>" to list the docs on that library.
        3) When you've found the library and the function you want, then all
            you have to do in your program is, at the beginning of it,
              $include $lib/<libraryname>
            then just use the function name to invoke it later in your program
            and it will run as if it were a function in your program.

    How to make a library:
        1) create a program with several useful generic subroutines.
        2) DOCUMENT those subroutines in a commented out header in the prog.
        3) @set <program>=_docs:<command to list those DOCS you made>
        4) make sure that all the functions are declared PUBLIC.
        5) Make sure the program is set LINK_OK.
        6) Globally register the program with the @register command with a
            prefix of "lib/".  ie: @reg lib-strings=lib/strings
        7) Set up the interface for each function on the program. To do this,
            you will need to set properties on the program in the form
              _defs/<callname>:"$<libname>" match "<funcname>" call
            where <callname> is the name that you want to have people use to
            invoke it in their programs, <libname> is the registered name you
            gave it (ie: lib/strings), and <funcname> is the actual name of
            the function in the program.  Example:
              @set lib-strings=_defs/.split:"$lib/strings" match "split" call
        8) You're done!
