;; reference manual for PIC18 Purrr language

(module pic18-ref mzscheme

  
  
  (require "documentation.ss"
           "ns.ss")

;  (for-each ns-new
;            '((doc)
;              (doc live)
;              (doc stack)
;              (doc math)
;              (doc memory)
;              (doc control)
;              (doc predicates)))

  (documentation (doc live)
    (load  <filename> (--) "Load a forth file.")
    (commit           (--) "Commit current assembler buffer to chip.")

    (pa               (--) "Print the contents of the assembler buffer.")
    (clear	      (--) "Clear the contents of the assembler buffer.")
    (mark             (--) "Mark the dictionary.")
    (empty            (--) "Revert dictionary from last '~a'." mark)
    (scrap 	      (--) "Compile project + boot loader from scratch.")
    

    (ping             (--) "Request and print target identification.")
    (cold	      (--) "Perform PIC cold reset.")
    
    (p           (byte --) "Print byte in decimal. See also '~a'." px)
    (px          (byte --) "Print byte in hexadecimal. See also '~a'." p)

    (ts               (--) "Print stack in unsigned bytes. See also '~a' and '~a'." tss tsx)
    (tss              (--) "Print stack in signed bytes. See also '~a' and '~a'." ts tsx)
    (tsx              (--) "Print stack in hexadecimal bytes. See also '~a' and '~a'." ts tss)

    (<word>           (... -- ...) "Run a target word and wait until it returns.")
    (start <word>     (... -- ...) "Start a target program, do not wait ontil it returns.")
    (<number>         (-- n)       "Push a literal number on the target stack."))

  (documentation (doc stack)
    (dup              (a -- a a)    "Duplicate number.")
    (drop             (a --)        "Discard number.")

    )
  (documentation (doc math)
    
    (+                (a b -- s)    "Add two numbers.")
    (++               (a b -- s)    "Add two numbers and carry.")
    (-                (a b -- d)    "Subtract two numbers.")
    (--               (a b -- d)    "Subtract two numbers with borrow.")
    (and              (a b -- c)    "Perform logical AND.")
    (or               (a b -- c)    "Perform logical OR.")
    (xor              (a b -- c)    "Perform logical XOR.")
    
    
    (<<               (a -- b)      "Shift left 1 bit.")
    (>>               (a -- b)      "Shift right 1 bit.")
    (rot<<            (a -- b)      "Rotate left 1 bit.")
    (rot>>            (a -- b)      "Rotate right 1 bit.")

    (rot<<c           (a -- b)      "Rotate through carry flag left 1 bit.")
    (rot>>c           (a -- b)      "Rotate through carry flag right 1 bit.")
    (clc              (--)          "Clear carry flag to 0.")
    (stc              (--)          "Set carry flag to 1."))

  (documentation (doc memory)
    
    (!                (val addr --) "Store value in RAM address.")
    (@                (addr -- val) "Fetch value from RAM address.")
    (high             (addr bit --) "Set bit in RAM variable.")
    (low              (addr bit --) "Clear bit in RAM variable.")
    
    
    (+!               (val addr --) "Add to value in RAM address.")
    (-!               (val addr --) "Subtract from value in RAM address.")
    (and!             (val addr --) "Perform AND with value in RAM address.")
    (xor!             (val addr --) "Perform XOR with value in RAM address.")
    (or!              (val addr --) "Perform OR with value in RAM address.")

    (: <name>         (--)          "Enter a new word definition.")
    (";"              (--)          "Exit a word definition.")
    (variable <name>  (--)          "Create a 1 byte RAM variable.")
    (2variable <name> (--)          "Create a 2 byte RAM variable.")
    
    )

  (documentation (doc control)
  
    (for 	      (n --)        "Start counted loop.")
    (next             (--)          "Delimit counted loop.")

    (begin            (--)          "Start loop.")
    (again            (--)          "Restart from matching '~a'." begin)
    (until            (? --) 	    "If condition is false, restart from matching '~a'." begin)

    (not              (? -- ?)	    "Invert condition.")

    (if               (? --)        "Start conditional.")
    (else             (--)          "Start of alternative for conditional.")
    (then             (--)          "End conditional."))

  (documentation (doc predicates)

    (high?	( byte bit -- ? )   "Is the bit set?")
    (low?       ( byte bit -- ?	)   "Is the bit clear?")
    (=?         ( a b -- a b ? )    "Are 2 numbers equal?")
    (>?         ( a b -- a b ? )    "Is a larger than b?")
    (<?         ( a b -- a b ? )    "Is a smaller than b?")
    (>=?        ( a b -- a b ? )    "Is a greater than or equal to b?")
    (<=?        ( a b -- a b ? )    "I a less than or equal to b?")
    (z?	        ( -- ?)	     	    "Last operation returned zero. (Copy zero flag).")
    (c?	        ( -- ?)	     	    "Last operation carried over. (Copy carry flag).")

    (macro      (--)                "Switch to macro word definition mode. See '~a'." forth)
    (forth      (--)                "Switch to procedure word definition mode. See '~a'." macro)

    )
  )