Note: to view the code examples on this page correctly you need a Unicode font including APL characters (i.e. APL385 Unicode) and a Unicode enabled browser.
Once you have downloaded Rowan and installed the font, start Rowan by running Rowan.exe; you'll be met by the session (shown here with the avg function already defined):
The large edit field is where you type expressions that you want Rowan to run. You can try a few things, but at this stage most things you type will probably produce an error! You can copy-and-paste expressions out of this tutorial, although sooner or later you're going to have to type your own code! The treeview displays the objects defined in the current session (your workspace is just the space in which you work), and different types of function have different icons, as you will see as we continue.
Let's start by entering those things in the screen snap, and finding out what they mean. It's probably a good idea to open the Rowan function reference (ref.htm), which tells you about all the functions, operators etc in Rowan and what keys to press to produce them. You can also switch to the Symbols tab which lets you select the characters with the mouse, as well as telling you the keyboard shortcuts when you hover over the buttons.
Type ⍳10 at the session. To type the ⍳, press AltGr+I; the special characters Rowan uses are available by Right-Alt (AltGr in Europe) or AltGr+Shift and a key, which often relates to the symbol (here, Iota is a Greek 'i'). This result ((1 2 3 4 5 6 7 8 9 10)) is easy enough to understand: Iota produces the list of integers from one to n.
The next line – avg←{(+/⍵)÷⍴⍵} – defines a function, avg, which returns the arithmetic mean of its argument. For the special characters here, ← is AltGr+[, ⍵ is AltGr+W, ÷ is AltGr+D (for divide) and ⍴ is AltGr+R. You can see that a function is given by a block of code in curly brackets – similar to JavaScript, C# etc – and assignment is done with the left arrow, ←. We'll worry about exactly how that function works in a second, although if you look up all those symbols in the Reference you might be able to understand it now. The important thing is that now the function avg is defined (you can see it in the treeview) and you can use it like functions Rowan gives you. Call it with avg (2 3 6), or any other set of numbers, and see how it gives you the average.
The most used functions in any language are the arithmetic functions. In Rowan these are +, -, × (AltGr+T, for Times) and ÷ (AltGr+D, for Divide); there are also the less-often used % for modulo, * for power and ⍟ (AltGr+8) for log.
To enter numbers, you can use a variety of formats: 23, 0xFF, 2.4 and 1.4e-3. (Some of these are integer and some floating-point, but usually within Rowan it doesn't matter.) You can even type an infinity ∞ (AltGr+Shift+8)! Try various arithmetic operations to get used to the symbols if you're used to ASCII programming languages, although being the standard mathematical symbols it shouldn't take long. See how Rowan can manipulate vectors (use brackets – parentheses or square brackets – to specify a vector) as easily as single numbers (scalars): for example, try
3+(2 7 12 1.6)
Result: (5 10 15 4.6 )
(2 3 4)*(3 3 2)
Result: (8 27 16 )OK, let's go through the function we defined earlier. Just to remind you, we defined avg as {(+/⍵)÷⍴⍵}. Within the curly braces, ⍵ refers to the right (and, in this function, only) argument. Rowan works from right to left, although you can usually 'see' how a function works either way around. In this case, the average function divides the sum of the argument (+/⍵) by its length (⍴⍵). You can read +/ as a diglyph meaning 'sum', although the documentation for reduce will tell you what is actually going on.
Notice how you didn't have to tell avg to return its result, but instead the value was automatically returned.
Let's have a look at a longer example function now. Enter #run "File", which will run the script file 'File.rws', which defines one function called LoadFile. LoadFile should appear in the treeview below avg; double-click it to bring up the function editor.
We'll work through this function and see how Rowan can communicate with the .Net Framework. Before we start, notice how each statement ends with a semicolon. If you forget a semicolon you can get some confusing errors, as the newline doesn't mean anything so the two lines would be run together!
// to comment out the rest of a line; you can also use the Comment character ⍝ (AltGr+#).
#try block. If you're familiar with modern languages (C#, Java, JavaScript) you'll know how this works already. The code within the #try section is run, and if an exception of type System.IO.FileNotFoundException is thrown (an error occurs) the section after #catch is run. After that, whether the error happened or not, the part labelled #finally is run (this is slightly different from C#).
sr←$IO.File:OpenText(⍵);res.
#while loop goes through, reading lines from the file until there are no more. thisline←sr:ReadLine(); assigns the next line to the local variable thisline, the #if clause leaves the #while if thisline is null, and if not the #else clause appends the line to res.
#catch block, which is run if the file could not be opened or some other IO error occured, simply displays an error message. Note how + can be used to append strings, as in C# or JavaScript.
sr:Close() makes sure the file is released.
←res forces the function to return the array stored in res.
Try the function on some files: try LoadFile "Rowan/docs/index.html", for example. You'll see how the result is an array of strings, one string for each line in the file.
You can see how, even though LoadFile defines several variables (sr, res and thisline), they don't appear in the treeview, whereas if you type a←(2 4 6 7) at the session you will see a there. This is because they are local assignments, so they disappear once the function finishes. To assign globally (from within a function or, later on when you're saving your work, a script), you can use the Global Assign function ⍅ (AltGr+Shift+[).
The information on this site is based on this article which appeared in the Spring 2005 edition of Vector.