ForthMinus

Revision as of 11:46, 23 January 2008

Description

ForthMinus is an alternative scripting engine for OpenSim. It's dialect resembles (loosely) the FORTHprogramming language and it's code runs within a Virtual Machine (VM). It's primary purpose was to test the feasibility of implementing a VM to handle the micro-threading of scripts as well as speed up the development of llFunctions for the main LSL script engine. It currently has some advantages and disadvantages versus the primary script engine (DotNetEngine):

Advantages:

• Micro-threading - User scripts cannot lock up the Engine's threads. Perpetual loops can be created without fear of the engine becoming unresponsive.
• State Saving - A ForthMinus script can be state saved thus allowing for script persistence through sim resets.
• Security - All scripts are ran under the VM opposed to being compiled into CIL and ran in parallel to OpenSim (although AppDomain implements some security measures).

Disadvantages

• 100% NOT LSL compatible - It does not resemble LSL/C/C# at all.
• Slower - Since code is executed interpretively, scripts are quite a bit slower than compiled CIL is.

Using ForthMinus

To enable ForthMinus, you need to change the script_engine line within OpenSim.ini to:

script_engine = OpenSim.Region.ScriptEngine.ForthMinus.dll

Language Syntax

Definitions

• Word - A function or subroutine. These can be user defined, or build in (via libraries).
• Data Stack - The main repository for data the script will manipulate
• Execution Stack - The list of commands to process
• Dictionary - The dictionary holds the user defined words
• Variables - Variables can store data - however variables are much slower to utilize than the Data Stack.

Overview

ForthMinus is a simple language with no explicit grammar. Everything is executed in a postfix (or RPN) method, where the arguments for an operator come before the operator itself. For example, take this simple LSL script of a math problem:

default
{
     state_entry()
     { 
         llSay(0,(string)((30 + 5) / 5));
     }
}

In ForthMinus, the functionaly similar code would be:

30 5 + 5 / 0 llsay

Another example is a familiar script:

default
{
     state_entry()
     {
          llSay(0,"Hello Avatar!");
     }

     touch_start(integer num)
     {
          llSay(0,"Touched!");
     }
}

Would be this in ForthMinus:

: @touched "Touched!" 0 llsay ;
"Hello Avatar!" 0 llsay

A bit of explanation is needed for that last script. The line ": @touched "Touched!" 0 llsay ;" is defining a new user-word "@touched" and adding it to the dictionary. The ":" word starts the definition of a new word. The first word following the ":" is the name of the new word to define (in this case, "@touched"). The words following is what the new word will do (in this case, pushes "Touched!" and 0 to the stack, and then pops them and says "Touched!" to channel 0 in world). The ";" indicates the end of the definition.

The word "@touched" is a special event word within ForthMinus. When an avatar touches a prim with a ForthMinus script in it, the engine checks to see if the script has "@touched" defined. If so, it pushes the word "@touched" to the bottom of the Execution Stack, thus not interrupting the current task of the script (this is similar to LSL - events are non-interrupting).

Quotations

The engine has a data type called a quotation. A quotation is signified by square brackets ("[","]"). A quotation holds a chunk of data or even code. Quotations can be stored and manipulated as any other data (e.g. stored in the data stack, assigned a variable name, etc.). A quotation can be executed by the the word qcall. For example:

[ "Hello World" . ] qcall

In this example, the quotation itself is placed onto the data stack. The word "qcall" pops a quotation from the stack, and executes what is inbetween the brackets.

Besides storing hunks of code, quotations can be utilized to mimic other data structures, such as lists, vectors, and rotations. For example:

[ 45.3 23.5 100.3 ] qcall llsetpos

This would execute the vector stored in the quotation, push'ing it's three values into the data stack. The llsetpos word would set the host's position in the sim.

There are words to construct common SL related quotations from the stack. For example:

llgetpos v>q curpos !

• llgetpos pushes the prims current x, y, and z position onto the data stack
• v>q pops the top three values of the stack and creates a quotation containing the x, y, z values ([ x y z ])
• curpos ! stores the quotation into the variable curpos, hence, curpos = [ x y z ]

Quotations can be used in conditional statements:

0 [ "True" 0 llsay ] [ "False" 0 llsay ] qif

In this example:

• 0 is pushed to the stack
• The quotation [ "True" 0 llsay ] is pushed to the stack
• The quotation [ "False" 0 llsay ] is pushed to the stack
• qif pops three values off the stack. If the third deep is true, it qcall's the first quotation, otherwise, it qcall's the second. In this example, since 0 == false, the program will say "False" in world.

QIf statements can be layered by placing additional qif chunks within the quotation. For example:

3 dup 0 < [ "Negative" drop ] [ 0 > [ "Positive" ] [ "Zero" ] qif ] qif 0 llsay

This:

• Pushes 3 into the data stack, then "dup" duplicates it and then pushes 0 to the stack (thus, or data stack is 3 3 0)
• "<" pops two values (3 and 0 in this case), and if 3 < 0, pushes 1, otherwise pushes 0 (and in this case, of course it pushes 0, since 3 is not < 0)
• The two quotations ([ "Negative" drop ] and [ 0 > [ "Positive" ] [ "Zero" ] qif ]) are pushed to the data stack.
• The qif pops the truth value from the second step and the two quotations. Since the test was false, it qcall's the second hunk of code (0 > [ "Positive" ] [ "Zero" ] qif)
• 0 is pushed, then ">" tests if the number is larger than 0, if so pushes "Positive", if not, pushes "Zero". In our example, it will push "Positive"
• "0 llsay" will push 0, then say "Positive" on channel 0 in world.

There are other conditional and control words that utilize quotations:

1 [ "True!" 0 llsay ] qwhen

This will qcall the quotation when the previous item on the data stack is true.

10 [ "Hello World" 0 llsay ] qdo

This will execute the quotation 10 times.

Another nifty function that effects quotations is qforeach:

[ 1 2 3 4 ] [ 1 + ] qforeach

This will execute the second quotation on each element of the first, pushing the results. In this case, the stack would be "2 3 4 5".

Primitive Libraries

These are pre-defined words that are loaded into the engine when a script is created. The engine is capable of dynamically loading libraries, so a future option could be a user could load additional libraries within their script. There is also options to load pre-defined user-level (e.g. words written in ForthMinus) words into a script, allowing end-users to create a custom library of commonly used code.

LibCore

Word marked with "*" are primarily for testing purposes for sim owners and not end users.

LibSLBase

LibMath

Events

Events are handled by tucking words to the bottom of the execution stack as well as adding variables with the parameters of the event.

Notes

- drop ( x -- ) - 2drop ( x y -- ) - 3drop ( x y z -- ) - nip ( x y -- y ) - 2nip ( x y z -- z ) Duplicating stack elements: - dup ( x -- x x ) - 2dup ( x y -- x y x y ) - 3dup ( x y z -- x y z x y z ) - dupd ( x y -- x x y ) - over ( x y -- x y x ) - pick ( x y z -- x y z x ) - tuck ( x y -- y x y ) Permuting stack elements: - swap ( x y -- y x ) - swapd ( x y z -- y x z ) - rot ( x y z -- y z x ) - -rot ( x y z -- z x y ) - roll ( x y z t -- y z t x ) - -roll ( x y z t -- t x y z )