File Workbench

Squirrel is the default scripting language of FWB. It is a dynamically typed language with a syntax that is as simple as it gets:

@ function Add( a, b ) { @ @ return a+b @ @ }@

In the function above, a, b may be integers, floating point values, strings, vectors or something else. Regardless of type, Squirrel will do its best to add them together. Often it works, sometimes there is no addition operation that makes sense for the two types (leading to an exception).

Apart from integers, decimal values and strings, there are also arrays and tables:

@ my_array <- [1, 2, “Hello”, 3.14, [2,4,6] ] // Creating and assigning an array @ @ person1 <- { name=“George” age=47 } // …and a table @

The <- operator is the new slot operator, it creates a new named variable in a table.

To iterate an array or a table (or anything that is collection like), we do:

@ function PrintElems( c ) { @ @ println( “Elements in c:” ) @ @ foreach( key, val in c ) @ @ println( key + “=” + val ) @ @ }@

The syntax of Squirrel is close to C/Java, except that no type is given in variable declarations:

@function MakeSquares( n ) { @ @ local arr = [] @ @ for( local i = 1; i<n; i++ ) {@ @ local tmp = i*i @ @ arr.push(tmp) @ @ } @ @ return arr @ @} @

Tables

Squirrel has tables (associaive arrays) much in the same way as the Lua language. Tables can be used as namespaces:

@ Math <- { PI=3.14 @ @ Square = function(v){ return v*v } @ @ CircleArea = function®{ return PI * Square® } @ @ } @

If we the do println( Math.CircleArea(4) ) we get the result: 50.24.

The topmost (default) table is called the root table.

Table access always happens relative the current object (this). So in the function CircleArea above, Squirrel finds PI in the Math table. If there would be a PI object also in the root table, then the one in Math would still be found first, since we’re looking from inside a function in the Math table.

To look directly in the root table (without consulting this), one can qualify a lookup with two colons: ::PI.

Tables can also be used to represent arbitrary objects:

@ person1 <- { name=“George” age=47 } @ @ person2 <- { name=“Sandra” age=38 } @

However, classes and instances are more efficient in most such cases.

The FWB Squirrel Prompt(s)

There are actually two different Squirrel script prompts in File Workbench:

• SqScrEng: A plain Squirrel prompt that only accepts Squirrel statements.
• SqSession: As above, but before executing the line, it will scan for and expand certain commands.

SqSession allows for using short commands that are expanded into several lines of Squirrel code. Examples:

Meaning	SqSession	Squirrel code	Result
Print result	p 1+2+3	print(1+2+3)	6
Print/Show Recursively	psr MakeSquares(5)	print(v2sr( MakeSquares(5) ))	[1,4,9,16,25]
Get Function Information	gfi MakeSquares	print(v2sr(getfuncinfo( MakeSquares ),""))	{type=“closure”, args=[“dyn”]}

SqSession can save quite a bit of typing in interactive scripting.

Starting a Squirrel prompt

If you don’t have a command prompt open, or want another one, then:

• Open the pane popup menu
• Select New Cmd Prompt.

This will get you a command prompt window. A dialog to select the prompt type is automatically shown. Select SqSession, press OK and a Squirrel prompt is opened:

The SqScrEng (plain Squirrel) prompt looks like:

@ sqp> @

The SqSession one looks like:

@ sqs@@>

or (when extensions are disabled):

@ sqs!> @

h2. Some useful SqSession commands

Command	Effect
set echo	Turns on echo of processed input. I.e. the resulting Squirrel code is printed, before sent to the Squirrel compiler.
set noecho	Turns off above echo.
!!	Enters un-processed mode (suppress SqSession extensions)
@@@@	Enters processed (SqSession) mode
ple	Print Last Error. Squirrel errors with full stack trace can be lengthy so a compressed version is printed by default. To get the full error report, use ple.
list !TextEditor	Lists all members of the class TextEditor. Any table, array, class or other iterable object can be listed.
list !TextEditor Add	Lists all keys of TextEditor matching the string Add.
modload base.nut	Loads and executes the Squirrel script file base.nut.
modpaths	Prints the directories that are scanned for Squirrel scripts (used in modload).

Editing and running script files

From an SqSession prompt, to load a script file, somefile.nut, run: @ modload somefile.nut @ (in a plain SqScrEng prompt we’d have to use: @ modload(“somefile.nut”) @ ).

Squirrel users might note that we’re not using dofile. The modload function has the advantage of only re-loading a file that’s really has been changed since loading it last, and to keep doing this for any script files it depends on.

FWB can of course be used to edit a Squirrel script files (somefile.nut). To create a new file in a File Browser, hit Ctrl-F7 and enter a filename. Then press F3 to start editing in a FWB text editor. When wanting to try compile / execute the file, hit Ctrl-B.

Directories

By default the Squirrel prompts looks in there directories for * .nut scripts:

• <user-fwb>/scripts/squirrel (<user-fwb> is the settings directory for the current user. On my Linux system, <user-fwb> equals /home/arne/FileWorkbench. On my Windows system it is C:\Documents and settings\ Arne\Application Data\FileWorkbench.
• < fwb-app>/scripts/squirrel (where <fwb-app> is the directory File Workbench is installed in)

You can add other directories using the modpath command.

Startup script files

When FWB is launched it will read / compile / run a number of script files. It will also try to run a user specific startup file:

@ fwb-user-init.nut @

It will first look for this file in /sripts/squirrel and then in /sripts/squirrel (see above).

Other startup files are:
| sq-init.nut | Initialization for basic SqScrEng |
| sqs-init.nut | the same for SqSession |
| fwb-init.nut | Init for FileWorkbench |
| fwb-sqs-init.nut | Init for FWB that adds to SqSession |

Getting something done

To illustrate how FWB can be scripted, we’ll try to accomplish a small task. We want to read and modify a text editor from a script, programatically.

1: Make sure you have at least two MiniApp panes with a text editor to the left and Squirrel prompt to the right. 2: Click in the text editor and enter some text: “Hello George, …” 3 – Run the Squirrel statements: 3a: @ ed <- ::matexted.GetObj(“TextEditor”) @ 3b: @ p ed @ // or print(ed) in a plain Squirrel prompt) We should get an answer like: (instance : 0×02102F48).

The root table variable ma_text_ed always contains a reference to the last active text editor. That’s how we can know which editor we’re working with. But at that stage, it is a non speicalized MiniApp. We need to query it for a TextEditor interface. That’s what happens in the GetObj call in 3a.

We continue with:

4a: @ ed.GotoPos( ed.GetLength() ) @

4b: @ ed.AddText( “\nP.S. Enjoy your holdiays” )@


Now a new line should appear a the end of the editor. In 4a we move the cursor to the end of the text editor buffer.

Finally, we do:

5: @ p ed.GetText() @

and we should get something like: