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 ;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 ;molecule merlin! , |
You can also clear the entire stack using
, ;destroy ;molecule , |
Often you will need to view the last atom on the stack, that can be done with
, 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 , |
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 , |
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.
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
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
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 , ;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
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.