Introduction to Scripting

Holocentric Modeler uses the JSL scripting language as its scripting and document template language.

The language syntax is primarily based on JavaScript, with influences from C#, Basic, Pascal and Eiffel. Hence, having knowledge of any of these languages is useful.

Scripting can be used:

  • as a document template language for report writing and exports
  • for general macro programming language
  • to present up-to-date content in most rich text fields
  • develop complex behavior using classes.

Features of the language include:

  • clear unambiguous syntax
  • optional semi-colon statement termination
  • loop iteration without the need for inner classes or code blocks
  • the ability to create one-line statements for complex loop constructs (eg., the ability to select elements within a collection, based on given criteria)
  • complete class library and runtime garbage collection
  • ability to invoke COM and shell operations.

 

Script Structure

The basic structure for a script is as follows:

input local_declarations endinput
locals local_declarations endlocals
statements

Input Statements

The syntax for input statements is as follows:

input local_declarations endinput

Input statements are used to declare the parameters that should be passed to the script when it is called. The input statement defines a list of input variables for use in a script or document template.

JSL Variable declarations use the Java convention of placing the type before the variable name.

The example below illustrates an input section with 2 input variables, 'diagrams' (that refers to instances of Diagram in a Collection) and 'title', which refers to an instance of a String:

// Script named "MyScript"
input
Collection <Diagram> diagrams
String title
endinput

Each time a script is invoked, the number of input parameters is checked.

You must always invoke a script with the correct number of parameters.

For example:

// Example script invocation.
// Assume that 'items' is a collection of diagrams.
Script.run( "MyScript", { items, "My Report" } )

Local Variables

Local variables are variables within the context of the executing script and can only be accessed internally. The syntax for local variable declarations is:

locals local_declarations endlocals

Local variables can be declared in any script context. As with input variables, each variable must have a type and variable name. For example:

locals
Integer count, total
List <Item> items
endlocals

Variables are initialized to null unless they have been specified as having an initial value. The following example shows how variables can be initialized within the locals declaration:

locals
Integer count = 0, total = 0
List <Item> items = new List()
endlocals

Local variables can also be declared outside the context of the locals and endlocals block. For example you can define variables anywhere within the body of the script using the local declaration:

local Integer count
local Integer total = 0
local List items = new List()

Type Declarations  

Each class in the JSL class library conforms to a type of its same name. For example, Diagram, Integer, Float, String and Character are all valid types and are also classes. Types always begin with a capital letter.

JSL supports generic types (as used in Ada or Eiffel), or templates as they are known in C++. Generic types are useful when declaring collections as they make the content type explicit.

While complete types can be declared in JSL, they are not enforced at runtime. Valid examples of generic types include:

Array < String >
Collection < Item >
Dictionary < String, Item >
KeyValue < String, String >
List < Diagram >

JSL does not enforce type checking within scripts.