Parasol Framework Manual

The Script class defines a common interface for script execution.

The Script class defines a common interface for the purpose of executing scripts, such as Fluid. The base class does not include a default parser or execution process of any kind.

To execute a script file, choose a sub-class that matches the language and create the script object. Set the Path field and then Activate() the script. Global input parameters for the script can be defined via the SetKey() action.

Note that client scripts may sometimes create objects that are unmanaged by the script object that created them. Terminating the script will not remove objects that are outside its resource hierarchy.

Structure

The Script class consists of the following fields:

Access

Name

Type

Comment

CacheFile STRING Compilable script languages can be compiled to a cache file.

Scripts that support compilation of the source code can be compiled to a target file when the script is initialised. This file is then used as a cache, so that if the cache file exists on the next initialisation then the cache file is used instead of the original source code.

If the cache file exists, a determination on whether the source code has been edited is usually made by comparing date stamps on the original and cache files.

CurrentLine INT Indicates the current line being executed when in debug mode.

In debug mode, the CurrentLine will indicate the current line of execution (according to the original source code for the script).

It should be noted that not all script processors will support this feature, in which case the value for this field will be set to -1.

Error ERR If a script fails during execution, an error code may be readable here.

On execution of a script, the Error value is reset to ERR::Okay and will be updated if the script fails. Be mindful that if a script is likely to be executed recursively then the first thrown error will have priority and be propagated through the call stack.

ErrorString STRING A human readable error string may be declared here following a script execution failure.

Flags SCF Optional flags.

Name	Description
SCF::EXIT_ON_ERROR	The script will automatically terminate its execution process if an error is detected.
SCF::LOG_ALL	Enables execution debugging. More information will be printed to the console in this mode.

Language STRING Indicates the language (locale) that the source script is written in.

The Language value indicates the language in which the source script was written. The default setting is ENG, the code for international English.

LineOffset INT For debugging purposes, this value is added to any message referencing a line number.

The LineOffset is a value that is added to all line numbers that are referenced in script debugging output. It is primarily intended for internal usage only.

Path STRING The location of a script file to be loaded.

A script file can be loaded by setting the Path to its location. The path must be defined prior to the initialisation process, or alternatively the client can define the Statement field.

Optional parameters can also be passed to the script via the Path string. The name of a function is passed first, surrounded by semicolons. Arguments can be passed to the function by appending them as a CSV list. The following string illustrates the format used: dir:location;procedure;arg1=val1,arg2,arg3=val2

A target for the script may be specified by using the 'target' parameter in the parameter list (value must refer to a valid existing object).

Procedure STRING Specifies a procedure to be executed from within a script.

Sometimes scripts are split into several procedures or functions that can be executed independently from the 'main' area of the script. If a loaded script contains procedures, the client can set the Procedure field to execute a specific routine whenever the script is activated with the Activate() action.

If this field is not set, the first procedure in the script, or the 'main' procedure (as defined by the script type) is executed by default.

Results STRING [] Stores multiple string results for languages that support this feature.

If a scripting language supports the return of multiple results, this field may reflect those result values after the execution of any procedure.

For maximum compatibility in type conversion, the results are stored as an array of strings.

Statement STRING Scripts can be executed from any string passed into this field.

Scripts may be compiled into a script object by setting the Statement field with a complete script string. This is often convenient for embedding a small script into another script file without having to make external file references. It is also commonly used for executing scripts that have been embedded into program binaries.

Target OBJECTID Reference to the default container that new script objects will be initialised to.

This field can refer to the target object that new objects at the root of the script will be initialised to. If this field is not set, the root-level objects in the script will be initialised to the script's owner.

TotalArgs INT Reflects the total number of parameters used in a script object.

The total number of parameters that have been set in a script object through the unlisted field mechanism are reflected in the value of this field.

WorkingPath STRING Defines the script's working path (folder).

The working path for a script is defined here. By default this is defined as the location from which the script was loaded, without the file name. If this cannot be determined then the working path for the parent process is used (this is usually set to the location of the program).

The working path is always fully qualified with a slash or colon at the end of the string.

A client can manually change the working path by setting this field with a custom string.

Actions

The following actions are currently supported:

Activate

Executes the script.

GetKey

Script parameters can be retrieved through this action.

ERR acGetKey(*Object, CSTRING Key, STRING Value, INT Size)

Parameter	Description
Key	The name of a key value.
Value	Pointer to a buffer space large enough to hold the retrieved value.
Size	Indicates the byte size of the Buffer.

Reset

Resets an object to its original state.

SetKey

Script parameters can be set through this action.

ERR acSetKey(*Object, CSTRING Key, CSTRING Value)

Parameter	Description
Key	The name of the target key.
Value	The string value to associate with Key.

Methods

The following methods are currently supported:

Callback An internal method for managing callbacks.

ERR sc::Callback(OBJECTPTR Object, INT64 ProcedureID, const struct ScriptArg * Args, INT TotalArgs, ERR * Error)

Parameter	Description
ProcedureID	An identifier for the target procedure.
Args	Optional CSV string containing parameters to pass to the procedure.
TotalArgs	The total number of parameters in the Args parameter.
Error	The error code returned from the script, if any.

Not for client use.

Error Codes

Okay	Operation successful.
Args	Invalid arguments passed to function.

DerefProcedure Dereferences an acquired procedure.

ERR sc::DerefProcedure(OBJECTPTR Object, FUNCTION * Procedure)

Parameter	Description
Procedure	The procedure to be dereferenced.

This method will release a procedure reference that has been acquired through GetProcedureID(). It is only necessary to make this call if the scripting language is managing function references as a keyed resource. Fluid is one such language. Languages that do not manage functions as a resource will ignore calls to this method.

Note that acquiring a procedure reference and then failing to release it can result in the reference remaining in memory until the Script is terminated. There may also be unforeseen consequences in the garbage collection process.

Error Codes

Okay	Operation successful.
NullArgs	Function call missing argument value(s)

Exec Executes a procedure in the script.

ERR sc::Exec(OBJECTPTR Object, CSTRING Procedure, const struct ScriptArg * Args, INT TotalArgs)

Parameter	Description
Procedure	The name of the procedure to execute, or NULL for the default entry point.
Args	Optional parameters to pass to the procedure.
TotalArgs	Total number of `Args` provided.

Use the Exec() method to execute a named procedure in a script, optionally passing that procedure a series of parameters.

The behaviour of this process matches that of the Activate() action and will return the same error codes in the event of failure. If the Procedure returns results, they will be available from the Results field after execution.

Parameter values must be specified as an array of ScriptArg structures. The following example illustrates:

struct ScriptArg args[] = {
   { "Object",       FD_OBJECTID, { .Long = Self->UID } },
   { "Output",       FD_PTR,      { .Address = output } },
   { "OutputLength", FD_LONG,     { .Long = len } }
};

The ScriptArg structure follows this arrangement:

struct ScriptArg {
   STRING Name;
   LONG Type;
   union {
      APTR   Address;
      LONG   Long;
      LARGE  Large;
      DOUBLE Double;
   };
};

The Field Descriptor FD specified in the Type must be a match to whatever value is defined in the union. For instance if the Long field is defined then an FD_LONG Type must be used. Supplementary field definition information, e.g. FD_OBJECT, may be used to assist in clarifying the type of the value that is being passed. Field Descriptors are documented in detail in the Parasol Wiki.

Error Codes

Okay	The procedure was executed.
Args	The `TotalArgs` value is invalid.
NullArgs	Function call missing argument value(s)

GetProcedureID Converts a procedure name to an ID.

ERR sc::GetProcedureID(OBJECTPTR Object, CSTRING Procedure, INT64 * ProcedureID)

Parameter	Description
Procedure	The name of the procedure.
ProcedureID	The computed ID will be returned in this parameter.

This method will convert a procedure name to a unique reference within the script, if such a procedure exists. The ID can be used by the client to create new FUNCTION definitions, for example:

FUNCTION callback;
SET_FUNCTION_SCRIPT(callback, script, procedure_id);

Resolving a procedure will often result in the Script maintaining an ongoing reference for it. To discard the reference, call DerefProcedure() once access to the procedure is no longer required. Alternatively, destroying the script will also dereference all procedures.

Error Codes

Okay	Operation successful.
NullArgs	Function call missing argument value(s)

Script Class

Structure

Actions

Methods

SCF Type