GSL Syntax

Contents

• General Syntax
• GSL Comments
• Specifying Data Values
• Working with Arrays
• Enumerated Values
• Valid Dataset Names
• Creating Datasets
• GSL Operators
• Working with objects
• Flow Control
• GSL Pointers
• GSL Functions
• Reserved Words

Return to The Gsharp Script Language

General Syntax

GSL is a platform independent language and will run on VMS, UNIX and Windows without modification. There is no binary form of GSL, each GSL file is compiled just before execution.

All GSL commands must be terminated with a semi-colon (;).

All whitespace (blanks, tabs and linefeeds) is ignored unless it is included within a string.

A GSL file can be included within another GSL file using the include command:

include "library.gsl";

Return to top

GSL Comments

There are two types of valid comments - multiline and single line.

Multi-line comments begin with /* and end with */. They cannot be nested.

Single-line comments begin with # and continue to the end of the line.

For example,

/*
 * example.gsl - A simple example
 */

include "library.gsl";     # My library of GSL functions

Return to top

Specifying Data Values

There are four data types - float, string, date and time

You can try out any of the examples below by typing echo(<example>) on the command line.

Notes

• When specifying a filename a forward slash can be used instead of a backslash. e.g.

  "$UNIDIR/example/Gsharp/bluntfin.gsl"
"$UNIDIR\\example\\Gsharp\\bluntfin.gsl"

Return to top

Working with Arrays

• Arrays can be specified by separating values with "//"'s. e.g.

  1//3//5//7//9

• Row arrays can be specified by separating values with commas and surrounding them with brackets. e.g.

  (1,3,5,7,9) or (10.0,12.0)

• When working with arrays GSL will operate on corresponding elements of the array. e.g.

  (1,2,3) + (4,5,6) = (5,7,9)

  When combining a single value with an array, the single value is used for each value of the array. e.g.

  (1,2,3) - 1 = (0,1,2)

• Single values of an array dataset can be used in an expression like so:

  x + grid[3,4];

  If either value in the square brackets is left out then all values will be taken. e.g.

  grid[1]	the first row of grid
  grid[,1]	the first column of grid

  More complex subselection can be performed using slice, slicex, slicey and slicez

  Example	Description
  slice(grid,1:10,1:10,0)	Take the first 10 columns of the first ten rows of grid.
  slicex(grid,1//2//3)	Take the first three rows of grid

Return to top

Enumerated Values

The following strings have special meaning in GSL

Return to top

Valid Dataset Names

GSL dataset names may only include the characters a-z, A-Z, 0-9 or _. The first character must be a letter. Reserved words cannot be used.

Dataset names are case sensitive. numDatasets is different from numdatasets.

The following examples show valid and invalid datasets:

Return to top

Creating Datasets

Datasets do not need to be declared before creation. They can be created automatically by GSL functions or by the data import routines.

Any dataset declared within a function will be created as a local variable, will not appear in the DataManager and will be destroyed when the function exits. To create a real dataset within a function then include the folder name e.g. string WORK.CurrentFile

To specify that a dataset cannot be modified precede the declaration with the keyword const and follow it with "= value", where value is the required constant.

The following examples show how to create datasets:

Return to top

GSL Operators

The following operators can be used in GSL

Return to top

Working with objects

Gsharp's graphs are made up of objects. The GSL commands to reproduce your graph can be created by Gsharp - ese "Generate GSL" from the Tools menu of the ScriptBuilder.

You can modify this code or write your own. To create objects in GSL use the create command:

create Viewport page_1.viewport_1;

Each object has a number of resources which describe it. These resources can be set when the object is created:

create Viewport page_1.viewport_1
 ( XuNbackgroundColor = 2,
   XuNframeWidth = 0.1 mm
 );

or at a later time with the set command:

set page_1.viewport_1
 ( XuNfirstDiagonalPoint = (10,10),
   XuNsecondDiagonalPoint = (90,90)
 );

It is also possible to set single resources with a standard assignment:

page_1.viewport_1.XuNobjectEnabled = false;

The value of a resource can also be stored into a dataset or passed to a function:

defaultScale = shades.XuNdefaultScale;
echo(shades.XuNdefaultScale);

Objects can be destroyed with the destroy command:

destroy page_1.viewport_1;

destroy can also be used to destroy datasets (datasets belong to an object called WORK):

destroy WORK.argv, WORK.x;

Return to top

Flow Control

GSL has support for for loops, while/endwhile, if/elif/else and goto.

For example:

for i=1 to 10
  echo(i);
endfor

for i=10 to 1 step -1
  echo(i);
endfor

values = "T"+(1:10);
for D in values
  echo(D);
endfor

i=1;
while (i<1000000)
  echo(i);
  i = i*2;
endwhile

while true
  printf("on and ");
endwhile

Notes

• The break command can be used to jump out of a for or while loop.
• The continue command can be used to jump to the next iteration.
• For loops and while loops can be nested.

if (i=1) echo("i equals 1");

if (i=1) then
  echo("i equals 1");
endif

if (i=1) then
  echo("i equals 1");
else
  echo("i is not equal to 1");
endif

if (a="Cat") then
  echo("Miaaow");
elif (a="Dog") then
  echo("Woof");
elif (a="Cow") then
  echo("Moo");
else
  echo("Unrecognised animal");
endif

Goto

if (a=1)  goto finish;
a = a/2;
finish:
echo(a);

Return to top

GSL Pointers

It is possible to use strings to refer to objects. This is done using the $ sign. Brackets can also be used to avoid ambiguities.

For example:

PTR = "page_1.viewport_1";
create Viewport $PTR;

Pointers are useful if you we want to use one piece of code to work with different objects:

for i = 1 to 10
  PTR = "page_1.viewport"+i;
  create Viewport $PTR
   ( XuNframeWidth = 0.1,
     XuNfirstDiagonalPoint = (rnd(1),rnd(1))*100,
     XuNsecondDiagonalPoint = (rnd(1),rnd(1))*100
   );
endfor

or

for PTR in all("Viewport")
  $(PTR).XuNobjectEnabled = false;
endfor

Pointers can be used to point to any Gsharp object, including data objects:

for PTR in "WORK."+namelist("WORK")
  echo(PTR + "=" + $PTR);
endfor

Return to top

GSL Functions

It is possible to supplement the many built-in functions of GSL with your own GSL functions.

Here is an example:

function MyFunction()
  echo("In MyFunction");
endfunction

You would call this function like this:

MyFunction();

If you want your function to return a value, you must declare the type between function and the function name and you must return the value using the return command. e.g.

function string am_pm()
  if secsince(time)/3600 > 12.0 then
    return "afternoon";
  else
    return "morning";
  endif
endfunction

You would call this function like this:

echo( "Good " + am_pm() );

Parameters can also be passed to the function. These must be specified inside the brackets. e.g.

function PrintOrder(float codes, float quantity)
  order = slicex("Eggs  "//"Bacon "//"Cheese"//"Butter", codes);
  price = slicex(.62//.24//.99//.79, codes);

  echo("You have ordered:");
  echo(order+" ("+quantity+"@"+price+") = "+quantity*price);
  echo("At a total cost of: "+sum(quantity*price));
endfunction

You would call this function like this:

PrintOrder( 1:3, 1:3 );

Parameters can also be passed by reference rather than by value, by preceding the parameter with a &. Any changes made to the parameter by the function will affect the dataset specified in the call to the function. Before passing parameters by reference you should read Function Parameters in the Gsharp User Guide.

Datasets declared within a GSL function are local variables. They do not appear in the DataManager, are known only within the function and are destroyed when the function has finished.

function Swap(float &a, float &b)
  float tmp;
  tmp = a;  a = b;  b = tmp;
endfunction

a=1; b=2;
echo("a="+a+" b="+b);
Swap(a,b);
echo("a="+a+" b="+b);

Return to top

Reserved Words

The following are reserved words in GSL:

and, break, const, continue, create, date, destroy, elif, else, endfor, endfunction, endif, endwhile, false, float, for, function, if, in, include, not, or, pi, print, quit, repaint, return, scope, set, step, stop, string, then, time, to, today, true, undef, while, Arrow, Axis, Bulletin, Button, Canvas, Command, Dialog, Domain, Folder, Graph, Icon, Label, Legend, Logo, Menu, Menubar, Note, Page, Panel, Popup, Separator, Switch, Text, Title, Toolbar, Viewport and any word beginning XuN.