====== TOOL Quick Reference Card ======

A "cheat sheet" of commonly used tools, control structures and their syntax.

TOOL lines beginning with the '!' character are considered **comments** and will be ignored by the interpreter.

===== Tools and examples =====
==== A ====
**avg()** syntax and example: 
<code>
A[s1,..,sn,t1,..,tm] = avg (B[s1,..,sn,k,t1,..,tm]; {dim=Name(k)},
{inlcudeZero={on,off}},{weight=W[s1,..,sn,k,t1,..,tm]})
</code>

==== E ====
**extend()** syntax and example: 
<code>
A[..,Y,..] = extend (B[..,X,..]; dim=name, {start=s} {,end=e})
A[s,t] = extend (B[s,t]; dim=time, end=1998)
</code>

==== L ====
**linint()** syntax:
<code>
A[..S] = linint(B[..S];{start={on,off}}, {end={on,off}}, {fixedStart={on,off}}, {fixedEnd={on,off}})
</code>

==== M ====
**map()** example:
<code>A[x] = map (B[y], yTox[x,y])</code>
where map can be created:
<code>
map1[x,y] = create (; dim=x, dim=y, format=mapping, y1->x1,..,yi->xi,...)
map2[x,y] = import (; dataFormat=mapping, y1->x1,..,yi->xi,...)
</code>

Note the syntax for one-to-many:
<code>
map1[x,y] = create (; dim=x, dim=y, format=mapping, \
  y1->"x1,x2,x3", ..,yi->xi,...)
</code>

There is also a dimension mapping:
<code>A[I1,.., In, X,K1,..,Km] = map (B[I1,.., In, Y,K1,..,Km]; Y->X)</code>
which matches up element names in Y with those in X.

{{ :howtos:toolcoding:mappingtemplate.xls |Mapping Template}}
==== N ====
**norm()** examples:
<code>
a[x,y,t] = norm (b[x,y,t]; dim=x)
a[x,y,t] = norm (b[x,y,t]; dim1=x,dim2=y)
a[x,y,t] = norm (b[x,y,t]; dim=all)
a[k->j,t] = norm (b[k->j,t]; dim=Name(k->j)@Name(k))

</code>
==== S ====
**sum()** examples:
<code>
a[t] = sum (b[t,a]; dim=age)
a[t] = sum (b[s,t,a]; dim1=sex, dim2=age)
a[s,t] = sum (b[s->c,t]; dim=stateCOcounty@state)
a[] = sum (b[s,a]; dim=all)
</code>

**shrink()** examples:
<code>
a[t] = shrink (b[byrs,a])
a[t] = shrink (b[byrs,a]; time)
</code>


**glue()** syntax and example:
FIXME

===== TOOL commands =====

TOOL **comments** are lines beginning with the '!' character and will be ignored.

Goto functionality via ''skipto'' command:
<code>
skipto label1
	...
	skipped code
	...
label1:
</code>

Navigation and display: ''where()'', ''moveto("pathName")'', ''up()'', ''look()'', ''showenv()''


**buildstring()** syntax:
<code>
buildstring ($var, string1, string2, ...)
</code>

**listen()** example 1 (for a value to put into a TOOL object):
<code>
string $target	
say ("")
listen ("What do you want for the 2031 total dwelling unit target? {0..}[340500] ",$target)
if $target == ""
	$target = "340500"
	target[] = create (; entity=dwellUnit, data=$target)
else
	target[] = create (; entity=dwellUnit, data=$target)
endif
</code>

Example 2 (for TOOL integer type variable):
<code>
integer $elec_startYear
say ("")
listen ("  What is your elec start year? {2007..2090}[2010] ",$elec_startYear)
if $elec_startYear == 0
	$elec_startYear = 2010
endif
</code>

Example 3 (for a yes/no question):
<code>
boolean $answer
say ("")
listen ("Do you want to do something? {y n}[n] ",$answer)
if $answer== true
	say ("Do stuff here")
endif
</code>

**menu()** syntax:
<code>
menu (prompt, numItems, {item1, ..., itemN},{$items[]}, $choices[]
{defaultChoice=itemNumber}, {oneChoice={on,off}})
</code>

Example1: using variable strings, defaults and one choice only paramters
<code>
integer $numChoices = 3
boolean $choices[$numChoices]
string $choiceStrs[$numChoices]

$choiceStrs[1] = "ON Ministry of Finance - low scenario"
$choiceStrs[2] = "ON Ministry of Finance - reference scenario"
$choiceStrs[3] = "ON Ministry of Finance - high scenario"

menu ("Which result do you you want to see?  ", $numChoices, \
	$choiceStrs[], $choices[]; defaultChoice=1, oneChoice=true)

if ($choices[1] == true) 
	say ($choiceStrs[1])
  ...
endif 
if ($choices[2] == true) 
	say ($choiceStrs[2])
  ...
endif
if ($choices[3] == true) 
	say ($choiceStrs[3])
  ...
endif
</code>
**If-Else** syntax:

<code>
if arithmeticExpression

{else}

endif
</code>

**For loop** syntax:

<code>
for $controlVar from start {upto, downto} end {by step}
...
endfor
</code>

**while-loop** syntax:

<code>
while arithmeticExpression
...
endwhile
</code>

**Boolean** operators: ''>'', ''<'', ''>='', ''<='', ''=='', ''!='', ''AND'', ''OR''
===== Object Creation and Shaping =====

**create()** syntax:

<code>
A[X1,..,Xn] = create (; {object=array},
dim=dimString(X1), ...,dimString=Name(Xn),
{dimFromi=D[..]},{SIuom=uomStr,{metre=ni, m=ni},
{kilogram=ni, kg=ni},{second=ni, sec=ni, s=ni},{degreeC=ni, degC=ni},
{coloumb=ni, q=ni},{radian=ni, rad=ni},{steradian=ni, sterad=ni}},
{altUom=altUomStr}, {entity=entStr},
{SIuomFrom=S[..]}, {altUomFrom=T[..]}, {entityFrom=E[..]},
{dataType={real, integer}},{desc=descrStr},
{format={agg,coord,record,mdi}, useIndex={on,off},
{translate1=string1, .., translaten=stringn,..,value1=number1,..,valuen=numbern,
{ mask1=maskName1[X1,..,Xn]},..{maskn=maskNamen[X1,..,Xn],..}}
...,format dependent parameters...)
</code>

Examples:

Create link to import examples FIXME

<code>
labourRate[s,t] = create (; dim=sex, dim=SEQ;time:1992:1994:1;year, \
entity="(person*year)/auto", rowTitles=on, dataFile=labour.txt)
</code>


**changeshape()** syntax:
<code>
A[..,Y,..] = changeshape (B[..,X,..]; {Name (X)->newDim, DimNum (X)->newDim}, {reduceEnt}, {entity=ent}, \
  {altUom=auom}, {entityFrom=C[..]}, {SIuomFrom=D[..]}, {altUomFrom=E[..]}, {desc=str},{addDimn=dimName}, \
  {addDimnFromm=Z[..]}, {deleteDims:DimName (X),..}, {CheckShape=off})
</code>

Examples:

<code>
A[s,thwb] = changeshape (B[a,s,th]; time->SEQ;time:1991:2006:1;year, deleteDims:age)
</code>

**copyshape()** syntax:
<code>
A[..] = copyshape (B[..])
</code>

**changeseq()** syntax:
<code>
A[..,Y,..] = changeseq (B[..,X,..]; dim=X, {name=c}, {interval=i},{start=b}, {end=e}, {step=s},{shift=n})
</code>

**reorder()** example:
<code>
popx[s,a,t] = reorder (pop[s,t,a]; sex, age, time)
</code>

**seeshape()** syntax:
<code>
seeshape (A1[],..,An[])
</code>

===== Defining Sequences; Extracting and Inserting =====


A **sequence** is defined by the string: ''SEQ;name:start:end:step;stepInterval''\\
For example:
<code>x[t] = create (; dim=SEQ;time:1986:2006:1;year)</code>

Examples of **extract()**, selection **ranges** from sequences.
<code>
A[s,t] = extract (B[s,t]; time:1993..1994)
A[s,t] = extract (B[s,t]; time:+1..+2)
A[s,t] = extract (B[s,t]; 2:1993..1994)
A[s,t] = extract (B[s,t]; 2:+1..+2)
A[s,t] = extract (B[s,t]; 2:+1..-2)
A[s,t] = extract (B[s,t]; time:1991..2006@5)
</code>

Non-sequence extraction:
<code>
A[s,tmp] = extract (B[s,t]; time:"1993,1995")
A[s,t] = extract (B[s,t]; time:+1,+3)
A[s,t] = extract (B[s,t]; time:"1987,1991..1998,2003")
</code>

Set from a set:
<code>
A[cp,t] = extract (B[c,t]; cities:"NY,Toronto")
A[cp,t] = extract (B[c,t]; time:+1,+2)
</code>

Multi-dimensional extraction with **shrink**:
<code>A[t] = extract (B[s,t]; sex:male, time:1993..1994, shrink=on)</code>

**insert()** examples
<code>
popx[t] = insert (popy[tc]; time->time:+0@5)
A[s,t] = insert (B[t]; sex:male)
</code>


===== Sets =====
<code>
crop[] = create (; object=set, data="wheat corn barley")
</code>

Or using a file

<code>
crop[] = create (; object=set, dataFile=crop.txt)
</code>

where 'crop.txt' is a file containing:

<file>
! the set 'crop'
wheat "wheat seed crop"
corn "corn seed crop"
barley "barley seed crop"
</file>


===== Categories =====

Syntax of category creation:

<code>
A[] = create (;object=category, groups=X, members=Y, dataFile=fileName,{desc=descrStr})
</code>

where the category definition file syntax is ''groupElemString : memberElemString'' or ''memberElemString''. For example:

<file>
! munWard category elements
downtown : hamlet
othello
east : romeo
west : juliet
west : falstaff
kingLear
</file>

Or creation with category definition using parameters:

<code>
localinformant vwcCOvpshd[] = create (; object=category, groups=vehWeightClass, members=vehPowerSrcHD, \
	4_5andUnder="ICE_Gas ICE_Diesel ICE_NGL", \
	4_5-14_9="ICE_Gas ICE_Diesel", \
	15andOver="ICE_Diesel")
</code>

**mapcat()** syntax:
<code>
A[..,cs,es,..] = mapcat (B[..,cs->es,..]; dim=csCOes)
A[..,cs->es] = mapcat (B[..,cs,es,..]; category=csCOes)
A[..,cs->es] = mapcat (B[..,cs,..]; category=csCOes)
A[..,cs->es] = mapcat (B[..,es,..]; category=csCOes)
</code>

Category **sum()** syntax:
<code>
A[s1,..,sn,k,t1,..,tm] = sum (B[s1,..,sn,k->j,t1,..,tm]; dim=Name(k->j)@Name(k), {ensureShare=(on,off)})
</code>

===== TOOL Object Info =====

**getobjinfo** syntax:
<code>getobjinfo (A[r,s,t], $infoVar; info=sequenceStart, dim=time)</code>
where common info parameter values are: ''sequenceName, sequenceStart, sequenceEnd, sequenceStep, rank''

Example:
<code>
integer $timeStart, $timeEnd, $targetYear
getobjinfo (population[uss,ts], $timeStart; dim=time, info=sequenceStart)
getobjinfo (population[uss,ts], $timeEnd; dim=time, info=sequenceEnd)
getobjinfo (targetYear[], $targetYear; info=dataElement, default=2041)
</code>

===== TOOL Variables =====

Variable declaration syntax and example:
<code>
varType $var1Name, $var2Name, ...
integer $x, $y, $z
</code>

Variable types: ''integer'', ''real'', ''boolean'', ''string''

TOOL operators by order of precedence:
<code>
* /
+ -
> < >= <=
== !=
AND OR
assign
</code>
===== Object Display =====

**display()** examples: \\

**table()** examples: \\
<code>table (population[s,t,a], births[s,t,ma]; window1=1)</code>

**graph()** examples: \\

**geomap()** examples: \\

===== Views & Scenarios =====

Structure of views.samm file, and types of views: ''creview, disview''

<file>
!type    view name   node        v. link file  tool file     view description
creview  creFertScn  population  creFertScn.v  creFertScn.t  "create fertility scenario"
disview  popRpt      population  popRpt.v      popRpt.t      "Population Report"
fbview   trackEU     compare     trackEU.v     trackEU.t     "Tracking Energy Use"  20  0.001
</file>

Structure of **variable link file** (.v) for **disview** is:

<file>
...
varName
...
</file>

where ''varName'' takes the form ''calculatorName/varName'' for non-framework variables. For **creview** the file has the structure:

<file>
...
varName {U F}
...
</file>

where ''U'' is for Using type object and ''F'' is for Filling type objects.

Object array declarations in views ''objectType objectArrayName[][]'' \\
where objectTypes are: ''view, creview, localview''

Reserved TOOL variables: ''$numScns'', ''$numVars'', ''$scnNumbers[]'', ''$scnNames[]'', ''$scnColours[]'', ''$scnDescs[]'', ''$createView'', ''$history'', ''$background''


**quit()** is called as ''quit (return code)''