This is an old revision of the document!
CRPL (Creeper Reverse Polish Language) is a stack-based, Reverse Polish Notation language. There, now that we've said it, what does it mean?
CRPL 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 CRPL and stack-based programming.
Each CRPL instruction (term) uses one or more arguments that are on a “stack”. The most recent argument on the stack will be used first. This is called LIFO (Last In, First Out). In return, the instruction may also place new arguments on the stack as part of its output. These new arguments are first in line to be consumed by the next instruction to be executed.
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
Both 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:
Adding comments makes code easier to understand, and sometimes helps the programmer or another reader 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 CRPL 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
Every CRPL operand takes zero or more arguments from a “stack”, pushes zero or more operands onto the “stack, or does both. In order to diagram the number of arguments consumed or produced, the following notation is included in every description following:
For instance, the instruction to add two numbers are:
4 5 add
Stack notation to represent this will be:
4 5 -- 9
In general, if we do not know the exact values of the arguments, an indicator of the argument would be given. Thus if we know the add command takes two input arguments and produces one output argument, then we notate it like this
n1 n2 -- n3
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.
The following convention is followed to represent items on the stack notation
|b||Boolean ; nominally a 1 or a zero, representing True or False|
|i||Integer ; an integer. The CRPL run-time will, if possible, convert the argument to an integer.|
|n||Term ; a generic argument. Any term that will be accepted by the instruction. If possible, the CRPL run-time will attempt conversion between types.|
|f||Float ; a floating point value. If possible, the CRPL run-time will attempt conversion between types.|
|x, y||Coordinate ; an integer that represents a valid X- or Y-coordinate on the map.|
|L||List ; a list is capable of storing multiple values in an orderly system.|
|s||String ; a string of one or more text characters. If possible, numeric values will be converted at run-time.|
An extra and optional operator to CRPL allows for a reversed order that you write some things in CRPL. It doesn't change a thing about the stack, or how CRPL works. It only gives you a syntax alternative that can make things easier to read in some cases.
This operator is 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. So stack notation for “add” is:
n1 n2 -- n3
This means two items on the stack before the operation, and one item on the stack afterwards. This is all CRPL (or RPL, or forth…) standard stuff and the primary principle of the language. This remains unchanged and untouched.
Take a second example:
CurrentCoords GetCreeper 1 gt if "Creeper Greater than 1" Trace endif
This looks at the current coordinates, gets the creeper there, checks if it is greater than 1. If so, trace the string “Creeper Greater than 1” 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” call 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 next statement, or jumps to the “endif”.
Again, CRPL 101.
Now, introducing the Warp operator.
3 4 add
add (3 4)
The open parenthesis ”(“ means to warp the previous command to the closing parenthesis ”)“ during compilation. There is no run time penalty for doing this since it is just a syntax trick. The compiler literally 'warps' “add” from before the 3 to after the 4 when this example is compiled.
This also means the same thing:
Here, the “add” warps from before the 4 to after the 4, resulting in “3 4 add” which is the exact same thing as the first example.
Take the second example. It now can become:
if ( GetCreeper(CurrentCoords) gt (1) ) Trace ("Creeper Greater than 1") endif
Notice that spaces before or after a warp operator ( which are parentheses) 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.
This means to assign 7 to the variable “x”. Or “seven goes into x”. So does this:
Like any language, you can write some really obfuscated code if you try (http://www.ioccc.org/years.html).
For instance take this clean piece of code:
CurrentCoords GetCreeper 1 gt if CurrentCoords -10 SetCreeper endif
Here it is in bizarro form:
Here's the same code with just one oddball warp:
endif ( if (GetCreeper(CurrentCoords) gt (1)) SetCreeper(CurrentCoords -10) )
Note: This has not yet been implemented. We intend to, but until then the following is merely a placeholder.
The following typographical conventions are used in this reference document:
|Normal text||Used in most instances.|
|Instruction||Refers to a CRPL language element or instruction.|
|Argument||Refers to a an argument required for a CRPL instruction.|
|User||Refers text that should be replaces with user-supplied values.|
Any text editor can be used to edit CRPL files. However, syntax highlight and auto completion support files are provided for several available editors.
Notepad++ can be obtained from here: http://notepad-plus-plus.org/
autoCompletionsubdirectory of the Notepad++ install folder. (In older versions, Notepad++ v7.6.1 and earlier, you had to put the file in the
plugins\APIssubdirectory of the intstall folder.) Then, restart Notepad++. Next, go to the Settings/Preferences menu in Notepad++. Click the “Backup/Auto-Completion” tab. Check the “Enable auto-completion on each input” checkbox, and make sure the “Function completion” radio button is selected.
https://knucklecracker.com/wiki/doku.php?id=crpl:docs:$(CURRENT_WORD)into the input field and click “Save”. After that, select a name (for example “Open CRPL Wiki”) and a keyboard shortcut (for example Ctrl+Shift+H) and click OK, then just close the Run… dialog. After that, you should see your shortcut in the “Run” menu, and you can use it to open the current command (the one that your input cursor is currently on) in the wiki.
Visual Studio Code can be obtained from here: https://code.visualstudio.com/.
Sublime Text can be obtained from here: https://www.sublimetext.com/3.
Features include syntax highlighting and auto completion.
Time permitting, this deserves a more complete treatment and probably a section of it's own.
Dokuwiki uses GeSHi syntax highlighting.