Import org.simantics.scl.tutorial from incubator SVN repo

[simantics/platform.git] / bundles / org.simantics.scl.tutorial / scl / Tutorial / X Old tutorial.md

<script type="text/javascript"\r
  src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">\r
</script>\r
\r
# Getting started\r
\r
SCL Console is the easiest way to access SCL in Simantics. Therefore we will\r
be using it all the time in this tutorial.  \r
\r
----\r
\r
SCL Console is opened from the menu *Show View/Other/SCL Console*.\r
\r
\includegraphics[scale=0.4]{figures/ShowView.png}\r
\hspace{1cm}\r
\includegraphics[scale=0.4]{figures/ShowView2.png}\r
\r
The view that is opened looks like this:\r
\r
\includegraphics[scale=0.5]{figures/SCLConsole.png}\r
\r
SCL commands are written to the box at the bottom of the view and the command responses\r
are shown in the upper part of the view. Try writing\r
~~~\r
> 1 + 1\r
~~~\r
and press enter.\r
\r
\r
----\r
If the current command in the SCL Console input box contains an error, it is shown with a red underline.\r
Moving the mouse pointer to that position shows an error description:\r
\r
\includegraphics[scale=0.5]{figures/ConsoleError.png}\r
\r
When the command contains an errors, the console is not willing to execute it. Pressing *enter*\r
adds a new line to the command.\r
\r
While editing the command, arrow keys can be used to move the cursor around. \r
Pressing *ctrl-enter* adds a new line even if the command is currently valid.\r
Pressing *ctrl* and arrow keys up or down, you can browse the previously entered commands. \r
\r
Also copy *ctrl-C*, paste and cut work in the editing area.\r
\r
\r
----\r
### Exercise\r
\r
Run a multiline command:\r
~~~\r
> for [1..10] (\x -> \r
      for [1..x] (\y ->\r
          print (show x + " + " + show y + " = " + show (x+y))\r
      )\r
  )   \r
~~~\r
Then find it from the history and modify it to show multiplications instead of additions.\r
\r
\r
----\r
### Remark\r
We will show lots of examples of SCL code in this tutorial. If some explanation leaves\r
you in uncertain state, copy some of the examples to the console and \r
play with them.\r
\r
\r
## Basic expressions\r
\r
We start from the basic mathematical expressions you can write in SCL.\r
This should cover the most needs you have if you want to use SCL expressions\r
in component types.\r
\r
----\r
Writing mathematical formulas in SCL is mostly unsurprising.\r
~~~\r
> 3*7+1\r
22\r
> 2 - sqrt 2\r
0.5857864376269049\r
> cos pi\r
-1.0\r
~~~\r
\r
One difference from many programming languages is that parentheses are not required around the \r
parameters and multiple parameters are separated by whitespace:\r
~~~\r
> atan2 1 1\r
0.7853981633974483\r
~~~\r
\r
Parentheses are needed for each parameter separately, if the parameter is\r
more complicated expression than  constant or variable:\r
~~~\r
> atan2 (sin 0.4) (cos 0.4)\r
0.4\r
~~~\r
\r
\r
----\r
### Exercise\r
What is wrong with the following code. How to fix it?\r
~~~\r
> sin -1\r
~~~\r
\r
----\r
The results of the computations can be bound to variables and used in subsequent expressions:\r
~~~\r
> m = 4.0\r
> c = 2.998e8\r
> energy = m * c^2\r
> energy\r
3.5952016E17\r
~~~\r
\r
If the variable is bound multiple times, the latest definition is used:\r
~~~\r
> a = 4\r
> a = 8\r
> a\r
8\r
~~~\r
\r
\r
----\r
### Remark\r
Replacing a variable binding with a new binding is a feature of SCL Console.\r
In SCL modules, variables can be bound only once.\r
\r
----\r
A variable name must begin with a *lower-case* letter or an underscore.\r
Following that can be any number of letters (lower-case and upper-case), numbers and underscores.\r
The following names are reserved and cannot be used as identifiers:\r
`_`, `forall`, `if`, `then`, `else`,\r
`where`, `by`, `do`, `mdo`, `class`, `effect`,\r
`match`, `with`, `instance`, `deriving`,\r
`data`, `type`, `infix`, `infixl`, `infixr`.\r
`import`, `include`, `importJava`, `as`.\r
\r
\r
----\r
\r
This is the list of arithmetical functions available in SCL. The middle column\r
contains the types of the functions. You can ignore them now.\r
\r
<table><tr><td>\r
zero </td><td> Additive a => a </td><td> additive neutral element </td></tr><tr><td> \r
(+) </td><td> Additive a => a -> a -> a </td><td> addition </td></tr><tr><td>\r
sum </td><td> Additive a => [a] -> a </td><td> sum of list elements </td></tr><tr><td>\r
neg </td><td> Ring a => a -> a </td><td> negation </td></tr><tr><td>\r
(-) </td><td> Ring a => a -> a -> a </td><td> difference </td></tr><tr><td>\r
one </td><td> Ring a => a </td><td> multiplicative neutral element </td></tr><tr><td>\r
(*) </td><td> Ring a => a -> a -> a </td><td> multiplication </td></tr><tr><td>\r
fromInteger </td><td> Ring a => Integer -> a </td><td> converts an integer to another number format </td></tr><tr><td>\r
abs </td><td> OrderedRing a => a -> a </td><td> absolute value </td></tr><tr><td>\r
(/) </td><td> Real a => a -> a -> a </td><td> division </td></tr><tr><td>\r
(`^`) </td><td> Real a => a -> a -> a </td><td> exponentiation </td></tr><tr><td>\r
pi </td><td> Real a => a </td><td> $\pi$ </td></tr><tr><td>\r
sqrt </td><td> Real a => a -> a </td><td> square root </td></tr><tr><td>\r
exp </td><td> Real a => a -> a </td><td> exponent function </td></tr><tr><td>\r
log </td><td> Real a => a -> a </td><td> natural logarithm </td></tr><tr><td>\r
sin,cos,tan </td><td> Real a => a -> a </td><td> trigonometric functions </td></tr><tr><td>\r
asin,acos,atan </td><td> Real a => a -> a </td><td> inverse trigonometric functions </td></tr><tr><td>\r
atan2 </td><td> Real a => a -> a -> a </td><td> arctangent with two parameters </td></tr><tr><td>\r
sinh,cosh,tanh </td><td> Real a => a -> a </td><td> hyperbolic functions </td></tr><tr><td>\r
asinh,acosh,atanh </td><td> Real a => a -> a </td><td> inverse hyperbolic functions </td></tr><tr><td>\r
fromDouble </td><td> Real a => Double -> a </td><td> converts a double to another number format </td></tr><tr><td>\r
floor </td><td> Real a => a -> a </td><td> the largest previous integer </td></tr><tr><td>\r
ceil </td><td> Real a => a -> a </td><td> the smallest following integer </td></tr><tr><td>  \r
div </td><td> Integer a => a -> a -> a </td><td> integer division </td></tr><tr><td>\r
mod </td><td> Integer a => a -> a -> a </td><td> integer remainer\r
</td></tr></table>\r
\r
Their meaning is mostly self-explanatory. \r
Real and integer divisions are two different functions:\r
~~~\r
> 5 / 2\r
2.5\r
> 5 `div` 2\r
2\r
~~~\r
The hat `^` is exponentiation:\r
~~~\r
> 3^4\r
81.0\r
~~~ \r
Negation function `neg` can be used with the unary minus syntax. So the following are equivalent:\r
~~~\r
> neg 3\r
-3\r
> -3\r
-3\r
~~~\r
\r
\r
----\r
### Remark\r
At this point you may encounter the following problem:\r
~~~\r
> a = 2\r
> b = 3.4\r
> a + b\r
~~~\r
The console does not execute the last expression because it contains an error \r
``Expected $\langle$Integer$\rangle$ got $\langle$Double$\rangle$''.\r
This is because the variable `a` is bound to an integer value and `b` is bound to a double value\r
and SCL does automatic number conversion only for numerical literals (2, 3.4 etc.). There are several ways to fix\r
the problem. First is to define `a` as a double:\r
~~~\r
> a = 2.0\r
~~~\r
or\r
~~~\r
> a = 2 :: Double\r
~~~\r
Another way is to convert the integer value to double in the final expression:\r
~~~\r
> fromInteger a + b\r
5.4\r
~~~\r
\r
\r
----\r
\r
Numbers and many other objects can be compared with the following functions:\r
<table><tr><td>\r
(==) </td><td> Eq a => a -> a -> Boolean </td><td> equality </td></tr><tr><td> \r
(!=) </td><td> Eq a => a -> a -> Boolean </td><td> inequality </td></tr><tr><td>\r
(<),(>) </td><td> Ord a => a -> a -> Boolean </td><td> strict comparison </td></tr><tr><td>\r
(<=),(>=) </td><td> Ord a => a -> a -> Boolean </td><td> non-strict comparison </td></tr><tr><td>\r
min </td><td> Ord a => a -> a -> a </td><td> returns the the smaller of two parameters </td></tr><tr><td>\r
max </td><td> Ord a => a -> a -> a </td><td> returns the larger of two parameters </td></tr><tr><td>\r
compare </td><td> Ord a => a -> a -> Integer </td><td> returns -1 (0, 1), if the first parameter is smaller (equal, bigger) than the second one\r
</td></tr></table>\r
For example:\r
\r
~~~\r
> 1 < 2\r
True\r
> 6 < 4\r
False\r
> max 1.5 3.8\r
3.8\r
~~~\r
\r
\r
----\r
Boolean expressions can be used to write conditional expressions:\r
~~~\r
> a = 3\r
> b = 4\r
> if a < b then a else b\r
3\r
> a = 5\r
> if a < b then a else b\r
4\r
~~~\r
In order to test multiple conditions, if-expressions can be combined:\r
~~~\r
> if a < b \r
  then -1\r
  else if a > b\r
  then 1\r
  else 0\r
1\r
~~~\r
\r
\r
----\r
Boolean values can be combined with conjunction `&&`, disjunction `||` and negation `not`.\r
~~~\r
> True && False\r
False\r
> True || False\r
True\r
> not True\r
False\r
~~~\r
\r
\r
----\r
\r
Strings are written by enclosing them into double quotes:\r
~~~\r
> "Hello world!"\r
"Hello world!"\r
~~~\r
\r
Some of the operators seen so far can also be applied to strings:\r
~~~\r
> "Hello" + " world!"\r
"Hello world!"\r
> "Foo" < "Bar"\r
False\r
~~~\r
\r
There are also many functions specific to strings. We will however \r
describe just some of them:\r
<table><tr><td>\r
length </td><td> String -> Integer </td><td> the length of a string </td></tr><tr><td>\r
substring </td><td> String -> Integer -> Integer -> String </td><td> returns a substring of the string\r
                                                     when the begin and the end positions of the\r
                                                     string are given </td></tr><tr><td>\r
show </td><td> Show a => a -> String </td><td> converts a value to a string </td></tr><tr><td> \r
read </td><td> Read a => String -> a </td><td> converts a string to a value </td></tr><tr><td>\r
indexOf </td><td> String -> String -> Integer </td><td> the index of the first position in the string that matches the given string </td></tr><tr><td>\r
lastIndexOf </td><td> String -> String -> Integer </td><td> the index of the last position in the string that matches the given string </td></tr><tr><td>\r
startsWith </td><td> String -> String -> Boolean </td><td> checks if the string starts with the given prefix </td></tr><tr><td>\r
trim </td><td> String -> String </td><td> removes the white space from the beginning and end of the string\r
</td></tr></table>\r
From these functions, we need only `show` in this tutorial. \r
\r
~~~\r
> x = 5.7\r
> "x = " + show x\r
x = 5.7\r
~~~\r
\r
\r
## Functions\r
\r
In SCL, functions are first-class values that can be manipulated with the\r
same ease as numbers and other values. Almost all control structures also\r
require that you define your own functions. Therefore we describe them\r
before going to other data structures.\r
\r
----\r
The syntax of the function definitions in SCL resemble function definitions in mathematics:\r
~~~\r
> dist x y = abs (x - y)\r
> dist 2 5\r
3\r
> dist 6 4\r
2\r
~~~\r
\r
\r
----\r
### Exercise\r
Define a generalized average function:\r
$${\rm avgG}\ p\ x\ y = \left({x^p + y^p \over 2}\right)^{1 \over p}$$\r
Check that it works correctly:\r
~~~\r
> avgG 1 3 5\r
4.0\r
> avgG 2 2 14\r
10.0\r
> avgG (-1) 3 6\r
4.0\r
~~~\r
\r
\r
----\r
\r
Functions can be recursive. For example Euclid's algorithm for\r
computing greatest common divisor for two integers can be implemented\r
as:\r
~~~\r
> gcd a b = if a > b\r
            then gcd b a\r
            else if a == 0\r
            then b\r
            else gcd (b `mod` a) a\r
> gcd 12 9\r
3           \r
~~~\r
\r
\r
----\r
### Exercise\r
Implement a function `fib` for computing Fibonacci numbers. First two Fibonacci numbers\r
are one and after that every Fibonacci number is the sum of two previous Fibonacci numbers:\r
1, 1, 2, 3, 5, 8, 13, \ldots.  \r
\r
\r
----\r
Many functions are implemented by cases. In these situations function definition can be\r
written as multiple separate equations:\r
~~~\r
> gcd a b | a > b = gcd b a\r
  gcd 0 b         = b\r
  gcd a b         = gcd (b `mod` a) a\r
~~~\r
In this way it is easier to verify that every individual equation is corrent.\r
\r
There are two ways to restrict the applicability of an equation.\r
The first way is to use patterns as parameters instead of just variables.\r
In the example above, the second equation has a constant pattern 0 as a first parameter.\r
We see later more complicated patterns.\r
The second way to restrict the applicability is to add guards to the equation. \r
A guard is the part in the first equation above after the vertical bar and before the equality.\r
It is a boolean condition that must be true for equation to be applicable.\r
\r
The actual function value is computed by the first equation that can be applied with the given parameters. \r
\r
\r
----\r
### Exercise\r
Rewrite the Fibonacci's function using either constant patterns or guards.\r
\r
\r
----\r
One of the cornerstones of all functional programming languages, including SCL, is the ability\r
to give functions as parameters to other functions:\r
~~~\r
> epsilon = 1e-9\r
> der f x = (f (x + epsilon) - f (x - epsilon)) / (2*epsilon)\r
> der sin 0\r
1.0\r
> der log 5\r
0.2000000165480742\r
~~~\r
This kind of functions are called *higher order functions*.\r
\r
Here is another example:\r
~~~\r
> iterate f n x | n > 0     = iterate f (n-1) (f x)\r
                | otherwise = x\r
> collatz n | n `mod` 2 == 0 = n `div` 2\r
            | otherwise      = 3*n + 1\r
> iterate collatz 0 13\r
13\r
> iterate collatz 1 13\r
40\r
> iterate collatz 2 13\r
20\r
> iterate collatz 5 13\r
16\r
> iterate collatz 8 13\r
2\r
> iterate collatz 9 13\r
1\r
~~~\r
\r
\r
----\r
Often the function we want to define can be get by filling some parameters of an already existing function.\r
For example a function `limitZero`, that returns zero if its parameter is negative and otherwise\r
returns the parameter unmodified, can be defined as:\r
~~~\r
> limitZero = max 0.0\r
> limitZero 2.1\r
2.1\r
> limitZero (-5.4)\r
0.0\r
~~~\r
This is called *partial application*.\r
\r
\r
----\r
Binary operators can be referred and partially applied by enclosing them\r
in parenthesis:\r
~~~\r
> f = (+)\r
> f 1 2\r
3\r
> incByOne = (+) 1\r
> incByOne 5\r
6\r
~~~\r
\r
Inversely, an ordinary function can be used as a binary operator by enclosing it\r
to backquotes (in fact, we have seen it already in the definiton of `gcd`):\r
~~~\r
> 1 `f` 2\r
3\r
> 14 `div` 3\r
4\r
~~~\r
\r
\r
----\r
Functions can be also defined without giving them a name:\r
~~~\r
> \x -> x * 2\r
<function>\r
> (\x -> x * 2) 3\r
6\r
~~~\r
\r
This is useful when using higher order functions:\r
~~~\r
> der (\x -> x^2 - 5*x) 2\r
-1.000000082740371\r
~~~\r
\r
\r
----\r
For writing complex functions, it is necessary to define auxiliary\r
variables. There are two ways of doing this in SCL. The first way is\r
`where` syntax:\r
~~~\r
> dist x1 y1 x2 y2 = sqrt (dx*dx + dy*dy)\r
    where\r
      dx = x1-x2\r
      dy = y1-y2      \r
~~~\r
The second way is `do` syntax\r
~~~\r
> dist x1 y1 x2 y2 = do\r
      dx = x1-x2\r
      dy = y1-y2\r
      sqrt (dx*dx + dy*dy)      \r
~~~\r
The difference between these constructs is often only aesthetic.\r
\r
One feature of SCL that is imporant here is that SCL uses\r
the layout (indentation) of the code for parsing. The statements\r
in the same `where` or `do` block must be consistently\r
indented and indentation must be larger than the enclosing context.\r
\r
\r
----\r
\r
SCL standard library defines the following functions for\r
manipulating functions:\r
<table><tr><td>\r
id </td><td> a -> a </td><td> identity function </td></tr><tr><td>\r
(\$) </td><td> (a -> <e> b) -> a -> <e> b </td><td> application operator </td></tr><tr><td>\r
(.) </td><td> (b -> <e> c) -> (a -> <e> b) -> (a -> <e> c) </td><td> function composition </td></tr><tr><td>\r
const </td><td> a -> b -> a </td><td> constant function </td></tr><tr><td>\r
curry </td><td> ((a, b) -> <e> c) -> a -> b -> <e> c </td><td> give function parameters separately instead of a pair </td></tr><tr><td>\r
uncurry </td><td> (a -> b -> <e> c) -> ((a, b) -> <e> c)  </td><td> inverse of curry </td></tr><tr><td>\r
curry3 </td><td> ((a, b, c) -> <e> d) -> a -> b -> c -> <e> d  </td><td> give function parameters separately instead of a tripl </td></tr><tr><td>\r
uncurry3 </td><td> (a -> b -> c -> <e> d) -> ((a, b, c) -> <e> d) </td><td> inverse of curry3  </td></tr><tr><td>\r
flip </td><td> (a -> b -> <e> c) -> b -> a -> <e> c </td><td> flips the order of the function parameters\r
</td></tr></table>\r
Function `$` just applies given function and a parameter:\r
\r
~~~\r
f $ x = f x\r
~~~\r
\r
The precedence of the operator is very weak and it associates\r
to right. It can be used\r
to remove some parentheses in deeply nested expression. So\r
we can write\r
\r
~~~\r
> text = "Lorem ipsum dolor sit amet, consectetur adipiscing elit."\r
> length \r
    $ filter (\s -> length s > 4) \r
    $ splitString text "[ ,.]"\r
5\r
~~~\r
\r
instead of\r
\r
~~~\r
> length (filter (\s -> length s > 4) (splitString text "[ ,.]"))\r
5\r
~~~\r
\r
\r
## Data structures\r
\r
----\r
One of the simplest data structure is a pair:\r
~~~\r
> ("Citizen Kane", 1941)\r
("Citizen Kane", 1941)\r
~~~\r
As seen above, the different elements of the pair can have different types. \r
\r
The components of the pair can be accessed with the functions `fst` and `snd`:\r
~~~\r
> fst ("Citizen Kane", 1941)\r
"Citizen Kane"\r
> snd ("Citizen Kane", 1941)\r
1941\r
~~~\r
\r
Other tuple lenghts are also supported:\r
~~~\r
> ()\r
()\r
> ("1", 1, 1.0)\r
("1", 1, 1.0)\r
~~~\r
\r
\r
----\r
Pairs and other tuples are useful, when we want to return more than one value from a function:\r
~~~\r
> toPolarCoordinates (x,y) = (sqrt (x*x + y*y), atan2 y x)\r
> toRectangularCoordinates (r,angle) = (r*cos angle, r*sin angle)\r
> polar = toPolarCoordinates (3,-6)\r
> polar\r
(6.708203932499369, -1.1071487177940904)\r
> toRectangularCoordinates polar\r
(3.000000000000001, -6.0)\r
~~~\r
\r
As seen in the above example, when tuples are given as parameters to the functions, they can\r
be pattern matched. In `toPolarCoordinates (x,y)` the components of the pair given\r
as a parameter to the function are bound to `x` and `y`. \r
A much less readable version of the above function would be:\r
~~~\r
> toPolarCoordinates p = (sqrt (fst p*fst p + snd p*snd p), \r
                          atan2 (snd p) (fst p))\r
~~~\r
\r
Patterns can be nested. A nonsensical example: \r
~~~\r
> shuffle ((a,b), (c,d)) = ((c,b), (a,d))\r
> shuffle ((1,2), (3,4))\r
((3, 2), (1, 4))\r
~~~\r
\r
\r
----\r
### Remark\r
The following command produces an error ``Expected $\langle$Integer$\rangle$ got $\langle$String$\rangle$\r
~~~\r
> shuffle (("1","2"), ("3","4"))\r
~~~\r
althought the function definition doesn't seem to care about the contents of the values (even if they are all of different types).\r
This is a restriction of the current version of SCL Console: all functions you define are *monomorphic* meaning\r
that all types involved must be fully known. When this is not a case, the compiler chooses the types somewhat arbitrarily.\r
In SCL modules, there is no such restrictions and the compiler chooses the most generic type as possible for a function.\r
Therefore, if the `shuffle` were defined in a SCL module, the above command would work.\r
\r
----\r
Maybe the most important datatype is a list that may \r
hold any number of values of the same type. Lists\r
are constructed by enclosing the values in brackets:  \r
~~~\r
> [1, 2, 3, 4]\r
[1, 2, 3, 4]\r
~~~\r
\r
Elements of the lists are accessed with `!` operator:\r
~~~\r
> l = [1, 2, 3]\r
> l!0\r
1\r
> l!2\r
3\r
~~~\r
The length of the list can be found out with `length`:\r
~~~\r
> length l\r
3\r
~~~\r
\r
Two lists are joined together with `+` operator:\r
~~~\r
> [1, 2] + [3, 4]\r
[1, 2, 3, 4]\r
~~~\r
\r
Finally, a list containing some range of integers can be constructed as\r
~~~\r
> [4..9]\r
[4, 5, 6, 7, 8, 9]\r
~~~\r
\r
\r
----\r
### Exercise\r
A quadratic equation $a x^2 + b x + c = 0$ has real solutions only if the discriminant\r
$\Delta = b^2 - 4ac$ is non-negative. If it is zero, the equation has one solution and\r
if it is positive, the equation has two solutions:\r
$${-b \pm \sqrt{\Delta} \over 2a}.$$\r
Write a function $`solveQuadratic`$ that solves a quadratic function whose\r
coefficients are given as parameters and returns a list containing all solutions\r
of the equation:\r
~~~\r
> solveQuadratic 1 1 (-2)\r
[1.0, -2.0]\r
> solveQuadratic 1 1 1\r
[]\r
~~~\r
\r
\r
----\r
Many useful tools for manipulating lists are higher order functions.\r
The function `map` applies a given function to all elements of a list\r
and produces a new list of the same length from the results:\r
$$`map`\ f\ [x_1,x_2,\ldots,x_n] = [f\ x_1,f\ x_2,\ldots,f\ x_n]$$\r
Here is couple of examples:\r
~~~\r
> map (\s -> "_" + s + "_") ["a", "b", "c"]\r
["_a_", "_b_", "_c_"]\r
> map ((*) 3) [1..4]\r
[3, 6, 9, 12]\r
~~~\r
\r
Unwanted elements can be removed from a list by `filter` function:\r
~~~\r
> filter (\s -> length s > 4) ["small", "big", "large", "tiny"]\r
["small", "large"]\r
> isPrime p = filter (\d -> p `mod` d == 0) [2..p-1] == []\r
> filter isPrime [2..20]\r
[2, 3, 5, 7, 11, 13, 17, 19]\r
~~~\r
\r
The function `foldl` computes an aggergate value over a list of values\r
by applying a binary function to the elements starting from the given initial element:\r
$${\tt foldl}\ (\oplus)\ x_0\ [x_1,x_2,\ldots,x_n] = (\cdots((x_0 \oplus x_1) \oplus x_2) \oplus \cdots \oplus x_n)$$\r
In practice:\r
~~~\r
> foldl (+) 0 [2,3,4]\r
9\r
> foldl (*) 1 [2,3,4]\r
24\r
> foldl max 0 [2,3,4]\r
4\r
~~~\r
The function `sum` is equivalent to `foldl (+) zero`, but is in \r
some cases implemented much more effeciently (for example for strings).\r
\r
The function `concatMap` is similar to `map`, but it assumes\r
that the given function produces lists and concatenates the lists together:\r
~~~\r
> concatMap \r
      (\(n,v) -> map (const v) [1..n]) \r
      [(3,"a"), (2,"l"), (1,"i")]\r
["a", "a", "a", "l", "l", "i"]\r
~~~\r
\r
\r
----\r
### Exercise\r
Define a generalized average function for lists:\r
$${\rm avgG}\ p\ [x_1,\ldots,x_{n}] = \left({x_1^p + \cdots + x_n^p \over n}\right)^{1 \over p}$$\r
\r
\r
----\r
### Exercise\r
One useful way for producing lists is to map a range expression. For example\r
~~~\r
> diffs (l :: [Integer]) = map (\i -> l!(i+1) - l!i) [0..length l-2]\r
> diffs [1,2,4,8,3]\r
[1, 2, 4, -5]\r
~~~\r
Use the pattern to reimplement the function `reverse` from the standard library\r
that reverses the order of elements in a list.\r
\r
\r
----\r
SCL supports *list comprehension* which allows to write\r
many list producing expressions with a syntax that closely\r
resembles the set comprehension from mathematics:\r
~~~\r
> l = [1..3]\r
> [2*x | x <- l]\r
[2, 4, 6]\r
> [(x,y) | x <- l, y <- l]\r
[(1, 1), (1, 2), (1, 3), (2, 1), (2, 2), (2, 3), (3, 1), (3, 2), (3, 3)]\r
> [(x,y) | x <- l, y <- l, x < y]\r
[(1, 2), (1, 3), (2, 3)]\r
> [(x,y) | x <- l, y=4-x]\r
[(1, 3), (2, 2), (3, 1)]\r
~~~\r
As seen in the above examples, the left side of the vertical bar \r
can be any expression producing the elements of the list. The\r
right side of the bar is a list of producing statements:\r
`x <- l` considers all `x` in the list `l`,\r
`x = e` sets the value of `x` by the expression `e`\r
and any boolean expression like `x < y` filters the produced elements.\r
\r
\r
----\r
### Remark\r
SCL does not support yet pattern matching of lists althought it is supported in Haskell. \r
\r
\r
----\r
This is a list of some list functions provided by SCL standard library:\r
\r
\r
<table><tr><td>\r
map </td><td> Functor a => (a -> b) -> f a -> f b </td><td> </td></tr><tr><td>\r
concatMap </td><td> (a -> <e> [b]) -> [a] -> <e> [b] </td><td> </td></tr><tr><td>\r
filter </td><td> (a -> <e> Boolean) -> [a] -> <e> [a] </td><td> </td></tr><tr><td>\r
filterJust </td><td> [Maybe a] -> [a] </td><td> </td></tr><tr><td>\r
foldl </td><td> (a -> b -> <e> a) -> a -> [b] -> <e> a </td><td> apply the given binary operation from left to right </td></tr><tr><td>\r
foldl1 </td><td> (a -> a -> <e> a) -> [a] -> <e> a </td><td> </td></tr><tr><td>\r
unfoldl </td><td> (b -> <e> Maybe (a, b)) -> b -> <e> [a] </td><td> </td></tr><tr><td>\r
unfoldr </td><td> (b -> <e> Maybe (a, b)) -> b -> <e> [a] </td><td> </td></tr><tr><td>\r
zip </td><td> [a] -> [b] -> [(a,b)] </td><td> combine elements in the two lists </td></tr><tr><td>\r
zipWith </td><td> (a -> b -> <e> c) -> [a] -> [b] -> <e> [c] </td><td> </td></tr><tr><td>\r
unzip </td><td> [(a,b)] -> ([a],[b]) </td><td> </td></tr><tr><td>\r
sort </td><td> Ord a => [a] -> [a] </td><td> sorts the elements in the list </td></tr><tr><td>\r
sortBy </td><td> Ord b => (a -> <e> b) -> [a] -> <e> [a] </td><td> sorts the elements by a given criteria </td></tr><tr><td>\r
sortWith </td><td> (a -> a -> <e> Integer) -> [a] -> <e> [a] </td><td> sorts the elements by a given comparison function </td></tr><tr><td>\r
(\\) </td><td> Eq a => [a] -> [a] -> [a] </td><td> removes from the first list the elements that occur in the second list </td></tr><tr><td>\r
range </td><td> Integer -> Integer -> [Integer] </td><td> </td></tr><tr><td>\r
reverse </td><td> [a] -> [a] </td><td> reverses the order of the elements in the list </td></tr><tr><td>\r
take </td><td> Integer -> [a] -> [a] </td><td> returns $n$ first elements of the list </td></tr><tr><td>\r
drop </td><td> Integer -> [a] -> [a] </td><td> removes $n$ first elements from the list and returns the tail </td></tr><tr><td>\r
lookup </td><td>  Eq a => a -> [(a, b)] -> Maybe b </td><td> finds a pair from the list such that the first component\r
                                             matches the given value and returns the second component </td></tr><tr><td>\r
and </td><td> [Boolean] -> Boolean </td><td> </td></tr><tr><td>\r
or </td><td> [Boolean] -> Boolean </td><td> </td></tr><tr><td>\r
any </td><td> (a -> <e> Boolean) -> [a] -> <e> Boolean </td><td> </td></tr><tr><td>\r
all </td><td> (a -> <e> Boolean) -> [a] -> <e> Boolean \r
</td></tr></table>\r
\r
\r
----\r
One data structure used quite often is an optional value.\r
It is useful, if the function produces the result only for\r
some parameter values. Optional value is either \r
`Just value` or `Nothing`. Here is an example:\r
~~~\r
> safeSqrt x | x >= 0    = Just (sqrt x)\r
             | otherwise = Nothing\r
> safeSqrt 2\r
Just 1.4142135623730951\r
> safeSqrt (-2)\r
Nothing   \r
~~~\r
The type of the expressions  `Just value` and `Nothing` is `Maybe t`,\r
where $`t`$ is the type of `value`.\r
\r
Optional values can be handled with pattern matching\r
(the example is from the standard library):\r
~~~\r
> fromMaybe _ (Just value)  = value\r
  fromMaybe default Nothing = default\r
~~~\r
\r
\r
----\r
Sometimes it is useful to use pattern matching without\r
defining a new function for it. Therefore there is\r
`match` construct:\r
~~~\r
> match (1,2,3) with\r
     (x,y,z) -> x+y+z\r
6\r
~~~\r
As with functions, there can be multiple cases and the\r
first matching case is chosen:\r
~~~\r
> match safeSqrt 3 with\r
      Just v  -> v\r
      Nothing -> fail "Something bad happened." \r
~~~\r
\r
## Types\r
\r
----\r
\r
Every expression in SCL has a type. Type determines the set of possible values\r
of the expression. They are used for detecting errors in SCL code, for choosing the\r
right implementation of a method (for example addition `(+)`) and for generating\r
efficient byte code.\r
\r
When the type is monomorphic (does not contain type variables), it can be printed as\r
~~~\r
> typeOf "foo"\r
String\r
> typeOf [1,2,3]\r
[Integer]\r
~~~\r
 \r
\r
----\r
Normally SCL compiler will infer the types of the expressions automatically and\r
you don't have to specify them manually. There are however situations where\r
explicit control of types is useful:\r
* You want to document the interface of your functions. It is good practice\r
  to write a type annotation for all top-level functions declared in a SCL module.\r
  Such declarations are not available in SCL Console: \r
  ~~~\r
  fst :: (a,b) -> a\r
  fst (x,y) = x\r
  ~~~\r
* SCL compiler cannot infer a type that satisfies all the required constraints:\r
  ~~~\r
  > strId x = show (read x)\r
  There is no instance for <Show ?a>.\r
  There is no instance for <Read ?a>.\r
  > strId x = show (read x :: Integer)\r
  > strId "1"\r
  "1"\r
  > strId "1.0"\r
  java.lang.NumberFormatException: For input string: "1.0"\r
  ...\r
  > strId x = show (read x :: Double)\r
  > strId "1"\r
  "1.0"\r
  > strId "1.0"\r
  "1.0"\r
  ~~~\r
  The type annotation is needed here, because `read` parses a string\r
  to a certain type of values, `show` converts it back to string,\r
  and the behavior of the composition depends on what the intermediate type is.\r
  There is however not enough information for the compiler to infer the type\r
  (it is shown as `?a` in the error message). \r
* Code specialized to a certain type may be more efficient than a generic code\r
  that applies to all data types.\r
A type of an expression or identifier is annotated by adding `::` and a type\r
expression after it. Type annotations may also be used in patterns:\r
~~~\r
sign (x :: Double) = compare x 0 \r
~~~\r
\r
\r
----\r
The following types (or more exactly, type constructors) are built in the SCL compiler:\r
* `Boolean`\r
* `Byte`, `Short`, `Integer`, `Long`\r
* `Float`, `Double`\r
* `String`\r
* `[]`\r
* `()`, `(,)`, `(,,)`, ...\r
* `(->)`\r
* `Maybe`\r
* `Array`\r
* `BooleanArray`, `ByteArray`, `ShortArray`, \r
  `IntegerArray`, `LongArray`, `FloatArray`, `DoubleArray`\r
\r
Other type constructors are defined in SCL modules, either importing them from Java\r
or using `data` declaration.\r
Except for the couple of special cases in the previous list, the names of \r
all type constructors are capitalized.\r
\r
Some type constructors are parametric (compare to generics in Java or templates in C++).\r
For example, the list type constructor `[]` has one parameter: the type of the list\r
elements. Thus `[Integer]` is the type of the integer lists and `[String]` \r
is the type of string lists. \r
`[[Integer]]` is the type of the lists of integer\r
lists. Parameters are usually written after the parametric type constructor: \r
for example `Maybe Integer` or `Array String`, but some of the builtin type \r
constructors can be written in a special way in order to make the type \r
expressions more readable:\r
~~~\r
[a] = [] a\r
(a,b) = (,) a b\r
(a,b,c) = (,,) a b c\r
...\r
a -> b = (->) a b\r
~~~\r
\r
Particularly important type constructor is `(->)` for building function types.\r
For example, the type of the function computing the length of a string is `String -> Integer`: \r
the function takes a string as a parameter and returns an integer.\r
\r
Types of the functions taking multiple parameters are written by composing function types. \r
For example, the type of a function taking nth element of a string list is \r
`[String] -> Integer -> String`. The function takes a string list and an integer as\r
a parameter and returns a string. Function type operator `->` is right associative\r
thus the previous type is equivalent to `[String] -> (Integer -> String)`. \r
Thus the type expression can be read as well as a type of functions taking a string\r
list and returning another function from integers and strings.\r
\r
`(a,b)` is the type of pairs where the first component of the pair has type `a`\r
and the second component has type `b`. Tuple types `(a,b,c)`, `(a,b,c,d)` etc. \r
are defined similarly. `Maybe a` is the type of optional values.\r
\r
\r
----\r
Many functions can be defined so that they do not need to know the exact types they are operating with.\r
Such unknown types can be filled in type expressions by type variables: for example the function\r
we discussed earlier that took nth element of a string list does not need the information that\r
list elements are strings in its implementation and so it can be given a more generic type\r
`[a] -> Integer -> a`, i.e a function taking a list of `a`:s and an integer as a parameter\r
and returning a single `a`.\r
\r
Type variables may also refer to parametric types, but all useful examples involve type constraints we describe below.\r
\r
\r
----\r
### Exercise*\r
\r
Function types with type variables tell quite much about the function assuming it is total,\r
i.e does not hang or throw a runtime exception with any parameters. Write the *unique*\r
functions with the following type signatures:\r
~~~\r
a -> a\r
(a,b) -> (b,a)\r
~~~\r
Write all possible functions with the following type signatures:\r
~~~\r
a -> a -> a\r
~~~\r
\r
Because SCL Console does not support definition of functions with generic types,\r
this exercise can be done only by writing your own SCL module.\r
\r
----\r
SCL does not support function overloading at least in the way Java and C++ support it.\r
This means that every function has a unique type signature. Now consider the addition function\r
`(+)`. We could defined its signature for example as `Integer -> Integer -> Integer`,\r
but then we would need some other name for the sum of doubles `Double -> Double -> Double` or\r
strings `String -> String -> String`. It would seem like the right signature would be\r
`a -> a -> a`, but that is not satisfactory either, because then the function had to\r
somehow support all possible types. \r
\r
The solution to the problem is to constraint the set of allowed types for the type variable.\r
Such a constrained type is written in the case of addition function as\r
`Additive a => a -> a -> a`. The constraint `Additive a` is composed of a type class\r
`Additive` followed by parameters of the constraint. \r
The type can be understood in two different ways. A logical reading is\r
> For any additive type `a`, the function takes two `a`:s as parameters and returns `a`.\r
and an operational reading that gives a good intuition what is happening in runtime\r
>  The function takes a parameter `Additive a` that describes a set of methods that can be used to operate the values of `a` and two `a`:s and returns `a`.\r
\r
Constrained type variable can also be parametric. For example, let's say we want to define a function getNth that takes nth element of a list but also works with arrays. The signature would then be\r
~~~\r
getNth :: Sequence s => s a -> Integer -> a\r
~~~\r
\r
Type classes form a hierarchy: each class may have any number of superclasses. Only the most specific type class is needed in the constraints. For example, addition and multiplication have the following signatures:\r
~~~\r
(+) :: Additive a => a -> a -> a\r
(*) :: Ring a => a -> a -> a\r
~~~\r
and Additive is a superclass of Ring a. A function using both operators need to specify only Ring as a constraint:\r
~~~\r
doubleAndAddOne :: Ring a => a -> a\r
doubleAndAddOne x = 2*x + 1\r
~~~\r
\r
This is a hierarchy of ``numerical'' type classes defined in the standard library of SCL:\r
\r
\includegraphics[scale=0.6]{figures/TypeClasses.png}\r
\r
The white boxes are type classes. An open arrow between type classes is the inheritance between type classes.\r
The yellow boxes are types defined in the standard library. They are connected to the type classes\r
they belong to.\r
\r
There are also type classes for converting values to strings `Show` and vice versa `Read`.\r
Types in the type class `Hashable` provide a method to compute a hash code.\r
Types in the type class `Serializable` can be serialized to a byte array and deserialized back to a value.\r
There are also some type classes that make programming with different containers more generic:\r
`Functor`, `Monad`, etc. \r
\r
\r
----\r
SCL functions are referentially transparent which means that they are like\r
mathematical functions always returning the same value for the same parameters\r
and not causing any observable side-effects. This seems extremely restrictive\r
because most of the programs are written in order to generate some kind of\r
side-effects and even completely mathematical algorithms involve functions\r
that are not referentially transparent such as generation of random numbers.\r
\r
This policy does not however restrict expressive power of the language because\r
functions can return and manipulate *descriptions of computations*.\r
These computations are then executed by some external means.\r
Two different ways of handling computations in SCL are monads and effect types.\r
Effect types are not applicable to as large range of different\r
computation concepts as monads are but they are easier to work with.\r
\r
An effectful computation has type `<effects> t`.\r
The type after angle brackets is the type of the value obtained by the computation.\r
Side-effects that might happen during the computation are listed inside of angle brackets.\r
Effect types must always occur as a return type of a function. Here are some examples (some fictional) \r
of functions with side-effects:\r
~~~\r
randomBetween :: Double -> Double -> <Nondet> Double\r
resource :: String -> <ReadGraph> Resource\r
claim :: Resource -> Resource -> Resource -> <WriteGraph> ()\r
randomLiteral :: Double -> Double -> <Nondet,WriteGraph> Resource\r
~~~\r
\r
Effect types are much like type constraints: you can mostly ignore them when using functions.\r
All effects you use are automatically collected and added to the type signature of the defined\r
function (or checked against type annotation if provided).\r
\r
Like type classes, effects form a hierarchy. For example WriteGraph inherits ReadGraph\r
and a function both reading and writing to graph is annotated only with `<WriteGraph>` effect.\r
\r
Like types, effects can also be abstracted with effect variables. This is important when defining generic\r
functions that manipulate possibly effectful functions:\r
~~~\r
executeTwice :: (() -> <e> ()) -> <e> ()\r
executeTwice f = do f () ; f ()\r
\r
(.) :: (b -> <e2> c) -> (a -> <e1> b) -> (a -> <e1,e2> c)\r
(f . g) x = f (g x)\r
~~~\r
\r
\r
----\r
### Exercise\r
Revisit the earlier lessons listing library functions and their types. \r
Can you now understand all the type signatures?\r
\r
\r
## Side-effects\r
\r
----\r
So far our examples have used pure functions without side effects.\r
There are indeed quite few functions in the standard library producing\r
side effects. One of them is the printing function: \r
~~~\r
> print "Hello world!"\r
Hello world!\r
~~~\r
\r
Side-effectful function applications can be sequenced \r
in a `do` block:\r
~~~\r
> do print "Hello,"\r
     print "    World!"\r
Hello,\r
    World!     \r
~~~\r
\r
----\r
It is very typical that we want to cause some effect for\r
every element of some list. For that purpose there is a function `for`:\r
~~~\r
> for [1..3] print\r
1\r
2\r
3\r
~~~\r
\r
Here is a little more complicated example:\r
~~~\r
> items = ["patridge in a pear tree", "turtle doves",\r
           "french hens", "colly birds", "gold rings",\r
           "geese-a-laying", "swans-a-swimming", "maids-a-milking",\r
           "ladies dancing", "lords-a-leaping", "pipers piping",\r
           "drummers drumming"]\r
> numbers = ["and a", "two", "three", "four", "five", "six",\r
             "seven", "eight", "nine", "ten", "eleven", "twelve"]\r
> printVerse n = do\r
      print "On the twelfth day of Christmas, my true love gave to me"\r
      for [1..n] (\i -> do\r
          c = n-i\r
          print $ (if n==1 then "a" else numbers!c) + " " + items!c\r
      )\r
      print ""\r
> for [1..12] printVerse\r
...\r
~~~\r
\r
\r
----\r
### Exercise\r
Procude the lyrics of the song ``99 Bottles of Beer''\r
<http://www.99-bottles-of-beer.net/lyrics.html>.\r
\r
\r
----\r
Sometimes it is useful to introduce a state that can be modified\r
during an algorithm. Such a state is created with function `ref`,\r
it is accessed with `getReg` and modified with `(:=)` operator:\r
~~~\r
> nRef = ref 1\r
> for [1..8] (\_ -> do \r
      n = getRef nRef\r
      print n\r
      nRef := 2*n\r
  )\r
1\r
2\r
4\r
8\r
16\r
32\r
64\r
128\r
~~~\r
\r
\r
----\r
### Exercise\r
Reproduce the `gcd` function by using modifible state.\r
\r
\r
----\r
This is a partial list of functions in the standard library producing side-effects:\r
\setlength\LTleft{-2cm}\r
<table><tr><td>\r
for </td><td> FunctorE f => f a -> (a -> <e> ()) -> <e> () </td><td> executes the given function with every element in the structure </td></tr><tr><td>\r
print </td><td> Show a => a -> <Proc> () </td><td> prints the given value </td></tr><tr><td>\r
ref </td><td> a -> <Proc> (Ref a) </td><td> creates a state </td></tr><tr><td>\r
getRef </td><td> Ref a -> <Proc> a </td><td> accesses a state </td></tr><tr><td>\r
(:=) </td><td> Ref a -> a -> <Proc> () </td><td> modifies the state </td></tr><tr><td>\r
newArrayList </td><td> () -> <Proc> ArrayList a </td><td> creates an array list </td></tr><tr><td>\r
addArrayList </td><td> ArrayList a -> a -> <Proc> () </td><td> add an element at the end of the list </td></tr><tr><td>\r
getArrayList </td><td> ArrayList a -> Integer -> <Proc> a </td><td> gets an element from the list </td></tr><tr><td>\r
lengthArrayList </td><td> ArrayList a -> <Proc> Integer </td><td> returns the current lenght of the list </td></tr><tr><td>\r
freezeArrayList </td><td> ArrayList a -> <Proc> [a] </td><td> freezes the list and returns the corresponding immutable list\r
</td></tr></table>\r
\r
\r
## Browsing Simantics database\r
\r
----\r
The functionality we have used so far has been readily available in the console.\r
There is also functionality that must be imported before using:\r
~~~\r
> import "Simantics/Ontologies"\r
~~~\r
The string `Simantics/Ontologies` is the name of the *SCL module* that is imported.\r
We assume that the import command is excuted in the rest of this section. \r
\r
\r
----\r
In order to browse the database more conveniently, let's define some helper functions.\r
~~~\r
> nameOfResource r = match possibleRelatedValue r L0.HasName with\r
    Just name -> name\r
    Nothing -> "no name"\r
> printNames (rs :: [Resource]) = \r
      for rs (\r -> print $ nameOfResource r)    \r
> findEntities (p :: Resource -> <ReadGraph> Boolean) = findRecursively\r
    where\r
      findRecursively r = do \r
          children = concatMap findRecursively $ immediateChildren r\r
          if p r\r
          then [r] + children\r
          else children\r
      immediateChildren s = s # L0.ConsistsOf     \r
> findByType t = findEntities (flip isInstanceOf t)\r
> aprosOntologies = resource "http://www.apros.fi"\r
> project = currentProject ()\r
~~~\r
\r
Now we can find all connection types defined in the Apros ontologies:\r
~~~\r
> printNames $ findByType STR.ConnectionType aprosOntologies\r
PipelineStructureConnectionType\r
...\r
ElectricalNameReferenceConnectionType\r
~~~\r
Find all module types:\r
~~~\r
> import "http://www.apros.fi/Apros-6.1" as APROS\r
> printNames $ findByType APROS.AprosModuleType aprosOntologies\r
~~~\r
Show all pipes in the workspace with their lengths:\r
~~~\r
> import "http://www.apros.fi/Combustion/Configuration-6.0/ModuleTypes" \r
         as MT\r
> import "http://www.apros.fi/Combustion/Configuration-6.0/Relations" \r
         as REL\r
> for (findByType MT.PIPE project) (\pipe ->\r
      print $ nameOfResource pipe + " " + \r
              show (relatedValue pipe REL.PI12_LENGTH :: Float)      \r
  )\r
~~~\r
Find all modules that are not connected anywhere:\r
~~~\r
> isUnconnected r = not (existsStatement r STR.IsConnectedTo \r
                      || existsStatement r APROS.AttachedModule)\r
> printNames $ filter isUnconnected \r
             $ findByType APROS.AprosModule project\r
~~~\r
\r
\r
----\r
This is a list of most important database accessing functions (the\r
type `Resource` is abbreviated as `Res` in the type signatures):\r
\setlength\LTleft{-4cm}\r
<table><tr><td>\r
resource </td><td> String -> <ReadGraph> Res </td><td> the resource with the given URI </td></tr><tr><td>\r
uriOf </td><td> Res -> <ReadGraph> String </td><td> the URI of the given resource </td></tr><tr><td>\r
(\#) </td><td> Res -> Res -> <ReadGraph> [Res] </td><td> returns all objects for given subject and predicate </td></tr><tr><td>\r
existsStatement </td><td> Res -> Res -> <ReadGraph> Boolean </td><td> returns true, if there is a statement with the given subject and predicate  </td></tr><tr><td>\r
singleObject </td><td> Res -> Res -> <ReadGraph> Res </td><td> returns the unique object with the given subject and predicate </td></tr><tr><td>\r
possibleObject </td><td> Res -> Res -> <ReadGraph> Maybe Res </td><td> returns a possible object with the given subject and predicate </td></tr><tr><td>\r
valueOf </td><td> Serializable a => Res -> <ReadGraph> a </td><td> reads a value associated with a resource </td></tr><tr><td>\r
relatedValue </td><td> Serializable a => Res -> Res -> <ReadGraph> a </td><td> reads a property </td></tr><tr><td>\r
possibleRelatedValue </td><td> Serializable a => Res -> Res -> <ReadGraph> Maybe a </td><td> reads a possibly existing property </td></tr><tr><td>\r
inverseOf </td><td> Res -> <ReadGraph> Res </td><td> inverse of a relation </td></tr><tr><td>\r
singleTypeOf </td><td> Res -> Res -> <ReadGraph> Res </td><td> the unique type of the resource inheriting the given type </td></tr><tr><td>\r
possibleTypeOf </td><td> Res -> Res -> <ReadGraph> Maybe Res </td><td> a possible type of the resource inheriting the given type </td></tr><tr><td> \r
isInstanceOf </td><td> Res -> Res -> <ReadGraph> Boolean </td><td> tests if a resource is an instance of the given type </td></tr><tr><td>\r
isSubrelationOf </td><td> Res -> Res -> <ReadGraph> Boolean </td><td> tests if a resource is a subrelation of a given relation </td></tr><tr><td>\r
isInheritedFrom </td><td> Res -> Res -> <ReadGraph> Boolean </td><td> tests if a resource is a subtype of a given type </td></tr><tr><td>\r
claim </td><td> Res -> Res -> Res -> <WriteGraph> () </td><td> adds a statement </td></tr><tr><td>\r
deny </td><td> Res -> Res -> Res -> <WriteGraph> () </td><td> removes a statement </td></tr><tr><td>\r
claimRelatedValue </td><td> Serializable a => Res -> Res -> a -> <WriteGraph> () </td><td> sets the value of a property </td></tr><tr><td>\r
syncRead </td><td> (() -> <Proc,ReadGraph> a) -> <Proc> a </td><td> makes a read request </td></tr><tr><td>\r
syncWrite </td><td> (() -> <Proc,ReadGraph,WriteGraph> a) -> <Proc> a </td><td> makes a write request\r
</td></tr></table>\r
\r
\r
## Manipulating diagrams\r
\r
----\r
Diagrams could be in principle manipulated with the set of primitive\r
graph functions introduced in the previous section. There is however\r
some tools available to work with diagrams at a higher level. \r
Therefore we need for this section the following imports:\r
~~~\r
> import "Simantics/Diagram"\r
> import "http://www.apros.fi/Apros-6.1" as APROS\r
> import "http://www.apros.fi/Combustion/Configuration-6.0/Relations" \r
         as REL\r
> import "http://www.apros.fi/Combustion/Diagram-6.0/Symbols" \r
         as SYMBOLS          \r
> import "http://www.apros.fi/Combustion/Diagram-6.0/Relations" \r
         as CPS\r
~~~\r
\r
For this section you should also create a model with (default) name Model\r
and a new diagram to that model with (default) name NewGenericDiagram. If\r
you want to change these names, you should also change the code\r
examples accordingly. Populate the diagram with couple of elements and\r
connect them together.\r
\r
\r
----\r
We show first how to read the diagram contents:\r
~~~\r
> dia = diagram (model "Model") ["NewGenericDiagram"]\r
> for (elementsOfR dia) print\r
(Connection [Terminal "SP_01" #221240, Terminal "MU_01" #218187] [Edge 0 1] (Just "XA_02"), #450761)\r
(Component #217233 "SP_01" (Position ...) [Property #137577, ...], #450756)\r
(Component #217663 "MU_01" (Position ...) [Property #144599, ...], #450751)\r
~~~\r
The actual result depends on how you have populated your diagram.\r
\r
The result is not very readable because of all the resource identifiers. \r
Let's write a pretty-printing function:\r
~~~\r
> printElement ((Component t n pos props),_) = do\r
    print $ n + " :: " + nameOfResource t\r
    print $ "    " + show pos\r
    for props (\(Property relation value) ->\r
        print $ "    " + nameOfResource relation + " " + show value\r
    )\r
 printElement ((Connection nodes _ name),_) = do\r
    print $ "Connection " + \r
            (match name with Just n -> n ; Nothing -> "")\r
    printNode (Terminal element connectionPoint) = \r
        print $ "    " + element + " " + nameOfResource connectionPoint\r
    printNode otherwise = ()\r
    for nodes printNode\r
 printElement ((Flag t name _ _ _ _ _ pos _),_) = do\r
    print $ "Flag " + name + " :: " + nameOfResource t\r
    print $ "    " + show pos\r
 printElement (el,_) = print el // Use the default printing as a fallback \r
~~~\r
Now we get:\r
~~~>  \r
> for (elementsOfR dia) printElement\r
Connection XA_02\r
    SP_01 SP_OUTPUT_SIGN_1_1\r
    MU_01 MULTIPLYER_INPUT_SIGN_1_1\r
SP_01 :: SetpointS\r
    Position 1.0 0.0 0.0 1.0 94.0 115.0\r
    SP_VALUE 0.0\r
    SP_MINMAX_ON false\r
    SP_GRADIENT_UP 60.0\r
    SP_TRACKING_ON false\r
    SP_MIN 0.0\r
    SP_GRADIENT_DOWN -60.0\r
    SP_FAST_MODE_ON true\r
    SP_MAX 100.0\r
MU_01 :: Gain\r
    Position 1.0 0.0 0.0 1.0 104.0 115.0\r
    MULTIPLYER_BIAS 0.0\r
    MULTIPLYER_GAIN 1.0\r
    MULTIPLYER_OUTPUT 0.0\r
~~~\r
\r
\r
----\r
Next, let's create some new diagrams. We need two helper functions:\r
~~~\r
> aprosDiagram modelName diagramName = NewDiagram \r
      (model modelName) \r
      [diagramName]\r
      APROS.Folder\r
      APROS.GenericAprosComposite\r
> joinMap = createJoinMap ()\r
~~~\r
The first function creates a specification for a new diagram:\r
it describes the model where the diagram is created, the path\r
to the diagram, the type of folders in the path and finally\r
the type of the diagram itself. The second definition defines\r
a `joinMap` that is used for connecting diagrams together (by flags).\r
\r
Now we can write:\r
~~~\r
> newDia = fst $ createDiagramR (aprosDiagram "Model" "TestDiagram1") joinMap []\r
~~~\r
This should create a new diagram with name TestDiagram1. The\r
last parameter is the list of diagram elements. Because the list\r
is empty, our diagram is also empty.\r
\r
Easiest way to create some content is to copy it from another diagram:\r
~~~\r
> sortEls l = filter (not . isReferring) l + filter isReferring l\r
    where\r
      isReferring (Connection _ _ _) = True\r
      isReferring (SimpleConnection _ _ _ _ _) = True\r
      isReferring (Monitor _ _ _ _) = True\r
      isReferring otherwise = False\r
> els = sortEls $ map fst $ elementsOfR dia\r
> createDiagramR (ExistingDiagram newDia) joinMap els \r
~~~\r
This replaces the contents of TestDiagram1 by the contents of NewGenericDiagram.\r
The function `sortEls` is needed to work around a bug in `createDiagramR`\r
occurring if some element is created after another element that refers to it.\r
\r
\r
----\r
Usually we want to modify the contents of the diagram somehow before copying it.\r
Here are couple of example functions for transforming the elements:\r
~~~\r
> mapElementName f (Component t name pos props) =\r
      Component t (f name) pos props\r
  mapElementName f (Connection nodes edges possibleName) =\r
      Connection (map prefixNode nodes) edges (map f possibleName)\r
    where\r
      prefixNode (Terminal name cp) = Terminal (f name) cp\r
      prefixNode n = n\r
  mapElementName f (Flag t name label output external \r
                         ioBinding ioTableRowIndex pos refs) = \r
      Flag t (f name) label output external \r
           ioBinding ioTableRowIndex pos refs\r
  mapElementName f el = el // This is not yet a complete definition!\r
> moveElement delta (Component t name pos props) =\r
      Component t name (move delta pos) props\r
  moveElement delta (Connection nodes edges name) =\r
      Connection (map moveNode nodes) edges name\r
    where\r
      moveNode (RouteLine False pos) = RouteLine False (pos + fst delta)\r
      moveNode (RouteLine True pos) = RouteLine True (pos + snd delta)\r
      moveNode n = n\r
  moveElement delta (Flag t name label output external\r
                          ioBinding ioTableRowIndex pos refs) = \r
      Flag t name label output external \r
           ioBinding ioTableRowIndex (move delta pos) refs\r
  moveElement delta el = el // This is not yet a complete definition!\r
~~~\r
Now we can move the elements and add a prefix to them:  \r
~~~  \r
> modifiedEls = map (moveElement (20,20)) \r
              $ map (mapElementName ((+) "PREFIX_")) els\r
> createDiagramR (ExistingDiagram newDia) joinMap modifiedEls\r
~~~\r
\r
Finally, let's try making some clones of the elements:\r
~~~  \r
> modifiedEls = [ moveElement (dx,dy) $ mapElementName ((+) prefix) el\r
                | i <- [0..3]\r
                , j <- [0..3]\r
                , dx = 30 * fromInteger i\r
                , dy = 30 * fromInteger j\r
                , prefix = "P_" + show i + "_" + show j + "_"\r
                , el <- els] \r
> createDiagramR (ExistingDiagram newDia) joinMap modifiedEls\r
~~~\r
\r
\r
----\r
### Exercise\r
Write a function `createPipeline` that takes as a parameter\r
a diagram specification and a list of two-dimensional points\r
and creates a pipeline such that elevations of the points are\r
the second components of the points in the list, the lengths \r
of the points are the distances between successive points and\r
the diagram positions are based on the physical positions.\r
The following command should work: \r
~~~\r
> dia = ExistingDiagram (diagram (model "Model") ["TestDiagram1"])\r
> createPipeline dia [(1,1), (6,1), (10,5)]\r
~~~\r
\r
Hint: The following commands create a pipe and a point that are connected\r
together with point elevation and pipe lenght specified:   \r
~~~\r
> els = [\r
      Component SYMBOLS.Point "PO_01" (location 30 30) \r
                [Property REL.PO11_ELEV (toDynamic 10.0)],\r
      Component SYMBOLS.Pipe "PI_01" (location 40 30) \r
                [Property REL.PI12_LENGTH (toDynamic 5.0)],\r
      Connection [Terminal "PO_01" CPS.PointSelf,\r
                  Terminal "PI_01" CPS.PI12_CONNECT_POINT_1_1_1]\r
                  [Edge 0 1] Nothing\r
  ]\r
> createDiagramR dia joinMap els\r
~~~\r
\r
\r
----\r
### Remark\r
This is the data type definition of the diagram elements:\r
~~~\r
data DiagramElement res = \r
    Component\r
        res            // component type\r
        String         // name\r
        Position       // position\r
        [Property res] // properties\r
  | SimpleConnection String res String res (Maybe String)\r
  | Connection [ConnectionNode res] [Edge] (Maybe String)\r
  | Flag \r
        res \r
        String         // name \r
        String         // label\r
        Boolean        // output\r
        Boolean        // external\r
        (Maybe String)  // IOTableBinding\r
        (Maybe Integer) // IOTableRowIndex\r
        Position       // position  \r
        [Dynamic]      // references to the joins\r
  | SVG String Position\r
  | Monitor String (Maybe MonitorReference) MonitorVisuals Position\r
data Position = Position Double Double Double Double Double Double\r
data Property res = Property res Dynamic\r
data Edge = Edge Integer Integer\r
data ConnectionNode res = Terminal String res\r
                        | RouteLine\r
                              Boolean   // is horizontal\r
                              Double    // position\r
data Font = Font String Integer Integer\r
data Alignment = Baseline | Center\r
               | Leading | Trailing\r
data MonitorReference = MonitorReference String String\r
data MonitorVisuals = MonitorVisuals (Maybe Font) Double Alignment Alignment                              \r
~~~\r
\r
## Model queries\r
\r
----\r
In this section, we make queries and mass modifications to the components\r
of a model. For preliminaries, you need to run the import command:\r
~~~\r
import "Apros/ModelQueries"\r
~~~\r
\r
It defines the following functions:\r
~~~\r
forAllComponentsIn :: (Resource -> <e> a) -> Resource -> <ReadGraph,e> ()\r
forAllComponents ::  (Resource -> <e> a) -> <Proc,ReadGraph,e> ()\r
forComponentsIn :: (Resource -> <e> Boolean) -> Resource \r
                -> (Resource -> <e> a) -> <ReadGraph,e> ()\r
forComponents :: (Resource -> <e> Boolean) -> (Resource -> <e> a) -> <Proc,ReadGraph,e> ()\r
searchComponents :: (Resource -> <e> Boolean) -> <Proc,ReadGraph,e> [Resource]\r
searchComponentsIn :: (Resource -> <e> Boolean) -> Resource -> <ReadGraph,e> [Resource]\r
\r
nameSatisfies :: (String -> <e> Boolean) -> Resource -> <e,ReadGraph> Boolean\r
nameIs name = nameSatisfies (== name)\r
getName :: Resource -> <ReadGraph> String\r
\r
typeIs :: Resource -> Resource -> <ReadGraph> Boolean\r
\r
configurationValueSatisfies :: Serializable a => Resource -> (a -> <e> Boolean) \r
                            -> Resource -> <e,ReadGraph> Boolean\r
configurationValueIs :: Serializable a => Resource -> a \r
                     -> Resource -> <e,ReadGraph> Boolean\r
setConfigurationValue :: Serializable a => Resource -> a -> Resource -> <WriteGraph> ()\r
getConfigurationValue :: Serializable a => Resource -> Resource -> <ReadGraph> a\r
\r
stateValueSatisfies :: Serializable a => Resource -> (a -> <e> Boolean) \r
                    -> <ReadGraph> (Resource -> <e,ReadGraph> Boolean)\r
stateValueIs :: Serializable a => Resource -> a \r
             -> <ReadGraph> (Resource -> <e,ReadGraph> Boolean)\r
setStateValue :: Serializable a => Resource -> a\r
              -> <ReadGraph> (Resource -> <WriteGraph> ())\r
getStateValue :: Serializable a => Resource -> <ReadGraph> (Resource -> <ReadGraph> a)\r
\r
(&&&) :: Combinable a => a -> a -> a\r
instance Combinable (Resource -> <e> Boolean)\r
instance Combinable (Resource -> <e> ())\r
\r
printName :: Resource -> <ReadGraph,Proc> ()\r
row :: [Resource -> <e> String] -> (Resource -> <e> String)\r
~~~\r
\r
\r
----\r
The functions make it possible to define queries to the active\r
model of the form:\r
``for all components satisfying a condition execute an action.''\r
For example:\r
\r
1) Print the names of all points in the model:\r
    ~~~\r
   forComponents\r
       (typeIs MODULETYPES.POINT)\r
       printName\r
   ~~~ \r
2) Set area of pipe PIP01 to 0.0033\r
   ~~~\r
   forComponents\r
       (nameIs "PIP01")\r
       (setConfigurationValue ATTRIBUTES.PI12_AREA 0.2)\r
   ~~~\r
3) Find all pipes in the active model and set their area to 0.001 m2:\r
   ~~~\r
   forComponents\r
       (typeIs MODULETYPES.PIPE)\r
       (setConfigurationValue ATTRIBUTES.PI12_AREA (0.001 :: Float))\r
   ~~~\r
4) Find all pipes with area < 0.0001 m2 in the active model and set their area to 0.001 m2:\r
   ~~~\r
   forComponents\r
       (configurationValueSatisfies ATTRIBUTES.PI12_AREA (\(x :: Float) -> x < 0.0001))\r
       (setConfigurationValue ATTRIBUTES.PI12_AREA (0.001 :: Float))\r
   ~~~\r
5) Find all pipes with fluid section WSB and list their boron concentrations:\r
   ~~~\r
   forComponents\r
       (configurationValueIs ATTRIBUTES.PO11_SECTION_NAME "WSB")\r
       (print . row [getName, showFloat . getStateValue ATTRIBUTES.PO11_BOR_CONC])\r
   ~~~\r
6) Find all pipes with fluid section WS and set their fluid section to WSB:\r
   ~~~\r
   forComponents\r
       (configurationValueIs ATTRIBUTES.PO11_SECTION_NAME "WS")\r
       (setConfigurationValue ATTRIBUTES.PO11_SECTION_NAME "WSB")\r
   ~~~\r
7) Find all pipes in diagram Diagram2 and set their length to 123.45 m:\r
   ~~~\r
   forComponentsIn\r
         (typeIs MODULETYPES.PIPE)\r
         (resource "http://Projects/Development%20Project/Model/Configuration/Diagram2")\r
         (setConfigurationValue ATTRIBUTES.PI12_LENGTH (123.45 :: Float))\r
   ~~~  \r
\r
----\r
It is also possible to write the results of a query to a file.\r
~~~\r
printingToFile "c:/temp/componentListing.txt" (\r
    forComponents\r
        (configurationValueIs ATTRIBUTES.PO11_SECTION_NAME "WSB")\r
        (print . row [getName, showFloat . getStateValue ATTRIBUTES.PO11_BOR_CONC])\r
    )\r
~~~\r
\r
\r
# Further topics\r
\r
----\r
\r
If you start to use SCL more frequently and write your own helper functions,\r
it becomes quickly cumbersome to paste them every time into the console.\r
You can write a list of commands into a separate file and run it with the command\r
~~~\r
> runFromFile "c:/file/path"\r
~~~\r
Commands are separated from each other by indentation.\r
\r
Another way to store function definitions is to write your own modules.\r
It also frees you from some restrinctions of SCL Console.\r
You can write the module into a file, say `c:/scl/MyModule.scl`\r
and import it as:\r
~~~\r
> import "file:c:/scl/MyModule"\r
~~~\r
What makes working with modules harder than console commands is that\r
it is not so easy to update a module that you have already imported.\r
It is however possible by running:\r
~~~\r
> reset ""\r
~~~\r
that clears the whole SCL environment. After clearing the environment, you \r
have to reimport all the modules you want to use.\r
We will improve the situation in next versions of \r
the SCL environment.\r
\r
\r
----\r
There are many language features we have not touched in this tutorial.\r
Many of them are also in Haskell, so you can familize yourself with them\r
by reading Haskell tutorials:\r
* defining new data types,\r
* defining new type classes and their instances,\r
* defining binary operators, their associativity and precedence.\r
SCL supports also monads like Haskell. Only difference is that monadic\r
syntax uses keyword `mdo` instead of `do`. Althought\r
the importance of monads is lessen in SCL because of effect types,\r
they are still a useful concept to know. Monads are particularly\r
useful for building domain specific languages in SCL.\r
\r
\r
----\r
There are also couple of features that we have not described that\r
are specific to SCL:\r
* definition of new effect types\r
* syntax for importing Java code to SCL, for example:\r
  ~~~\r
  importJava "java.util.List" where\r
      @JavaName get\r
      (!) :: [a] -> Integer -> a\r
  \r
      @JavaName size\r
      length :: [a] -> Integer\r
  \r
      subList :: [a] -> Integer -> Integer -> [a]\r
  ~~~\r
* value annotations\r
  ~~~\r
  @inline\r
  curry :: ((a, b) -> <e> c) -> a -> b -> <e> c\r
  curry f x y =  f (x, y)\r
  \r
  @macro\r
  a && b = if a then b else False\r
  ~~~\r
\r
\r