Once installed, Merlin can be invoked in your shell of choice by simply typing merlin and hitting return.
You should then be greeted by a comma and blinking cursor. Something like:
$ merlin
, |
First, we can start out by typing some text and hitting enter.
, hello, merlin!
, |
Now, what exactly did this do? Well, Merlin will automatically start in its atom mode, so in this case typing hello, merlin! will first add hello, and then merlin! to the stack. The stack, in Merlin, is a global list of data, or pieces of text, called atoms. To view the stack, we can use the molecule command like so:
, ;molecule
hello, merlin!
, |
Take note that commands in Merlin are prefixed with a semicolon, to distinguish them from atoms. If you would like to add an atom beginning with a semicolon to the stack, you can prefix it with a backslash (\).
Now, what if we would like to switch the order of these two atoms? We can use the orbit command.
, ;orbit ;molecule
merlin! hello,
, |
There we go! Now the order of the two atoms have been reversed. Again, take note that just like you can add two atoms to the stack on the same line, you can also run two commands.
Of course if you can add atoms, you must also be able to remove them. You can do so with the decay command.
, ;decay ;molecule
merlin!
, |
You can also clear the entire stack using destroy:
, ;destroy ;molecule
, |
Often you will need to view the last atom on the stack, that can be done with pen.
, hello world
, ;pen
world, |
Well would you look at that, pen doesn't append a newline! If you would like to use a newline anywhere in Merlin, you can use new. Although it is formatted like a command, all it really does is add a newline to the stack. Think of it being like \n in C derived programming languages.
So, if we wanted to print the last atom on the stack, followed by a newline we could do something like:
, ;pen ;new ;pen ;decay
world
, |
The decay is necessary for removing the newline we added to the stack.
Another action that you will find is very commonly needed in Merlin is joining and splitting atoms on the stack. You can use the tether command to join all of the atoms by another atom.
, ;new ;tether
, ;pen ;new ;pen ;decay
hello
world
, |
Essentially, tether will take the last atom, intersplicing it between all of the previous atoms, creating a new atom.
fray works in a similar way. It takes the second to last atom and splits it into different atoms, using the last atom as the delimiter.
, ;new ;fray
, ;molecule
hello world
, |
Finally, you can use the atoms command to get the number of atoms in the stack. This is useful for when you are dealing with empty ("") atoms.
Now you have learned all of the ways you can manipulate the stack in Merlin! But still, many of these actions can be clunky to type out each time, that's where the nomen (short for nomenclature) command comes in.
The nomen command captures all of the atoms in the stack, creating a new command, named by whatever the last atom of the stack was. Calling the "nomen" will "expand" to whatever the stack was when you defined it.
If you wanted to create a nomen, dispn, to print the most recent item, appending a newline, and then removing the item from the stack, you would do:
, \;pen \;decay disp ;nomen
, \;disp ;new \;disp dispn ;nomen
, |
The first line defines the disp nomen to print the last item in a stack and then remove it. Notice that the commands are prefixed with a '\' in order to escape the commands' leading semicolons.
The second line defines dispn. It calls our disp nomen by itself (therefore on the last item on the stack), and then on a newline
This means that calling Hello! ;dispn would "expand" to:
Hello! ;disp ;new ;disp
And then:
Hello! ;pen ;decay ;new ;pen ;decay
Not only can you create nomens, but also delete and "clear" them. The disenchant command will take the name of a nomen and set it to do nothing. The nomen must be already be in memory. The smash command will completely delete the nomen.
The difference between the two commands is illustrated below:
, Hello! quark ;nomen
, ;quark
, ;molecule
Hello!
, quark ;disenchant
, ;quark
, ;molecule
Hello!
, quark ;smash
, ;quark
merlin: unknown command
, |
Now that you know everything there is to know about stack manipulation and nomens in merlin, you can begin to learn about merlin's different modes
As mentioned before, merlin defaults to being in the atom mode. In this mode each space-separated "atom" is parsed by itself, whether it be a string or a command.
This differs from merlin's scribe mode (entered by simply using the scribe command) in which each line is parsed in it's whole.
This means that entering hello, world will add the string in its entirety to the stack, not breaking it up into pieces like atom would.
This concept is exemplified by the following example:
, ;scribe
Hello, World!
;dispn
Hello, World
;atom
, |
Notice that typing ;atom executes the atom command and returns us to the atom mode
It would also be a good time to mention that the adieu command can be used to exit merlin at any time.
Merlin, like most text editors, support multiple buffers (called volumes) for storing the text you are manipulating. You can create a new buffer with the genesis command:
, ;genesis
, ;volume ;dispn ;volumes ;dispn
1
1
, |
We can use the volume command to return the index of our current buffer, and volumes to return the total number of buffers open.
Volumes are indexed in the order in which they are created, you can go to volume n by typing n ;focus.
Similarly, you can use the shelve command to close volumes.
Finally, you can do filename ;dub to name your buffer, and then ;carve to write it.