-
Notifications
You must be signed in to change notification settings - Fork 4
Short Seco Tutorial
In this tutorial we will guide through your first steps with Seco. Seco is about scripting, which could be defined as efficient programming in the small. It used to be called Scriba but somebody threatened to sue us for a trademark infringement.
If you prefer watching video demos, the roughly equivalent material can be found in video form at: http://www.kobrix.com/secovideos.jsp. They are a bit old and the first one points to the now defunct Google Code for the tarball, but surely that won't confuse you too much. And if you absorb faster and better by skimming through a tutorial, then let's go...
First, make sure you have installed and can start Seco: Installing and Starting Seco
There is this commercial piece of software for doing mathematics, created back in the 80s and slowly but surely growing and acquiring popularity until today it's reached a point where it claims to "compute" the world's knowledge, in its entire totality. It's called Mathematica and besides a nice term-rewrite language for symbolic processing, typesetting and rich library of algorithms for doing maths, it has this GUI interface for interacting with an interpreted language in the form of a structured document. The structure amounts to having basic cells of several different types (input, output, text, ...) and being able to group them arbitrarily deep.
This turns out to be a rather neat way when you are developing scripts. The cell being the basic unit of the notebook, it allows you to operate on logical chunks of your code, like move them around, evaluate them in bulk or lock them as read-only for example. Grouping cells or grouping groups is just an extension of that concept and it also helps in managing the visual space because you can collapse and expand them depending on what you want to see.
The cell types are essentially three: input, output and documentation cells. Seco actually doesn't distinguish those types much, what matters is the content of the cell. If it's a script, you can evaluate it. If it's HTML, it will do its best using Java Swing to show the HTML nicely. If it's a Swing component, it will actually embed it as an interactive component inside the notebook.
So you have this rich document that's kind of like a program, kind of like a document, kind of like a REPL (read-eval-print loop) with a history. The notebook itself is just a cell group with a name. It gets stored in the niche database and you can look for it by name. You can also export it as an XML file and email it to your friends and co-workers. Or you can publish it as a blog entry for other programmers to read. So that's pretty much what notebooks are in essence. There is one sample notebook that comes with the Seco distribution, under SECO_HOME/examples there is SecoWelcome.nb. You can select the File->Import menu and import that notebook. You can read there some of same stuff I just told you, and some more, and you can evaluate a bunch of code cells see it works.
Say you have your notebook opened (if you don't, just do File-New to open one). You can just start writing code in there. A new input cell is automatically created and it is assumed that the language is the notebook default language. Initially that's going to be BeanShell, but you can change that. So to start with type some arithmetic expression (e.g. 42/7) and press the Shift-Enter keystroke combination - this will evaluate your input cell and create an output right beneath with the value 6.
An input cell contains script code of arbitrary length and complexity. Anything from a simple literal value, to a single function, to a complete program.
When a cell is evaluated, declared names in whatever scripting language you are using become part of the runtime context and remain so as long as Seco is running (or you overwrite them).
Speaking of scripting language, you can change from the BeanShell default to something else with simple keystroke: Ctrl-Space will popup a menu with the list of available languages to interpret your input. But that's just for that input cell, so you can have different cells using different languages, but all sharing the same global context (that's JSR 223 scripting). Another way to change the language is through the cell context menu (right-click within a cell to open it).
That blue bracket-looking thingy on the right hand side of the notebook is the cell visual handle. Those are not to be confused with HyperGraphDB handles (which are pointers). The notebook handles are called such because you can grab them with the mouse. Click on it to "grab the cell" and move it around. Right-click to get a context-menu. Note that the representation for a group and for a collapsed cell are slightly different, just as a visual cue.
And you can to other from that context menu such a grouping/ungrouping a bunch of cells (or cells groups) together. You can mark cell as an init cell or you can mark a whole cell group as an init group.
What does init mean? An init (initialization) cell or a group is evaluated upon opening the notebook. Notebooks, even minimized ones, are opened upon Seco startup. So this means if you have startup code, say a library of functions that you need, or an external script file that you need to load, or some cells that create Swing components that you need for daily work, you put them in an init group and you don't have to manually re-evaluate every time you start Seco.
Note that when you evaluate an input cell for the first time, the create output cell is forever linked to its input. Therefore, if you move it somewhere else, say somewhere on the canvas, or in another notebook, it will always be updated when you re-evaluate that same input cell. So a quick way to build some UI that you need to do some work, or to share with others, is to construct it piecemeal by evaluating cells, adjusting, looking at results etc. And once you are done, move the important output cells to the canvas where they will appear as standalone components. Then mark all the code that creates and initializes those components as an init group and you are good to go.
To change the look&feel of a notebook, use the Format->Visual Properties menu - change fonts, colors and background for various types of cells.
Some other things you can do if you explore those menus: change syntax formatting and coloring for your scripts, keyboard shortcuts, code templates.
Seco has this notion of a runtime context which allows you to have several execution environments, each with a different classpath and a different set of global variables, within the same JVM. Each runtime context gets its own Java class loader. You create runtime contexts by configuring them via the Runtime menu. There is always a default top context pre-configured. But if you have several projects you are working on at the same time, multiple contexts come in handy.
I mentioned global variables. The Java scripting standard, JSR 223, makes it possible for different scripting engine to cohabit and share the same set of global variables. That's exactly what happens in Seco. You have a set of globals and this is the main way you can share information between scripting engines. To see them, use the Tools->RuntimeContext Inspector menu. You can kind of get a clean slate and get rid of all the globals in one short with Tools->Clean Engine Context menu. But that won't re-initialize static variables in the classes. To really start clean with a given context without restarting the whole of Seco, you need to reboot a context. You do that from the Runtime->Manage Contexts dialog or by executing thisContext.reboot() in a notebook.
Now, the thisContext variable is clearly not something you've created yourself. There are a few globals like pre-populated by Seco. Other such variable is the niche for the HyperGraphDB instance where everything is stored, desktop for the top-level Java Swing JFrame, notebook for the current notebook (a CellGroup instance) and maybe others :)
If you've used the context menu of a notebook so far to change the default language, you probably noticed an option for runtime context. That's what it's about - you can set the runtime context of a notebook, but not individual cells within it.
Notebooks inside Seco are simply cell groups that have a name. They are persisted automatically, all the time. You don't have to save them. However, you can export them (menu Notebook->Export) as files on the file systems, for example for backup to share with colleagues. The format is an XML-based format, and the extension usually .nb, though it doesn't matter. Conversely, you don't actually "open" a notebook file, but rather you import a notebook into a Seco niche. The Notebook->Open menu is not going to open a file dialog box, but rather show you a list of notebooks in the backing database that are not currently open in the UI. By the way, since we've explained initialization cells, it is important to remember that:
All initialization cells and cell groups from all currently open notebooks will be evaluated upon Seco startup.
The notebooks that are in your niche, but not currently open won't be evaluated. And it's actually hard to delete a notebook - when you select a notebook Alt+left-click and then press the DEL key to delete it, it just removes it from the UI. But you can still re-open it from the open menu.