The stack is the most important part of Josl. You would be wise to spend a lot of time reading through the stack reference material ensuring that you understand each word. Time spent with the stack will make you a stack guru, but without information even time cannot help.
The vast majority of your stack usage will be with these shallow words. There are deep words which can be enticing sometimes, but these shallow words perform little stack movement and therefore are fast and cheap. If you can do it with a shallow word, skip the deep words. If you require a deep word, rethink your word and try to factor it's requirement out. Only after that, proceed to the deep word.
Synopsis
depth ( -- i )
Description
Get the depth of the stack. The result given does not take into account the new depth value pushed onto the stack.
Example
> 1 1 depth
stack (3) 1 1 2
Synopsis
dup ( x1 -- x1 x1 )
Description
Duplicate TOS.
Example
> 1 dup
stack (2) 1 1
String note
Duplicating string values does not actually duplicate the string content. It only duplicates the pointer. Any time a change is made to the string, a new string will be created automatically.
Synopsis
2dup ( x1 x2 -- x1 x2 x1 x2 )
Description
Duplicate the top pair.
Example
> 1 2 2dup
stack (4) 1 2 1 2
Synopsis
drop (x -- )
Description
Drop TOS.
Example
> 1 2
stack (2) 1 2
> drop
stack (1) 1
Synopsis
2drop ( x1 x2 -- )
Description
Drop the top pair.
Example
> 1 2 3 4
stack (4) 1 2 3 4
> 2drop
stack (2) 1 2
Synopsis
pick ( ... i -- ... )
Description
Copy the stack item i over the TOS. Zero refers to TOS, One refers to NOS, etc...
Example
> 1 2 3 4
stack (4) 1 2 3 4
> 3 pick
stack (5) 1 2 3 4 1
Synopsis
nip ( x1 x2 -- x2 )
Description
Drop NOS leaving TOS intact.
Example
> 1 2 nip
stack (1) 2
Synopsis
tuck ( x1 x2 -- x2 x1 x2 )
Description
Copy TOS under NOS.
Example
> 1 2 tuck
stack (3) 2 1 2
Synopsis
over ( x1 x2 -- x1 x2 x1 )
Description
Copy NOS over TOS
Example
> 1 2 over
stack (3) 1 2 1
Synopsis
2over ( x1 x2 x3 x4 -- x1 x2 x3 x4 x1 x2 )
Description
Copy the NOS pair over the TOS pair.
Example
> 1 2 3 4 2over
stack (6) 1 2 3 4 1 2
Synopsis
rot ( x1 x2 x3 -- x2 x3 x1 )
Description
Rotate the top three stack items backward.
Example
> 1 2 3 rot
stack (3) 2 3 1
Understanding rot, -rot and roll
Looking at the stack diagram, keep your eye on x2. When you rotate the stack backward, x2 moves backward one. x3 also moves backward. x1, which was the first of the three now wraps around and becomes the first of the 3 item list just rotated.
Perform rot in the interactive mode and apply it a few times keeping your eye on your x2 value. Once you understand rot other words such as -rot, 2rot and roll variants will be a snap.
Synopsis
-rot ( x1 x2 x3 -- x3 x1 x2 )
Description
Rotate the top three stack items forward.
Example
> 1 2 3 -rot
stack (3) 3 1 2
Synopsis
2rot ( x1 x2 x3 x4 x5 x6 -- x3 x4 x5 x6 x1 x2 )
Description
Rotate the top three pairs backward.
Example
> 1 2 3 4 5 6 2rot
stack (6) 3 4 5 6 1 2
Synopsis
-2rot ( x1 x2 x3 x4 x5 x6 -- x5 x6 x1 x2 x3 x4 )
Description
Rotate the top three pairs forward.
Example
> 1 2 3 4 5 6 -2rot
stack (6) 5 6 1 2 3 4
