xRPL ¹⁾ is a stack-based, Reverse Polish Notation language. There, now that we've said it, what does it mean?

xRPL programming is similar to programming a HP calculator or Forth language programming. If this is not something you have done, read on for a brief introduction to xRPL and stack-based programming. For a more detailed CRPL explanation, see the CRPL Tutorial.

An xRPL instruction either use arguments (data) that is on a “stack”, or place arguments on the “stack”. Arguments on the stack are in LIFO (Last In, First Out) order. That means the argument taht was placed on the stack last will be the first to be retrieved. Imagine this as a stack of coins. If you put a coin on the top, then the first coin to be taken off will also be the one that was last placed on the stack.

You can place arguments on the stack by typing them, or executing an instruction that will push arguments on to the stack. For instance, you can type

2 4 5

and then these three numbers will be pushed onto the stack when your script executes.

As an illustration, imagine you want to add two of the numbers you entered above. The instruction to perform addition is add. Either of these mini scripts will now perform the addition:

• 2 4 5 add

• 2 4 5
  add

Either of the scripts above will read the two most recent arguments on the stack (4 and 5), add them and push the sum on to the stack. After the instruction has completed, there will be two numbers on the stack. The “2” from your original entry, and “9” - the sum of the two arguments added by the “add” instruction. The stack would now look like this:

2 9

You can find more commands and detailed explanations of them in the CRPL Reference!

Adding comments makes code easier to understand, and sometimes helps the programmer or other readers to grasp complex pieces of logic. Also, after some time interval, it refreshes one's memory about exactly what a certain piece of code was intended to do.

Comments in xRPL can be either a whole line or a partial line. The comment terminates when a line ends.

Comments are indicated by the “hash” character (#),

# This is how we add two of the three numbers
# that are on the stack
# Below is code         #  Below is a comment
2 4 5  add              # adds 4 and 5 to get 9

Note: Unless explicitly noted otherwise, all instructions are destructive stack operations in that they will remove as many arguments as is required for their execution from the stack and replace those with the output from their execution. In the example above, the original two items on the stack have been replaced by their sum.

Likewise, note that the most recent item pushed on to the stack will also be the first item to be removed. This is referred to as LIFO (Last In, First Out) processing.

An extra and optional operator ²⁾ change how you can choose to write the syntax. It doesn't change anything about the stack, or how xRPL works. It only gives you a syntax alternative that can make things easier to read in some cases.

This operator is called the warp operator since it warps things around. In more technical terms, it allows for prefix notation. Take the following example:

3 4 add 

This means to push 3 to the stack, push 4 to the stack, then to call add. Add pops two items from the stack, adds them together, then pushes the result back.

This means two items on the stack before the operation, and one item on the stack afterwards. This is all xRPL (or RPL, or Forth…) standard stuff and the primary principle of the language. It remains unchanged and untouched.

Introducing the Warp operator.

3 4 add

can become

add (3 4)

The open parenthesis ( means to warp the all arguments between it and the closing parenthesis ) to before the command during compilation. This is merely a syntax trick to improve readability of some code and has no run-time penalty. It is resolved during compilation, when the compiler literally warps the 3 and 4 from inside the parenthesis to the front of the add operation when the code is compiled.

Here the warp operator is used to make the code slightly more readable.

3 add(4)

Here, the 4to the front of the add, resulting in 3 4 add which is the exact same thing as the first example.

Take a second example:

# CurrentCoords obtains the (X, y) location and places it on the stack
# GetCreeper uses the (X,Y) coordinates to  look at a cell on a map
#   and returns the amount of creeper on that cell
# The "IF" statement then evaluates for a value greater than one (In 
#  other words, creeper exists in a significant amount) and if true
#  displays a message in the trace output.
 
CurrentCoords GetCreeper 1 gt if
   "Creeper exists here" Trace
endif

The comments in the sample above explains what we're trying to achieve with this code snippet.

It uses the current coordinates, to get the creeper at that coordinate location, then checks if it is greater than 1. If so, it writes the string “Creeper exists here” to the trace log.

Because of the way the stack works, you have to push two coordinates to the stack first (CurrentCoords does that), then call GetCreeper. That takes two items from the stack, uses them as coordinates, then pushes the value of the creeper at that map location back to the stack. The number 1 is then pushed to the stack, and the gt operator takes two items from the stack and does a “greater than” comparison between them. The result is either 0 (false) or 1 (true) and that is pushed back to the stack. Finally, the if statement pops the result of the gt call from the stack and then either allows execution to pass to the Trace statement, or jumps to the endif.

That's xRPL in a nutshell.

Using warp notation, we can make this slightly more readable.

# CurrentCoords obtains the (X, y) location and places it on the stack
# GetCreeper uses the (X,Y) coordinates to  look at a cell on a map
#   and returns the amount of creeper on that cell
# The "IF" statement then evaluates for a value greater than one (In 
#  other words, creeper exists in a significant amount) and if true
#  displays a message in the trace output.
 
if ( GetCreeper(CurrentCoords)  gt (1) )
   Trace ("Creeper exists here")
endif

Notice that spaces before or after a warp operator ( and ) don't matter. You can put spaces, or you can bump the warp operator up right next to something else.

Note also that this syntax is totally optional and can be intermixed with standard RPL notation as seems appropriate. For instance, assignments still look better without warping.

7 ->x
->x(7)

Both the above statements assign 7 to the variable “x”. Choose which format you prefer and you think makes your code most readable - then be consistent. :)

Many arithmetic operators can be substituted with shorthand symbols (4RPL only).

https://github.com/Arin112}Arin112 wrote a code translator that can translate in-fix ³⁾ code to the xRPL post-fix notation.

For those struggling to master xRPL's post-fix format, this may be a useful tool. It can be obtained from github and is accompanied by many samples. Of course, it should be noted that the code and translation will only be up-to-date as long as the repository is maintained.

Here are some sample translations, taken directly from the GitHub repository:

x = 2 + 2 * 2;

2 2 2 mul add ->x

z = f(x, y);

z = f(x, y);

[x, y] = CurrentCoords();

CurrentCoords ->y ->x

if(a<b && (c+1 == -c)) [a, b, c] = 1, 2.0, 3.14;

<-a <-b lt <-c 1 add <-c neg eq and if
1 2 3.140000 ->c ->b ->a
endif

do (1 .. 42){
a = refRead("num");
refWrite(7*(3.14+i), "num");
}

42 1 do
"num" <-! ->a
7 3.140000 i add mul "num" ->!
loop