docs/Developer/SCL/SCLTutorial.md

   1 ## Getting started
   2
   3 The easiest way of getting started with SCL is to use SCL console that is included in almost all Simantics-based products. You can open the console by pressing ALT-SHIFT-q and then q and choosing "SCL Console" from the list of views.
   4
   5 SCL console works by executing commands you write into the input box in the bottom of the view. After the command has been written, it can be executed by pressing ENTER. However, this works only if the command contains no syntactic errors. Possible errors are highlighted in the input box and a description of the error is shown when you move mouse on top of the highlighted text.
   6
   7 Multiline commands can be written by pressing CTRL-ENTER (or just ENTER when the current command text contains errors). The command history can be browsed with CTRL-UP and CTRL-DOWN.
   8
   9 If the command you write into console results as an ordinary value, it is just printed to the console. Here are couple of examples you can try:
  10
  11 ```
  12 > 13
  13 13
  14 > 1+2
  15 3
  16 > sin 1
  17 0.8414709848078965
  18 > "Hello " + "world!"
  19 Hello world!
  20 > [1,3,5]
  21 [1, 3, 5]
  22 ```
  23
  24 You can also declare local variables to be used in the commands:
  25
  26 ```
  27 > x = 35
  28 > y = 40
  29 > x + y
  30 75
  31 > x * y
  32 1400
  33 ```
  34
  35 Also new functions can be defined:
  36 ```
  37 > f x = x * x
  38 > f 123
  39 15129
  40 ```
  41
  42 If you write a command that has side-effects, it is executed in the console:
  43
  44 ```
  45 > print "Hello" ; print "world!"
  46 Hello
  47 world!
  48 ```
  49
  50 SCL is a dialect of Haskell and tutorials written for Haskell can be used for learning the details of the language. The main differences between the languages are the strict evaluation strategy used in SCL and somewhat different standard library. Some Haskell tutorials can be found at [https://wiki.haskell.org/Learning_Haskell](https://wiki.haskell.org/Learning_Haskell).
  51
  52 ## Extending SCL environment
  53
  54 The SCL values, data types etc. that are available in expressions and commands are defined in SCL modules. Currently all SCL modules must be part of the product plugins (in the future, you can also write modules inside the models). Each module is identified by a URI.
  55
  56 SCL module is a text file ending with extension ".scl". The recommended place for modules is scl/ folder under plugin root, but also other directories can be used:
  57
  58 **scl/Test1.scl**:
  59
  60 ```
  61 fib :: Integer -> Integer
  62 fib x | x <= 1    = 1
  63       | otherwise = fib (x-1) + fib (x-2)
  64 ```
  65
  66 A directory is declared as a SCL package with the following kind of extension points defined in org.simantics.scl.runtime:
  67
  68 ```
  69    <extension point="org.simantics.scl.runtime.package">
  70       <package URI="http://www.simantics.org/Tests"
  71                directory="scl"/>
  72    </extension>
  73 ```
  74
  75 The module is not automatically available in the console, but you must run an import declaration:
  76
  77 ```
  78 > import "http://www.simantics.org/Tests/Test1" as Test1
  79 > Test1.fib 13
  80 377
  81 ```
  82
  83 Import declaration can also be used in modules to refer other modules. Cyclic module dependencies are not allowed.
  84
  85 ## Importing functionality from Java
  86
  87 Java interfaces and classes can be imported from Java by declaring them inside importJava block:
  88
  89 ```
  90 importJava "java.util.regex.Pattern" where
  91     data Pattern
  92
  93 importJava "java.util.List" where
  94     data List a
  95 ```
  96
  97 Java methods, constructors and fields can be similarly imported by giving
  98 their type annotations in importJava block:
  99
 100 ```
 101 importJava "java.util.regex.Pattern" where
 102     @JavaName compile
 103     compilePattern :: String -> Pattern
 104
 105     @JavaName matcher
 106     createMatcher :: Pattern -> String -> <Proc> Matcher
 107
 108 importJava "java.util.regex.Matcher" where
 109     data Matcher
 110
 111     @JavaName matches
 112     matcherMatches :: Matcher -> <Proc> Boolean
 113
 114 matches : Pattern -> String -> <Proc> Boolean
 115 matches pattern text = do
 116     matcherMatches (createMatcher pattern text)
 117 ```
 118
 119 Another example:
 120
 121 ```
 122 importJava "java.util.ArrayList" where
 123     @JavaName "<init>"
 124     createArrayList :: () -> <Proc> List a
 125
 126     @JavaName "<init>"
 127     createArrayListWithCapacity :: Integer -> <Proc> List a
 128
 129     @JavaName size
 130     sizeList :: List a -> <Proc> Integer
 131
 132     @JavaName get
 133     getList :: List a -> Integer -> <Proc> a
 134
 135     @JavaName set
 136     setList :: List a -> Integer -> a -> <Proc> ()
 137
 138     @JavaName add
 139     addList :: List a -> a -> <Proc> Boolean
 140 ```
 141
 142 Java constructor is referred with `<init>`. If Java method name and SCL name matches the annotation @JavaName can be left out. Java import mechanism tries to be quite flexible. It provides some arguments based on the effects the function has. It also ignores the return value of the Java method if return type is `()` in SCL.
 143
 144 A major functionality currently still missing is the ability to create new implementations of existing Java interfaces in SCL code or extend an existing class. This can be worked around currently by writing new implementations in Java.