MiniRobotLanguage (MRL)
STJ. Command
STack Job
Intention
This Command is the universal Command to manage the User-Stack/Que.
• You can exchange stack items (SWAP).
• You can duplicate Items (DUPL).
• You can delete items (REMO)
• You can insert items anywhere in the stack (INSE)
Usage is like this:
' This command will swap Stack positions 0 and 2
STJ.SWAP|0|2
Now how does the Stack look before and after?
We assume that there are 10 Elements on the Stack, we'll just look at the first 4 Stack positions. This is the stack before the command.
Note: We will use this Stack as the start-stack for all of the following Stack-commands examples.
picture 1 - the starting stack before the stack-commands
Now we will swap elements 0 and 2 using the command:
STJ.SWAP|0|2
And then the stack looks like this:
You can see that the elements are exchanged.
Using the SWAP Command, you can exchange ANY of the Stack-Elements.
Also you can exchange multiple elements in just one command.
The parameters are always used in pairs. If one parameter is missing, the TOS is exchanged with it.
For example:
STJ.SWAP|1|2|3|4
Will result in this:
Now lets add just one parameter to exchange it with the TOS.
STJ.SWAP|1|2|3|4|4
This what we get:
You can exchange up to 20 Stack-elements in the same command!
All exchanges are done from left to right, one after the other.
Now lets duplicate a Stack element. The stack before the command is the same like in picture 1. In the first example we are going to DUPLicate the TOS (Top of Stack Element).
Because this is the most commonly used case. The command is:
STJ.DUPL|0
And the result is as expected:
Again you can use up to 20 parameters to duplicate many stack elements with just one command. We will jsut use three duplications here.
STJ.DUPLICATE|3|4|4
which will result in this:
Internally the duplicates are done in a way to avoid shifting effect.
Next let's INSERT something. The stack before the command is the same like in picture 1. In the first example we are going to INSErt something on the TOS (Top of Stack).
Because this is the most commonly used case. The command is:
STJ.INSERT|3|Hallo its me!
The result is as expected:
As always with STJ. you can add more parameters. Generally they are used in pairs of two. First the number, then the String. Objects will always be inserted as string elements currently. If you omit the second parameter, or if you leave it empty, an empty string will be inserted. Here is an example with just two elements:
STJ.INSERT|3|Hallo its me!|1|I am here!
The result is:
You can add more parameters, up to ten elements can be inserted with just one command. INSErts will not be processed in strict order from left to right.
They will be processed in a way that "Shifting effects" that will not occur.
An element that you want to have inserted at place 2 will be at place 2 when you dump the stack after the operation. Of course inserting multiple elements at the same place will always shift elements to another place. For example:
STJ.INSE|4|Me at place 4||4|Me too at place 4|2|Me at place 2
If this would be processed from "Left to right", we would have two inserts at place 4 and then we would insert an element at place 2. This would shift our previous place 4 element to place 5!
Therefore the INSERT command handles it internally different. The result of this command will be, as if you had done this:
STJ.INSE|2|Me at place 2|4|Me at place 4||4|Me too at place 4
As you can see below all INSERTS are made in a way that shifting effects are avoided, and that you get what you want.
Below you see the result.
If you got until here, the REMOve command may be already clear to you. Let us anyway take a look at some examples. As always we start with our stack like in picture 1. This is the easiest way. We remove just the TOS-element:
STJ.REMOVE|0
The result is as expected:
Now it gets more interesting. Imagine we would remove the elements just in this order:
STJ.REMOVE|0|2
Then internally after the removal of element 0 (TOS), the former element 2 would shift one up and be element 1. If we would go on to remove element 2, we would really remove element 3!
To avoid this, internally the elements are removed from highest to lowest NOT in the order you specify them in the command This avoids confusion through shifting effect.
Important: When the actual stack is switched to a Que, then the internal removal order is automatically reversed. This is true for the REMOVE as well as for the DUPLICATE command.
And here is the result as expected:
This way, its much easier for you to specify the right elements to be removed. You do not need to care for the right order of removal to avoid shifting effects.
Therefore if you write:
STJ.REMOVE|0|2|4
exactly the same will happen, as if you write:
STJ.REMOVE|4|2|0
because the elements are internally sorted, and removed in the right order that avoids "shifting effects". Still you can do something like this:
STJ.REMOVE|0|0|0
Which will just delete the first three elements from the Stack.
Important: it does not matter, if you write:
STJ.DUPL|0|1
or if you write
STJ.DUPLICATE|0|1
Therefore you can decide if you want to save a bit typing or if you prefer readability.
Syntax
STJ. P1|P2[..|PX]
Parameter Explanation
P1 - Stack-Command:
SWAP - Exchange given Elements
DUPL - Duplicate given Element(s)
REMO - Remove given Element(s)
INSE - Insert String/Variable into Stack-Position
P2 - VAR/NUM - depend on used Stack-Command
PX - VAR/NUM depend on used Stack-Command
Example
STS.GLOB
' Put 10 Items on global Stack
FOR.$$A01|1|10
VAR.$$B00=Stackplace $$A01
PUV.$$B00
NEX.
STS.DUMP
DBM.2
: $$B00=3
: $$B01=2
: $$B02=1
' Swap Items 3 with 2
STJ.SWAP|$$B00|$$B01
STS.DUMP
' Insert a 2 (=$$B01) below TOS and insert "Hallo" at Stack-Pos. 3
STJ.INSE|0|$$B01|$$B00|Hallo
STS.DUMP
' Remove Items 9,8 and 4 from Stack
STJ.REMO|9|8|4
STS.DUMP
' Duplicate Items 2 and 3
STJ.DUPL|$$B01|$$B00
STS.DUMP
DMP.
MBX.Ready
END.
Remarks
If you add multiple Parameters, they will not be processed strictly from left to right. Instead they will internally be reordered to avoid "Shifting effects".
Limitations:
-
See also:
• STV. - Stack To/from Variable
• PUS. - Push Parameter onto Stack/Que
• PUV. PUsh variables on the User-Stack
• POP. - POP Variable from Stack
• POV. - POp Variables from User-Stack