This project is read-only.
This documentation is incomplete - datatype docs need to be added.

Scripting Language Reference

General Concepts

Script execution begins on the first line.

Script statements end with a semi-colon. (;)

If an error occurs during execution the script execution will be halted.

Case Sensitivity

The scripting language is case-insensitive including keywords and identifiers.

White Space

White space is ignored between operators and operands. White space characters are space, carriage return, line feed, and tab.

The following are all identical:

x = 1 + 2 + 3;
x=1+2+3;
x = 1 +2+3;
x = 1 +
    2 + 3;

Comments

A comment, also known as a remark, can contain any information that a programmer wants to add to describe the script. The comment itself is marked with special characters so that it is completely ignored by the compiler and has no effect on the final software.

Any text or code following the double slash (//) on the same line is ignored during compilation of the program.

Example:

// This entire line is a comment.
x = y; // This part is the comment.
a = b; // a = c

Literals

Numeric

A numeric literal is a sequence of numbers and an optional decimal symbol. A period (.) must be used as the decimal symbol for all locales.

Example:

25
150.25

String

Two forms of string literals are supported: regular string literals and verbatim string literals.

Regular String Literal

A regular string literal consists of zero or more characters enclosed in double quotes, as in "hello", and may include escape sequences (such as \t for the tab character).

Escape Character Description
\\ Backslash (\). As the backward slash character defines as escape character sequence, the double-backslash is required to indicate the insertion of a single backslash.
\n New Line. Inserts a new line into the string literal. When outputted, the output starts a new line of text when the control character is reached.
\t Horizontal Tab. Inserts a horizontal tab into a text string, moving the current position to the next tab stop in a similar manner to pressing the tab key in a word processor.
\0 Unicode Character Zero / Null. This character is generally used as a marker at the end of a file or data stream.
\a Alert. In some scenarios this character sounds an alert through the computer's speaker.
\b Backspace. Emits a backspace character.
\f Form Feed. This character instructs a printer to execute a form feed, ejecting the current sheet of paper and readying the next sheet.
\r Carriage Return. This is similar to the new line character when used for screen output. Some printers use this as an indicator to return to the start of the current line. In this case, to begin a new line both a carriage return and new line character (\r\n) are required.
\v Vertical Tab. Inserts a vertical tab.

Verbatim String Literal

A verbatim string literal consists of an @ character followed by a double-quote character, zero or more characters, and a closing double-quote character. A simple example is @"hello". In a verbatim string literal, the characters between the delimiters are interpreted verbatim, the only exception being a quote-escape-sequence. In particular, other escape sequences are not processed in verbatim string literals. A verbatim string literal may span multiple lines.

String Literal Examples:

a = "hello, world";                 // hello, world
b = @"hello, world";                // hello, world
c = "hello \t world";               // hello     world
d = @"hello \t world";              // hello \t world
e = "Joe said \"Hello\" to me";     // Joe said "Hello" to me
f = @"Joe said ""Hello"" to me";    // Joe said "Hello" to me
g = "\\\\server\\share\\file.txt";  // \\server\share\file.txt
h = @"\\server\share\file.txt";     // \\server\share\file.txt
i = "one\r\ntwo\r\nthree";
j = @"one
two
three";
// Notice j spans multiple lines.

Boolean

There are only two literals that are defined as using the Boolean data type. They are true and false.

Example:

true
false

Operators

An operator is a term or a symbol that takes one or more expressions, or operands, as input and returns a value. Operators that take one operand, such as the increment operator (++) or new, are referred to as unary operators. Operators that take two operands, such as arithmetic operators (+,-,*,/) are referred to as binary operators.

An operand can be a valid expression of any size, composed of any number of other operations. When an expression is evaluated, the first step is to evaluate all the operands from left to right. After all operands have been evaluated, the operators are evaluated in a specific order known as operator precedence. The following table divides the operators into categories based on the type of operation they perform. The categories are listed in order of precedence.

Primary
x.y Member access
a[x] Array element access
f(x) Function or method access
x++ Post-increment
x-- Post-decrement
new T(...) Object creation
colspan="3" Unary
-x Negation
!x Logical negation
Multiplicative
x * y Multiplication
x / y Division
x % y Remainder
Additive
x + y Addition, string concatenation
x - y Subtraction
Bitwise Shift
x << y Shift left
x >> y Shift right
Relational
x < y Less than
x > y Greater than
x <= y Less than or equal
x >= y Greater than or equal
Equality
* x == y Equal
x != y Not equal
Bitwise AND/OR
x & y Bitwise AND
x ^ y Bitwise exclusive OR
x | y Bitwise inclusive OR
Logical AND/OR
x && y Logical AND
x | y Logical OR
Assignment
x = y Assignment
Expression
( expression ) Expression

Identifiers

Identifiers provide names for the following language elements:
  • Variables
  • Functions
  • Labels

An identifier's first character must be an alphabetic character or an underscore (_). The following characters must be alphabetic, numeric, or underscores.

Variables

Variables represent storage locations. The value of a variable can be changed through assignment or through use of the ++ and -- operators.

Local variables must be assigned to using the assignment operator (=) before they can be referenced in any expressions.

Local script variables do not persist after the script execution or script function execution has ended.

Referencing a variable before it is assigned will cause an error.

Example:

x = y;


Literals are implicitly converted to their associated type before the assignment is made. Therefore the following 2 lines have the same effect:

x = 10; // This assigns the literal number 10 to x.
x = new Number(10);  // Same as above.

Functions

Functions are blocks of statements used for computing an output value. Not all functions return an output value.

Function referencing/calling:

Functions are referenced by their name, followed by an open and close parenthesis. Function arguments are passed to the function by entering them between the parenthesis and delimited by a comma.

Function arguments are type sensitive. So the values passed into the function must match the function parameter types. This allows for duplicate function names with different parameter types. Referencing a function with invalid argument types causes an error.

The function return type is type sensitive. If a function returns a value, the value's type must match the function's declared return type. An error is thrown if the value type returned from the function does not match the declared return type. This prevents the type mistake from causing unexpected behavior later in code.

Examples:

System.Sleep( 5000 );


z = Math.Min( x, y );



Function Declarations:

Function declarations use the following format:


function returntype functionname( _parameter_type parameter_name,_ ... )
{
// function code goes here
}



The return keyword terminates execution of the function and outputs the return value. If the return keyword is not used then no output value will be returned.

An example with no function arguments:

function Number ReturnFive()
{
  return 5;
}


An example with 2 function arguments:

function Number Add(Number value1, Number value2)
{
  total = value1 + value2;
  return total;
}


An example causing an error:

function Number causeError()
{
  return "abc"; // causes an error since the declared return type is a Number.
}


Another example causing an error:

x = echoNumber("abc");  // causes an error since the declared parameter type is a Number.

function Number echoNumber(Number value1)
{
  return value1;
}

Labels

Labels mark points of branch execution that are accessible via the goto statement.

Labels must be alone on a line and end with a colon (:).

Example:

myLabel:

Statements

if-else

The if statement selects a statement or block of statements for execution based on the value of a Boolean expression.

Syntax:

if (expression)
  statement;


or

if (expression)
  statement1;
else
  statement2;


or

if (expression)
{
  statement1a;
  statement1b;
}
else
  statement2;


Example:

if (abc == true)
  System.Sleep(1000);
else
{
  if (xyz == 10)
    System.Sleep(5000);
}

while

The while statement executes a statement or a block of statements until a specified expression evaluates to false.

Syntax:

while expression
  statement;


Example:

count = 0
while (counter<5)
{
  TextToSpeech(counter);
  counter++;
}

for

The for loop executes a statement or a block of statements repeatedly until a specified expression evaluates to false. Because the test of a conditional expression occurs before the execution of the loop, a for statement executes zero or more times.

Syntax:

for (initial-expression ; condition-expression ; loop-expression)
  statement;


Example:

for (counter=0 ; counter<5 ; counter++)
{
  TextToSpeech( counter );
}

goto

The goto statement transfers script execution to some label within the script.

Syntax:

goto label;
....
label:


Example:

goto skip_point;
System.sleep(5000);  // this line will be skipped
skip_point:
System.sleep(1000);

break

The break statement terminates the closest enclosing loop in which it appears. Control is passed to the statement that follows the terminated statement, if any.

break;

continue

The continue statement passes control to the next iteration of the enclosing iteration statement in which it appears.

continue;

return

The return statement terminates execution of the method in which it appears and returns control to the calling method. It can also return an optional value.

return;


return expression;

end

Terminates execution of the script.

end;

try-catch-finally

The j9Script language's exception handling features help you deal with any unexpected or exceptional situations that occur when a script is running. Exception handling uses the try, catch, and finally keywords to try actions that may not succeed, to handle failures when you decide that it is reasonable to do so, and to clean up resources afterward.

The try block contains the guarded code that may cause the exception. The block is executed until an exception is thrown or it is completed successfully.

The finally block is useful for cleaning up any resources allocated in the try block as well as running any code that must execute even if there is an exception. Control is always passed to the finally block regardless of how the try block exits. Whereas catch is used to handle exceptions that occur in a statement block, finally is used to guarantee a statement block of code executes regardless of how the preceding try block is exited.

A common usage of catch and finally together is to obtain and use resources in a try block, deal with exceptional circumstances in a catch block, and release the resources in the finally block.
  • The catch statement must specify an exception identifier.
  • A catch AND/OR finally statement is required. In other words try-catch, try-finally, and try-catch-finally combinations are all valid.

Syntax:

try
{
  statement1;
  statement2;
}
catch (ex)
{
  statement1;
  statement2;
}
finally
{
  statement1;
  statement2;
}


Examples:

try
{
  xxxxx // this causes an exception.
}
catch (ex)
{
  return ex.Message;
}

try
{
  throw new Exception( "example" ); // manually throw an exception
}
finally
{
  // Do any clean up here.
  // Notice there is no catch statement.  This finally block will
  // execute and the exception will be thrown.
}

throw

The throw statement is used to signal the occurrence of an anomalous situation (exception) during the script execution.

Usually the throw statement is used with try-catch-finally statements. You can also rethrow a caught exception using the throw statement.

Example:

try
{
  throw new Exception( "example" ); // manually throw an exception
}
catch (ex)
{
  // rethrow the exception just for example purposes
  throw ex;
}

empty-statement

An empty-statement does nothing.

Example empty-statement:

    ;


An empty-statement is used when there are no operations to perform in a context where a statement is required.

Be careful not to inadvertently follow an if-statement with an empty-statement. Doing so will case the following line to always execute.

When intentionally using an empty statement, it is a good practice to comment your code in a way that makes it clear that the empty-statement is intentional.

Global Functions

Conversion Functions

Conversion functions convert from a source type to a specified target type.

Syntax:

String( expression )
Number( expression )
Boolean( expression )


Example:

a = 5;
b = "5";
c = "true";

x = String( a );  // converts the number 5 to as string.
y = Number( b );  // converts the string "5" to the number 5.
z = Boolean( c ); // converts the string "true" to a boolean value of true.

Basic Data Types

String Object

Represents text; that is, a series of characters.

Number Object

Represents a signed IEEE 64-bit (8-byte) double-precision floating-point number ranging in value from -1.79769313486231570E308 through -4.94065645841246544E-324 for negative values and from 4.94065645841246544E-324 through 1.79769313486231570E308 for positive values.

Boolean Object

Represents a Boolean value of true or false.

Dictionary Object

Represents a collection of key/value pairs that are ordered based on the key/index. The key is a case-insensitive string.

DateTime Object

Represents an instant in time, typically expressed as a date and time of day.

Array Object

The Array object is used to store a set of values in a single variable name.

Byte Array Object

Represents an array of bytes.

Exception Object

Represents an error that occurred during script execution.

Object Data Type

Used only as the return type for a method or a parameter type of a method to specify that the return value or parameter value can be any data type.

null

The null keyword is a literal that represents a null reference, one that does not refer to any object.

void

Used only as the return type for a method to specify that the method does not return a value.

Advanced Datatypes & Objects

Math Object

Provides constants and static methods for logarithmic, and other common mathematical functions. This object can not be instantiated in a script.

File System Object

Provides static methods for common file system operations. This object can not be instantiated in a script.

OleDbConnection Object

Represents an OLE DB connection to a data source (such as a database). With a client/server database system, it is equivalent to a network connection to the server.

OdbcConnection Object

Reresents an ODBC connection to a data source (such as a database). With a client/server database system, it is equivalent to a network connection to the server.

DataTable Object

Represents one table of in-memory data retrieved from a database using a DbConnection Object instance.

TextFileReader Object

Facilitates reading from a standard text file.

TextFileWriter Object

Facilitates writing to a standard text file.

RegEx Object

Represents an immutable regular expression.

Last edited Sep 20, 2011 at 5:43 PM by JohnHughes, version 8

Comments

No comments yet.