# This is a comment
1 2 3 pop swap  # This is another comment

# How stack diagrams are used:
rt multi_dup
  # [N, X]
  # X = Item to duplicate
  # N = How many times to duplicate X
  
  while
    # [N, X]
    swap dup   # [X, X, N]
    1 3 rroll  # [N, X, X]
    1 swap -   # [N-1, X, X]
  end
  # [N(0), X, ...]
  pop  # [X, ...]
end

# General commands
pop         # Drop the topmost element from the stack     [a] -> []
dup         # Duplicate the topmost item of the stack     [a] -> [a, a]
swap        # Swap the two topmost items of the stack     [a, b] -> [b, a]
over        # Duplicate the 2nd topmost item to the top   [a, b] -> [b, a, b]
lroll       # Roll X items N times to the left            [X(3), N(1), a, b, c] -> [b, c, a]
rroll       # Roll X items N times to the right           [X(3), N(1), a, b, c] -> [c, a, b]
end         # End the code block / Only used in routines, ifs and loops

# Comparison commands
# Peeks two values and pushes result (either 1 or 0 (true or false))
eq         # True if topmost two items are equal          [a, b] -> [a==b, a, b]
neq        # True if topmost two items are not equal      [a, b] -> [a!=b, a, b]
gt         # True if topmost item > 2nd topmost item      [a, b] -> [a>b, a, b]
gte        # True if topmost item >= 2nd topmost item     [a, b] -> [a>=b, a, b]
lt         # True if topmost item < 2nd topmost item      [a, b] -> [a<b, a, b]
lte        # True if topmost item <= 2nd topmost item     [a, b] -> [a<=b, a, b]

# Arithmetic / bitwise commands
# Remember: Top of the stack in stack diagrams is left
+           # Pop top two items and push sum              [a, b] -> [a+b]
-           # Pop top two items and push difference       [a, b] -> [a-b]
*           # Pop top two items and push product          [a, b] -> [a*b]
/           # Pop top two items and push quotient         [a, b] -> [a/b]
&           # Pop top two items and push ANDed result     [a, b] -> [a&b] 
|           # Pop top two items and push ORed result      [a, b] -> [a|b] 
^           # Pop top two items and push XORed result     [a, b] -> [a^b] 
~           # Pop top item and push flipped result        [a] -> [~a]


3 5 -   # 5 - 3
1 8 +   # 8 + 1
4 3 ^   # 3 ^ 4

123         # [] -> [123]
-123        # [] -> [-123]
"abc"       # Len + chars as bytes / [] -> [3, 99, 98, 97]
            # Strings are naturally reversed due to the stack

# ------ Imports ------
# Import statements have to be placed at the beginning of the script
import "stdlib/io/std"
# You can assign custom names to imported scripts
import "stdlib/math/ints" as custom_import_name
# You can call the declared global routines of the imported scripts
"Hi" :std.println_out               # -> import "stdlib/io/std"
123 :custom_import_name.int_to_str  # -> import "stdlib/math/ints" as custom_import_name

# ------ Routines ------
# Declaring a routine called my_routine
# Routines whose name starts with an underscore are internal and can not be called by
# other scripts
rt my_routine
  # Insert routine code here
end
.my_routine  # Calling my_routine

# ------ If ------
# if will pop the top stack value and check if it is greater than zero
if
  # Code
else if
  # Else if code
else
  # Else code
end

# ------ Loops ------
# while (peek_top_stack_item() != 0)
while
  # Code
end
# while (peek_top_stack_item() == 0)
until
  # Code
end

native_stack_debug      # Print the stack contents to stdout    [] -> []
native_open             # Open a file                           [FLAGS, PATH] -> [FD]
native_write            # Write data to file descriptor         [FD, DATA] -> [RES]
native_read             # Read data from file descriptor        [FD, AMT] -> [RES]
native_close            # Close an opened file descriptor       [FD] -> [RES]
native_time             # Get current time in seconds           [] -> [TIME]