FORA/tutorial

Introduction

Overview of the manual

The FORA tutorial is a practical guide to using the FORA programming language. It teaches the reader by using examples to demonstrate the development of a few simple programs. Each example introduces new features, so that by mastering these examples, a competent technician will be ready to tackle more advanced projects.

Audience

Readers are assumed to have a logical mind and basic numeric ability. Familiarity with languages such as C, Python or Java is beneficial as FORA is similar to these languages. An understanding of object-orientated programming is useful, but not required. The examples are written in a concise self-documenting programming style so that they are easy to follow. Programming "tricks" are avoided as the result is often unmaintainable code.

FORA Basics

FORA

FORA provides a platform to develop programs which dynamically scale to use all the computer resources available to perform complex computations. If you have a 32-core cpu, then a FORA program will dynamically use as many cores as it needs to minimise its runtime. Similarly in a cloud environment, calculations can be split between multiple blade computers. So many problems can be solved in less time using FORA code than an equivalent C program.

The FORA interpreter dynamically compiles code so that execution efficiency is similar to a program written in C, but development using an interpreter is far faster than using a compiler. So FORA allows mathematical models to be developed and modified more quickly than traditional languages.

FORA program development

A FORA program is a sequence of FORA statements normally stored on a harddisk. The program may reference FORA modules from a library. Typically a program is developed as a set of modules. Each module is tested interactively and then installed in a library as a module. The standard FORA virtual machine has two text editors suitable for writing FORA code:

• "gedit" is a screen-based editor available from the Applications/Assessories menu.
• The legacy "vi" editor is available using terminal from the same menu.

The writer's preference is to use "vi".

FORA Identifiers and Cast Functions

Identifier names follow standard programming conventions. The examples uses "camelcase" style to make the code easier to follow. In FORA all identifiers are objects, which are dynamically typed as they are used. Inbuilt functions provide casting between String and basic Integer types. The following table explains how this works.

Code	Dynamic Object Type	Cast Function
a=1	Int64 (signed 64-bit integer)	a=Int64("123")
a=1s32	Int32	a=Int32("123")
a=1s16	Int16	a=Int16("123")
a=1s8	Int8	a=Int8("123")
a=1u64	Uint64 (unsigned)
a=1u32	Uint32
a=1u16	Uint16
a=1u8	Uint8
a=true	Uint1
a="Hello"	String	a=String(123)
a=1.0	Float64
a=1.0f32	Float32
a=1.0; a=1	Finally Int64
a=fun(x){x*x}	function
a=(1,2)	Tuple(Int64,Int64)
a=(1,'Fred')	Tuple(Int64,String)
a=[1,2,3]	Vector(Int64)
a=[1,'Fred']	Vector(AnyConstant)
a=['Fred']	Vector(String)

The FORA 'Type' interpretive command returns the type of any in-scope FORA object.

FORA uses 64-bit integers by default on hardware which supports it. On many systems, 64-bit arithmetic is slower than 32-bit computations. When optimising module code, the use of appropriate integer sizes will generally give a performance benefit.

FORA operators

FORA supports the following operators:

Operator Class	Supported operators
Arithmetic	+,-,*,/,%,**
Comparison	==,!=,>,<,>=,<=
Concatenation	+
Assignment	=
Bitwise	,^,<<,>>
Logical	and,or,not
Precedence	(,) as matched pairs
Block	{,} as matched pairs

Operator meaning and precedence follows industry standards.

FORA Operation

Using the Interpreter

On the standard FORA VM open a terminal window from the Applications/Accessories menu.
Then enter "fora" to load the interpreter.
You can now enter your first line of FORA code as 'println("Hello World")'. The FORA inbuilt functions print and println provide basic console output, which is mainly used for program testing.
You have written and tested your first line of FORA code and should see a result similar to the image:

Hello World Program

Use your favorite text editor to create file hello.fs to be the source file for the hello program. It should contain the FORA statement 'println("Hello World")'.Then save the file to disc.

In another terminal window enter "fora hello.fs".
Your first FORA program has run and you should see a result similar to the image:

A simple Function

The tutorial develops greet.fs from hello.fs and uses a simple function to personalise our programs.
Using your favorite text editor, create greet.fs based on the image code.

Open another terminal window and run the FORA interpreter in interactive mode to test the greet function.

It works fine, so press Control-D to exit the FORA interpreter.

You now have a window with your source code and a window using the FORA interpreter. Change your source to use the Australian "G'day", rather than the English "Hello" . Now click the up-arrow key which displays the last command. Hit the Enter key to test your code changes. You have a simple efficient testing environment.

Running our first program as a module

Now that the greet function has been tested, we can include it in a library of tested routines. By default FORA searches the current directory for Module Libraries with .fora extentions. We will call our library tutorial.fora and create this file in the current directory (mkdir tutorial.fora) .

We copy greet.fs to the library and change the function declaration to suit a module function and document as appropriate.

We now use different FORA options run our greet function from the module library. First we use the -e option which evaluates an expression; in this case a function call statement. Then we run the interpreter interactively using no options. Finally we use the -i option to run a FORA source file base.fs (shown below) and test the module interactively. Control-D exits.

This program shows a neat trick to simplify coding and save typing.

Using FORA Iterators

Iterators and iterator functions are a very powerful feature of the FORA language. The tutorial uses a simple example to show how these feature are used.

Iterator Functions

An iterator function is called repetitively to return values until it finishes. Potentially the function may never end, so it may be considered as the current value and a tail consisting of the values yet to be returned. The value returned is the iterator. Iterators are typically used with the construct:

for iterator in iterator function { function }

The "sequence" example

First we write an iterator function sequence(start,end) to return all the integers in the range start to end. By default the range is 1 to 5. We create a file seq.fora as shown and save it to disk.

The yield statement returns an iterator to the caller

We load the FORA interpreter and use the "for iterator in iteratorFunction" construct to test our code.

Now that the code is tested, we add it to tutorial.fora. In future it will be accessed as tutorial.sequence and file seq.fora should be deleted.

Processing a File using an Iterator

A Textfile Iterator Function

We now modify the sequence program to read lines from a file. The readFile iterator function will take a filename as a parameter. The function uses Python file access primitives directly and also local variables. Create a file rd.fora with the code shown.

We explain the new features:

• Within functions, the let directive binds an identifier to its storage and must be used the first time an identifier is referenced.
• The Python open function links a file to a PythonObject. Use 'rb' or 'wb' for reading or writing.
• The size function returns the number of characters in a String.
• The Python readline function reads the next line of text, including the End of Line character, from a PythonObject linked to a file. At the End of File, a zero-length string is returned.

Testing the Textfile Iterator Function

As the test program is non-trivial, we create a file rdTest.fs and use FORA interactively to test the function.

We explain the test program:

• The filename is hardcoded so we don't have to enter it for each test. It will be sufficient to list the source of this short test program. Note that as this code runs interactively and is not a function the let directive should not be used.
• A heading line is printed and the line count is initialised.
• The iterator function is called to return each line in the file. Each line is processed as follows.
  • A line number is printed together with the line contents. Note that as each line ends with an EOL character print is used instead of println.
• Finally println finalises the listing neatly.

Note that we use the '-i' compiler option to run the FORA interpreter interactively.

As a technical exercise, change rdTest.fs to print line numbers as a zero-padded 3 digit field. Hint line 5 will need replacing.

Now that the readFile function has been tested, it can be added to the module tutorial.fora as a tested function. rd.fora should then be deleted