Logo

Table of contents

Introduction

CalclipseMath™ is a math tool written in Java. CalclipseMath consists of two main parts; a library for parsing and evaluating mathematical expressions, and a script interpreter based on this library.

The math parser used by the script interpreter recognizes a wide range of predefined symbols. These range from basic mathematical operations, trigonometry, statistics, linear algebra, and more. The scripting language allows you to use these predefined symbols to define your own mathematical functions.

The CalclipseMath script environment supports a basic component type, called MComp (Math Component). MComps are implemented as Java classes, and allow further extensions to the scripting language.

Getting started

CalclipseMath has the following directory layout:

calclipsemath
  +---- bin  [launchers]
  |
  +---- doc  [documentation]
  |
  +---- lib
  |
  +---- res
  |
  +---- inventory [MComps/scripts]

The script interpreter is invoked from the command line using the calclipse command located in the bin directory. This command expects a script file to be specified as a command line argument. The inventory contains a sample script file named calc.txt. To run that script, first change to the bin directory, then enter the following command:

calclipse ..\inventory\calc.txt

In the above example the path to the script is relative to the bin directory, but you might just as well add the bin directory to the path environment variable.

Fundamental concepts

This chapter explains concepts that are essential to the scripting language.

Expressions

Mathematical expressions are treated as instructions that are carried out when evaluated. Semicolon is used to separate multiple expressions. A semicolon is also permitted at the end of an expression, where it is ignored. The following example shows three expressions using the print operator to display the result of some calculation:

print 1 + 2;
print 3 * 4;
print 5 / 7;

Identifiers

An identifier is a user-chosen name for a variable or function. The first character in an identifier must be a letter or underscore. Remaining characters may also include digits.

Symbols

A symbol is a name that may occur in an expression. User-defined identifiers, and predefined names like print, +, * and /, are all symbols. Symbols are resolved by querying a dictionary during the evaluation of an expression.

Variables

A variable is a symbol that can have a value stored in it. The following example illustrates how a value may be stored in a variable named "x":

x := 1 + 2

Constants like pi, on the other hand, cannot be assigned new values.

Strings

A string is a representation of text as a sequence of characters. Strings may be surrounded by either single or double quotes. The following is an example of a string:

"...Some text..."

In an expression, strings may be concatenated with the + operator to form a combined string. For example, the expression:

"Event" + " horizon"

results in:

"Event horizon"

Any value can be appended to a string, like this:

'10 squared equals: ' + 10^2

The expression above first raises ten to the power of two, then adds the result to the string literal on the left, resulting in a new string containing the left followed by the result on the right.

Scripts

In general a script is a small program that another separate program is able to run. A CalclipseMath script is a text file that may contain mathematical expressions, exports and imports, and declarations of variables and functions.

MComps

An MComp (Math Component) is a type of software component supported by the script interpreter. An MComp is written in Java, and may be imported by scripts. Symbols exported by the MComp become available in scripts importing the MComp.

Namespaces

A namespace is a logical grouping of names for the purpose of disambiguation. Namespaces help to ensure that if two MComps export the same symbol, a name conflict is prevented since the two symbols belong to different namespaces.

Scripting language

This chapter describes the constructs making up the scripting language.

Comments

Comments are notes or remarks embedded in the script. Comments are intended for human readers for explanatory purpose, and ignored by the script interpreter. Comments are surrounded by /* and */, and may occur anywhere in the script.

Executing expressions

The execute keyword is followed by an expression to be executed by the interpreter. exec is an alias for execute. The following example illustrates how to execute an expression in a script:

/* Prints 3 to the console: */
execute print 1 + 2

If the expression spans multiple lines, the remaining lines of the expressions must be space or tab indented. The following code executes a multi-line statement:

execute print 'This is line 1';
   print 'This is line 2';
   print 'This is line 3'

Declaring variables

Before a variable can be referenced in an expression, it must be declared (created). A variable declaration has the form of an identifier followed by an optional assignment. The assignment is specified as := followed by an expression. If the expression spans multiple lines, the remaining lines of the expression must be space or tab indented. Unassigned variables receive the default value of zero. A declared variable may be reassigned later in the script.

The following example illustrates creation and assignment of two variables named "x" and "y":

/*
This script produces the following output:
0.0
1.0
2.0
3.0
*/
x
y := 1
exec print x; print y
x := 2
y := x + 1
exec print x; print y

Declaring functions

Declaring a function is very similar to declaring a variable. There are a few differences, however. When declaring a function, the identifier must be followed by parentheses. Independent variables of the function are placed within these parentheses. A function may also be assigned an expression, which is used as the definition of the function. If the expression spans multiple lines, the remaining lines of the expression must be space or tab indented. A dependency between a function and a variable is established by using the variable in the definition.

The following are examples of function declarations:

f() := 2
g(x) := 2x
h(x, y) := 2x + y

A declared function may be redefined later in the script. The variable list is then optional. If present, it must be identical to the one specified in the declaration.

If any of a function's variables has not previously been declared, it is created along with the function and given the default value of zero. A function's variable is unaffected by the evaluation of the function, and may be used like any other variable in the script.

The undeclare keyword

The undeclare keyword is followed by a comma-separated list of identifiers, which are removed so they are no longer recognized by the interpreter. The following example illustrates the use of this keyword:

two_pi := 2pi
f(x) := 2x + sin two_pi
undeclare x, two_pi

The export keyword

The export keyword is followed by a comma-separated list of identifiers, which will be made available to be used in other scripts. The following script exports two variables and one function (the first line, name steep_line, is explained in the next section):

name steep_line
a := 23
b := 7
f(x) := ax + b
export a, b, f

The name declaration

A script that exports symbols should have a name declaration. The name is used as namespace for symbols exported by the script. The name is declared using the name keyword followed by an identifier. The name declaration should be placed at the top of the script.

The import keyword

The import keyword allows your script to use other scripts and MComps. This involves adding exported symbols to the vocabulary of the importing script. The imported symbols are prefixed with the name of the exporting script or MComp, followed by colon.

Assuming the code above is saved to a file named stpln.txt, the following example shows how to use it in a script located in the same directory:

/*
This script produces the following output:
a = 23.0
b = 7.0
f(21) = 490.0
*/
import 'stpln.txt'
exec
   print 'a = ' + steep_line:a;
   print 'b = ' + steep_line:b;
   print 'f(21) = ' + steep_line:f(21);

The import keyword is followed by a comma-separated list of strings. The strings should contain either the path to a script file, or a URL on one of the following formats:

  • script://package/file-name: A script file on the class path.
  • class://package.ClassName: An MComp on the class path.
  • Alias: A more convenient name for a URL or file path. Aliases are specified in files on the class path named aliases.properties. An entry could for instance look like this: steep=C:\MyScriptFiles\stpln.txt.

The namespace keyword

The namespace keyword makes life a little easier by allowing imported symbols to be referenced without the namespace prefix. This keyword is used in conjunction with the import keyword. The following example illustrates how it works:

import 'toast_thingy.txt', namespace 'tst'
A := tst:make_toast(2)
B := make_toast(2) /* same as above, but without the namespace */

In the example above, the first string after import is a script file. The second string, the one after namespace, is the name of the script, which happens to be "tst".

The main section

A script may contain a main section at the very bottom. The main keyword marks the beginning of the section. Everything following the main keyword will be interpreted as an expression, regardless of indentation.

© 2013 Tone Sommerland