From d1cee77ae93afa7bf6b6263933c9199e226530ef Mon Sep 17 00:00:00 2001
From: kitty <nepeta@canaglie.net>
Date: Wed, 18 Mar 2026 16:23:26 +1100
Subject: stack operators

---
 readme.md   | 31 ++++++++++++++++++++++++++++
 sanctuary.s | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+)

diff --git a/readme.md b/readme.md
index a4aaad5..3b3edfb 100644
--- a/readme.md
+++ b/readme.md
@@ -38,6 +38,10 @@ start compilation of the word 'name'.
 ### `;   ( -- ) IMMEDIATE`
 end compilation of the currently compiling word.
 
+### `-rot   ( u1 u2 u3 -- u3 u1 u2 )`
+rotate the three topmost values on the stack so that the topmost value
+is moved to the third highest.
+
 ### `>body   ( xt -- a )`
 yield the code field of xt.
 
@@ -45,6 +49,15 @@ yield the code field of xt.
 variable containing the index of the first unparsed character
 in the input buffer.
 
+### `>r   ( u -- ) ( R: -- u )`
+move a value from the working stack to the return stack.
+
+### `2drop  ( u1 u2 -- )`
+remove the two topmost values from the stack.
+
+### `2dup   ( u1 u2 -- u1 u2 u1 u2 )`
+duplicate the two topmost values on the stack.
+
 ### `brk@   ( -- a )`
 yields current program break.
 
@@ -60,6 +73,9 @@ a variable that contains the first byte of user memory.
 ### `dp$   ( -- )`
 a variable that contains the last available byte of user memory.
 
+### `drop   ( u -- )`
+remove the value at the top of the stack.
+
 ### `dup   ( u -- u u )`
 duplicate the value at the top of the stack.
 
@@ -110,6 +126,15 @@ and return as a string.
 tabs (ascii 0x09), newlines (ascii 0x10), and spaces (ascii 0x20)
 are considered whitespace.
 
+### `r>   ( -- u ) ( R: u -- )`
+move a value from the return stack to the working stack.
+
+### `rdrop   ( R: u -- )`
+remove the value at the top of the return stack.
+
+### `rot   ( u1 u2 u3 -- u2 u3 u1 )`
+rotate the top three values on the stack so that the third highest value is moved to the top.
+
 ### `smudge   ( -- )`
 toggles the smudge bit on the xt in latest.
 
@@ -118,6 +143,9 @@ a variable containing a boolean value.
 if 0 (false), the system is in interpreting mode,
 if -1 (true), the system is in compiling mode.
 
+### `swap  ( u1 u2 -- u2 u1 )`
+swap the two topmost values on the stack.
+
 ### `syscall0   ( rax -- u )`
 perform the syscall with the id in `rax`,
 and push the value of the `rax` register to the stack.
@@ -143,6 +171,9 @@ a variable containing the address of the current input buffer.
 ### `type   ( a u -- )`
 write u characters at a to output.
 
+### `over   ( u1 u2 -- u1 u2 u1 )`
+copy the second-highest value on the stack and move it to the top of the stack.
+
 ## dictionary format
 
 note that the string length of one byte limits a word's name to 255 characters.
diff --git a/sanctuary.s b/sanctuary.s
index 89db85f..f1a7047 100644
--- a/sanctuary.s
+++ b/sanctuary.s
@@ -588,6 +588,73 @@ defcode "dup", dup, 0
 	mov r11, [r15]
 	pspush r11
 	ret
+
+defcode "2dup", twodup, 0
+	mov r11, [r15]
+	mov r12, [r15+8]
+	pspush r12
+	pspush r11
+	ret
+
+defcode "swap", swap, 0
+	pspop r11
+	pspop r12
+
+	pspush r11
+	pspush r12
+	ret
+
+defcode "over", over, 0
+	mov r11, [r15+8]
+	pspush r11
+	ret
+
+defcode "rot", rot, 0
+	pspop r11
+	pspop r12
+	pspop r13
+	pspush r12
+	pspush r11
+	pspush r13
+	ret
+
+defcode "-rot", dash_rot, 0
+	pspop r11
+	pspop r12
+	pspop r13
+	pspush r11
+	pspush r13
+	pspush r12
+	ret
+
+defcode "r>", from_r, 0
+	pop r12 ; keep return address
+	pop r11
+	pspush r11
+	push r12
+	ret
+
+defcode ">r", to_r, 0
+	pop r12 ; ret addr
+	pspop r11
+	push r11
+	push r12
+	ret
+
+defcode "drop", drop, 0
+	pspop r11
+	ret
+
+defcode "2drop", twodrop, 0
+	pspop r11
+	pspop r11
+	ret
+
+defcode "rdrop", rdrop, 0
+	pop r12 ; ret addr
+	pop r11
+	push r12
+	ret
 ; }}}
 
 ; math + comparison {{{
-- 
cgit v1.2.3