builtins.rpl

( CODSWALLOP RPL, a zen garden
  #####################################################
  Builtins )

(This file prepares all of the builtin commands that are close to just being
 wrappers around internals.  As handed to us, the only information available 
 is a list of types and a set of internals: single dispatch routines with no 
 type or argument checking.  Our job is to build the nice safe
 multiply-dispatched userspace from those building blocks.)

(First, here's a thing which makes the rest of this code easier to read.
 It takes a list of tags and uses those to prepare and store the builtins.
 Sort of like named arguments, by abusing local variables.)
'::
  ':: table args hint 'name I*.rcl I*.>bin I*.binhook 'name I*.rcl I*.sto ;
  I*.swap I*.local ;
'I*.stobin I*.sto


( ### Documentation )

(List of names.)
{ :name: NAMES
  :args: #0
  :hint: "Return a list of all global symbols."
  :table: { { :: `I*.firstobj `I*.dir ; } } }
I*.stobin

(List of names in a directory.)
{ :name: DIR
  :args: #1
  :hint: "Return a list of all names in a directory."
  :table: { { I*.dir Types.Directory } } }
I*.stobin

(Object type.)
{ :name: TYPE
  :args: #1
  :hint: "Return an integer representing the type of an object."
  :table: { { I*.type Types.Any } } }
I*.stobin

(Introspect.)
{ :name: SELF
  :args: #0
  :hint: "Return the currently executing code block."
  :table: { { I*.self } } }
I*.stobin


( ### Input/Output)

(Open a file.)
{ :name: FOPEN
  :args: #2
  :hint: "Open a text file for reading or writing."
  :table:
  { { ::
        ':: name attr "read" `I*.== "r"
          ':: attr "write" `I*.== "w"
            ':: attr "append" `I*.== "a"
              ':: attr "A file can only be \"read\", \"write\", or \"append\""
                ':: `I*.ded ; `I*.beval ;
              `I*.ifte ;
            `I*.ifte ;
          `I*.ifte 
  	  `I*.fopen ;
        { attr name } `I*.local ;
      Types.String Types.String } } }
I*.stobin

(Close a file.)
{ :name: FCLOSE
  :args: #1
  :hint: "Close a file."
  :table: { { I*.fclose Types.Handle } } }
I*.stobin

(Check if a file is at EOF.)
{ :name: EOF
  :args: #1
  :hint: "Report whether a file is at EOF (if open for write, always #0.)"
  :table: { { I*.feof Types.Handle } } }
I*.stobin

(Read some bytes from a file.)
{ :name: READ
  :args: #2
  :hint: "Read n characters from a file (or all of them, if n<1.)"
  :table: { { I*.fread Types.Handle Types.Integer } } }
I*.stobin

(Read a line from a file.)
{ :name: READL
  :args: #1
  :hint: "Read a whole line from a file."
  :table: { { I*.freadline Types.Handle } } }
I*.stobin

(Write to a file.)
{ :name: WRITE
  :args: #2
  :hint: "Write a string to a file, with a newline."
  :table: { { I*.fwrite Types.String Types.Handle } } }
I*.stobin

(Write to a file.)
{ :name: WRITEN
  :args: #2
  :hint: "Write a string to a file, without a newline."
  :table: { { I*.fwriten Types.String Types.Handle } } }
I*.stobin

(Display.)
{ :name: DISP
  :args: #1
  :hint: "Print any object in human-readable form to the screen."
  :table: { { I*.disp Types.Any } } }
I*.stobin

(Display with no newline.)
{ :name: DISPN
  :args: #1
  :hint: "DISP without newline."
  :table: { { I*.dispn Types.Any } } }
I*.stobin

(Console input.)
{ :name: PROMPT
  :args: #1
  :hint: "Line input from stdin, with x as a prompt."
  :table: { { I*.prompt Types.Any } } }
I*.stobin

(Time.)
{ :name: EPOCH
  :args: #0
  :hint: "Returns epoch time as a floating point number."
  :table: { { I*.epoch } } }
I*.stobin

( ### Stack manipulation )

(Return whole stack.)
{ :name: STACK
  :args: #0
  :hint: "Push stack onto the stack."
  :table: { { I*.stack } } }
I*.stobin

(Drop.)
{ :name: DROP
  :args: #1
  :hint: "Pop and discard the first line of the stack."
  :table: { { I*.drop Types.Any } } }
I*.stobin

(Drop multiple.)
{ :name: DROPN
  :args: #1
  :hint: "Drop the first n lines off the stack."
  :table: { { I*.dropn Types.Integer } } }
I*.stobin

(Clear stacks.)
{ :name: CLR
  :args: #0
  :hint: "Clear call and data stacks (end program)."
  :table: { { I*.clr } } }
I*.stobin

(Evaluate.)
{ :name: EVAL
  :args: #1
  :hint: "Evaluate the object on the first line of the stack."
  :table: { { I*.eval Types.Any } } }
I*.stobin

(Swap.)
{ :name: SWAP
  :args: #2
  :hint: "Swap lines 1 and 2 of the stack."
  :table: { { I*.swap Types.Any Types.Any } } }
I*.stobin

(Duplicate.)
{ :name: DUP
  :args: #1
  :hint: "Duplicate the first line of the stack."
  :table: { { I*.dup Types.Any } } }
I*.stobin

{ :name: DUP2
  :args: #2
  :hint: "Duplicate the first and second lines of the stack."
  :table: { { I*.dup2 Types.Any Types.Any } } }
I*.stobin

{ :name: DUPN
  :args: #1
  :hint: "Duplicate n lines of the stack."
  :table: { { I*.dupn Types.Integer } } }
I*.stobin

(Roll.)
{ :name: ROLL
  :args: #1
  :hint: "Roll the first n lines of the stack up."
  :table: { { I*.roll Types.Integer } } }
I*.stobin

{ :name: ROLLD
  :args: #1
  :hint: "Roll the first n lines of the stack down."
  :table: { { I*.rolld Types.Integer } } }
I*.stobin

(Require.)
{ :name: REQUIRE
  :args: #1
  :hint: "Require n objects on the stack to continue."
  :table: { { I*.require Types.Integer } } }
I*.stobin

(Copy.)
{ :name: CP
  :args: #1
  :hint: "Return a new copy of an object.  This is only useful for mutable types (tag, directory, user types.)"
  :table: { { I*.cp Types.Any } } }
I*.stobin


( ### Disk store )

(Parse and evaluate from disk.)
{ :name: DSK>
  :args: #1
  :hint: "Read a file from disk and shove it straight into the parser."
  :table: { { I*.dsk> Types.String } } }
I*.stobin


( ### Named store )
(Store symbol)
{ :name: STO
  :args: #2
  :hint: "Write an object into the named store, either to a local variable if it exists, or to the main store (or into a tag)."
  :table:
  { { I*.sto   Types.Any Types.Symbol }
    { I*.stoto Types.Any Types.Tag } } }
I*.stobin

(Recall symbol)
{ :name: RCL
  :args: #1
  :hint: "Recall an object from the most local named store that has it, or extract an object from a tag."
  :table:
  { { I*.rcl     Types.Symbol }
    { I*.rclfrom Types.Tag } } }
I*.stobin

(Dereference symbol)
{ :name: DEREF
  :args: #1
  :hint: "Return de reference of the most local tag for this symbol in the named store."
  :table:
  { { I*.deref Types.Symbol } } }
I*.stobin

(Does it exist?)
{ :name: EXISTS
  :args: #1
  :hint: "Check to see if a symbol exists in the current named store (including locals.)"
  :table:
  { { I*.exists Types.Symbol } } }
I*.stobin

(Erase name)
{ :name: RM
  :args: #1
  :hint: "Remove an object from the most local named store."
  :table:
  { { I*.rm Types.Symbol } } }
I*.stobin

(New local context)
{ :name: LOCAL
  :args: #2
  :hint: "Create and evaluate a local variable context.  Stack level 2 contains the code which will run in the context; stack level 1 contains a list of symbol names for that context.  Levels 3 and up contain the objects to be stored."
  :table: { { I*.local Types.Code Types.List } } }
I*.stobin


( ### Flow control )
(Bail)
{ :name: BAIL
  :args: #0
  :hint: "Bail out of a context (pop one off the call stack)."
  :table: { { I*.bail } } }
I*.stobin

(Bail-eval)
{ :name: BEVAL
  :args: #1
  :hint: "Bail out of a context and evaluate a new one (this is more or less a goto.)"
  :table: { { I*.beval Types.Any } } }
I*.stobin

(If then)
{ :name: IFT
  :args: #2
  :hint: "If stack level 2 is true, then evaluate stack level 1."
  :table: { { I*.ift Types.Any Types.Any } } }
I*.stobin

(If then else)
{ :name: IFTE
  :args: #3
  :hint: "If stack level 3 is true, then evaluate line 2, else evaluate line 1."
  :table: { { I*.ifte Types.Any Types.Any Types.Any } } }
I*.stobin


( ### Maths )
(Parity)
{ :name: ODD
  :args: #1
  :hint: "Determine if a number is odd."
  :table:
  { { I*.odd Types.Integer } 
    { I*.odd Types.Float } } }
I*.stobin

(Absolute value)
{ :name: ABS
  :args: #1
  :hint: "Return absolute value of a number."
  :table:
  { { I*.absint Types.Integer }
    { I*.absfloat Types.Float } } }
I*.stobin

(Addition)
{ :name: +
  :args: #2
  :hint: "Add or concatenate two objects."
  :table:
  { { I*.+int   Types.Integer Types.Integer }
    { I*.+float Types.Float   Types.Float }
    { I*.+float Types.Integer Types.Float }
    { I*.+float Types.Float   Types.Integer }
    { I*.catlist  Types.List    Types.List }
    { I*.list+  Types.Any     Types.List }
    { I*.+str   Types.String  Types.Any }
    { I*.+list  Types.List    Types.Any }
    { I*.+str   Types.Any     Types.String }
    { I*.catcode  Types.Code    Types.Code } 
    { I*.+sym   Types.Symbol  Types.Symbol } } }
I*.stobin

(Power)
{ :name: ^
  :args: #2
  :hint: "Arithmetic power (y^x)."
  :table:
  { { I*.^int   Types.Integer Types.Integer }
    { I*.^float Types.Float   Types.Float }
    { I*.^float Types.Integer Types.Float }
    { I*.^float Types.Float   Types.Integer } } }
I*.stobin

(Multiply)
{ :name: *
  :args: #2
  :hint: "Arithmetic multiply, or repeat strings, lists, or programs."
  :table:
  { { I*.*int   Types.Integer Types.Integer }
    { I*.*float Types.Float   Types.Float }
    { I*.*float Types.Integer Types.Float }
    { I*.*float Types.Float   Types.Integer }
    { I*.*str   Types.String  Types.Integer }
    { I*.*lst 	Types.List    Types.Integer }
    { I*.*code	Types.Code    Types.Integer } } }
I*.stobin

(Subtract)
{ :name: -
  :args: #2
  :hint: "Arithmetic subtraction."
  :table:
  { { I*.-int   Types.Integer Types.Integer }
    { I*.-float Types.Float   Types.Float }
    { I*.-float Types.Integer Types.Float }
    { I*.-float Types.Float   Types.Integer } } }
I*.stobin

(Divide)
{ :name: /
  :args: #2
  :hint: "Arithmetic division."
  :table:
  { { I*./int   Types.Integer Types.Integer }
    { I*./float Types.Float   Types.Float }
    { I*./float Types.Integer Types.Float }
    { I*./float Types.Float   Types.Integer } } }
I*.stobin

(Modulo)
{ :name: MOD
  :args: #2
  :hint: "Arithmetic division (remainder)."
  :table:
  { { I*.modint   Types.Integer Types.Integer }
    { I*.modfloat Types.Float   Types.Float }
    { I*.modfloat Types.Integer Types.Float }
    { I*.modfloat Types.Float   Types.Integer } } }
I*.stobin

(Negate)
{ :name: NEG
  :args: #1
  :hint: "Negate a number."
  :table:
  { { I*.neg Types.Integer }
    { I*.neg Types.Float } } }
I*.stobin

(Random)
{ :name: RND
  :args: #0
  :hint: "Return a random number between 0 and 1."
  :table: { { I*.rnd } } }
I*.stobin

(Integer portion)
{ :name: IP
  :args: #1
  :hint: "Return integer portion of floating point number."
  :table:
  { { I*.ip Types.Float }
    { I*.ip Types.Integer } } }
I*.stobin


( ### Bitwise operations )
(Bitwise NOT)
{ :name: BNOT
  :args: #1
  :hint: "Bitwise NOT (one's complement) of integer."
  :table: { { I*.bnot Types.Integer } } }
I*.stobin

(Bitwise shift left)
{ :name: BSHL
  :args: #2
  :hint: "Bitwise shift left of integer."
  :table: { { I*.bshl Types.Integer Types.Integer } } }
I*.stobin

(Bitwise shift right)
{ :name: BSHR
  :args: #2
  :hint: "Bitwise shift right of integer."
  :table: { { I*.bshr Types.Integer Types.Integer } } }
I*.stobin

(Bitwise AND)
{ :name: BAND
  :args: #2
  :hint: "Bitwise AND of integers."
  :table: { { I*.band Types.Integer Types.Integer } } }
I*.stobin

(Bitwise OR)
{ :name: BOR
  :args: #2
  :hint: "Bitwise OR of integers."
  :table: { { I*.bor Types.Integer Types.Integer } } }
I*.stobin

(Bitwise XOR)
{ :name: BXOR
  :args: #2
  :hint: "Bitwise XOR of integers."
  :table: { { I*.bxor Types.Integer Types.Integer } } }
I*.stobin


( ### Conversions )

(Make a builtin)
{ :name: >BIN
  :args: #4
  :hint: "Build a new built-in from a hint string, symbol name, an argument count, and a dispatch table in the form of:
  { { code objtype1 objtype2 ... } ... }"
  :table:
  { { :: `I*.>bin `I*.binhook ;
      Types.List Types.Integer Types.String Types.Symbol } } }
I*.stobin

(Hook a builtin)
{ :name: HOOK
  :args: #2
  :hint: "Hook new dispatch lines into an extant builtin, in the same fashion as >BIN."
  :table:
  { { :: `I*.binhook `I*.drop ; Types.List Types.Builtin } } }
I*.stobin

(Make a tag)
{ :name: >TAG
  :args: #2
  :hint: "Prepare a new tag object from any object and a non-dotted symbol."
  :table:
  { { I*.>tag Types.Any Types.Symbol } } }
I*.stobin

(Make directory)
{ :name: MKDIR
  :args: #0
  :hint: "Create a new empty directory."
  :table: { { I*.mkdir } } }
I*.stobin

(Coerce to integer)
{ :name: >INT
  :args: #1
  :hint: "Make a number or string an integer."
  :table:
  { { I*.num>int Types.Float }
    { I*.str>int Types.String }
    { (Fageddaboudit) Types.Integer } } }
I*.stobin

(Coerce to float)
{ :name: >FLOAT
  :args: #1
  :hint: "Make a number or string a float."
  :table:
  { { I*.num>float   Types.Integer }
    { I*.str>float   Types.String }
    { (Fageddaboudit) Types.Float } } }
I*.stobin

(Basic-type VAL)
{ :name: VAL
  :args: #1
  :hint: "Like BASIC, turn a string into a float, 0 if 0, 0 also if error."
  :table: { { I*.basicval Types.String } } }
I*.stobin

(Character to integer)
{ :name: ASC>
  :args: #1
  :hint: "Retreive the character number of the first character in a string."
  :table: { { I*.asc> Types.String } } }
I*.stobin

(Integer to character)
{ :name: >ASC
  :args: #1
  :hint: "Return a character from an integer value."
  :table: { { I*.>asc Types.Integer } } }
I*.stobin

(Anything to quote)
{ :name: QUOTE
  :args: #1
  :hint: "Quote an object."
  :table: { { I*.>quote Types.Any } } }
I*.stobin

(String to objects)
{ :name: >OBJ
  :args: #1
  :hint: "Parse a string into an RPL object."
  :table: { { I*.>obj Types.String } } }
I*.stobin

(To symbol)
{ :name: >SYM
  :args: #1
  :hint: "Turn a string into a symbol."
  :table:
  { { I*.str>sym Types.String } } }
I*.stobin

(To string)
{ :name: >STR
  :args: #1
  :hint: "Return a string representation of an object."
  :table: { { I*.>str Types.Any } } }
I*.stobin


( ### Comparisons )

(Equality)
{ :name: ==
  :args: #2
  :hint: "Test two objects for equality."
  :table: { { I*.== Types.Any Types.Any } } }
I*.stobin

(Inequality)
{ :name: !=
  :args: #2
  :hint: "Test two objects for inequality."
  :table: { { I*.!= Types.Any Types.Any } } }
I*.stobin

(Reference check)
{ :name: SAME
  :args: #2
  :hint: "Test two objects for physical sameness."
  :table: { { I*.==ref Types.Any Types.Any } } }
I*.stobin

(Reference check)
{ :name: !SAME
  :args: #2
  :hint: "Test two objects for physical difference."
  :table: { { I*.!=ref Types.Any Types.Any } } }
I*.stobin

(Less than)
{ :name: <
  :args: #2
  :hint: "Compare two numbers."
  :table:
  { { I*.< Types.Integer Types.Integer }
    { I*.< Types.Float   Types.Float }
    { I*.< Types.Integer Types.Float }
    { I*.< Types.Float   Types.Integer } } }
I*.stobin

(Less than or equal to)
{ :name: <=
  :args: #2
  :hint: "Compare two numbers."
  :table:
  { { I*.<= Types.Integer Types.Integer }
    { I*.<= Types.Float   Types.Float }
    { I*.<= Types.Integer Types.Float }
    { I*.<= Types.Float   Types.Integer } } }
I*.stobin

(Greater than)
{ :name: >
  :args: #2
  :hint: "Compare two numbers."
  :table:
  { { I*.> Types.Integer Types.Integer }
    { I*.> Types.Float   Types.Float }
    { I*.> Types.Integer Types.Float }
    { I*.> Types.Float   Types.Integer } } }
I*.stobin

(Greater than or equal to)
{ :name: >=
  :args: #2
  :hint: "Compare two numbers."
  :table:
  { { I*.>= Types.Integer Types.Integer }
    { I*.>= Types.Float   Types.Float }
    { I*.>= Types.Integer Types.Float }
    { I*.>= Types.Float   Types.Integer } } }
I*.stobin

(AND)
{ :name: AND
  :args: #2
  :hint: "Compare two numbers."
  :table:
  { { I*.and Types.Integer Types.Integer }
    { I*.and Types.Float   Types.Float }
    { I*.and Types.Integer Types.Float }
    { I*.and Types.Float   Types.Integer } } }
I*.stobin

(OR)
{ :name: OR
  :args: #2
  :hint: "Compare two numbers."
  :table:
  { { I*.or Types.Integer Types.Integer }
    { I*.or Types.Float   Types.Float }
    { I*.or Types.Integer Types.Float }
    { I*.or Types.Float   Types.Integer } } }
I*.stobin

(NOT)
{ :name: NOT
  :args: #1
  :hint: "Boolean NOT: return #0 if object is true, or #1 if it is false."
  :table:
  { { I*.not Types.Integer }
    { I*.not Types.Float } } }
I*.stobin


( ### List functions )
(Length)
{ :name: LEN
  :args: #1
  :hint: "Return the length of a compound object or string, or the depth of a symbol."
  :table:
  { { I*.len Types.List }
    { I*.len Types.String }
    { I*.lencode Types.Code } 
    { I*.len Types.Symbol } } }
I*.stobin

(Pop)
{ :name: POP
  :args: #1
  :hint: "Pop the last item off a list."
  :table:
  { { I*.pop Types.List }
    { I*.pop Types.Code } } }
I*.stobin

(Obj>)
{ :name: OBJ>
  :args: #1
  :hint: "Break up a composite object and return the object count in stack level 1.  Or return the contents of a tag or builtin."
  :table:
  { { I*.composite> Types.List }
    { I*.composite> Types.Code }
    { I*.tag>	    Types.Tag }
    { I*.context>   Types.Context }
    { I*.bin>       Types.Builtin } } }
I*.stobin

(Subset from left)
{ :name: LEFT
  :args: #2
  :hint: "Fetch a subset of a string, list, or program."
  :table:
  { { I*.left Types.String Types.Integer }
    { I*.left Types.List   Types.Integer }
    { I*.left Types.Code   Types.Integer } } }
I*.stobin

(Subset from right)
{ :name: RIGHT
  :args: #2
  :hint: "Fetch a subset of a string, list, or program."
  :table:
  { { I*.right Types.String Types.Integer }
    { I*.right Types.List   Types.Integer }
    { I*.right Types.Code   Types.Integer } } }
I*.stobin

(Subset from middle)
{ :name: SUBS
  :args: #3
  :hint: "Fetch a subset of a string, list, or program."
  :table:
  { { I*.subs Types.String Types.Integer Types.Integer }
    { I*.subs Types.List   Types.Integer Types.Integer }
    { I*.subs Types.Code   Types.Integer Types.Integer } } }
I*.stobin

(Get from list and evaluate)
{ :name: GETE
  :args: #2
  :hint: "Fetch an object from a list or code and evaluate it."
  :table:
  { { I*.gete Types.List Types.Integer }
    { I*.gete Types.Code Types.Integer } } }
I*.stobin

(Get from composite)
{ :name: GET
  :args: #2
  :hint: "Fetch a character from a string or an object from a list or code."
  :table:
  { { I*.get Types.List   Types.Integer }
    { I*.get Types.String Types.Integer }
    { I*.get Types.Code   Types.Integer } } }
I*.stobin

(Put to composite)
{ :name: PUT
  :args: #3
  :hint: "Store an object into a list or code."
  :table:
  { { I*.put Types.List Types.Any Types.Integer }
    { I*.put Types.Code Types.Any Types.Integer } } }
I*.stobin

(Make list)
{ :name: >LST
  :args: #1
  :hint: "Combine x objects into a list, or convert code to a list."
  :table:
  { { I*.>lst          Types.Integer }
    { I*.composite>lst Types.Code }
    { (Nothin')        Types.List } } }
I*.stobin


( ### Error handling functions )
(Cause an error)
{ :name: DED
  :hint: "Invoke error handler with level 1 as its message."
  :args: #1
  :table: { { I*.ded Types.String } } }
I*.stobin

(Is there an error?)
{ :name: ISDED
  :args: #0
  :hint: "Return a boolean representing an uncleared error."
  :table: { { I*.isded } } }
I*.stobin

(Clear error state)
{ :name: UNDED
  :args: #0
  :hint: "Clear stored error condition."
  :table: { { I*.unded } } }
I*.stobin

(Set error continuation)
{ :name: DEDCONT
  :args: #1
  :hint: "Set error continuation: 0 will stop on error, 1 will suppress some messages but still set ISDED."
  :table: { { I*.dedcont Types.Integer } } }
I*.stobin

(Set traceback depth)
{ :name: TRACE
  :args: #1
  :hint: "Set the number of contexts to leave on the call stack with CLR or when tracing back an error (normally 1 for interactive mode, or 0 otherwise.)"
  :table: { { I*.trace Types.Integer } } }
I*.stobin