docs/Developer/SCL/SCLRegistry.md

   1 This page documents a mechanism for finding and contributing SCL types and values in Simantics platform. All interfaces and classes mentioned are defined in the plugins `org.simantics.scl.reflection` or `org.simantics.scl.runtime`.
   2
   3 Both types and values are identified by URIs. The last part of the URI is the *name* of the type or value and the prefix before the name is the *namespace*.
   4
   5 ## Types
   6
   7 ### Grammar and representation
   8
   9 SCL types are written according to the following grammar:
  10
  11 ```
  12 t ::= C                // Type constructor
  13     | a                // Type variable
  14     | t1 t2            // Type application
  15     | forall a. t      // Universal quantification
  16     | P t1 ... tn => t // Qualified type
  17 ```
  18
  19 Type constructor is either one capitalized identifier or concatenation of multiple identifiers with period (`.`). In the former case, the last identifier does not have to be capitalized. Type variable is always a one identifier that is not capitalized.
  20
  21 Types are represented in Java using the following subtypes of <code>Type</code> (org.simantics.scl.types)
  22
  23 ```
  24 TCon(String module, String name)
  25 TVar()
  26 TApply(Type function, Type parameter)
  27 TForAll(TVar var, Type type)
  28 TPred(TFuncApply predicate, Type type)
  29 ```
  30
  31 Some type constructors have special syntax:
  32
  33 ```
  34 a -> b   =   TApply(TApply(TCon(Types.BUILTIN, "->"), a), b)
  35 [a]      =   TApply(TCon(Types.BUILTIN, "[]"), a)
  36 ()       =   TCon(Types.BUILTIN, "()")
  37 (a,b)    =   TApply(TApply(TCon(Types.BUILTIN, "(,)"), a), b)
  38 (a,b,c)  =   TApply(TApply(TApply(TCon(Types.BUILTIN, "(,,)"), a), b), c)
  39 ...
  40 ```
  41
  42 A type is converted from a String to Type using Types.parseType.
  43
  44 ### Converting types to classes
  45
  46 In order to get a Java class from a type, `TypeBindingScheme` (`org.simantics.scl.reflection`) is needed. It describes which Java class each type constructor corresponds to. With a scheme `s` types are converted to classes with the following rules implemented in `ReflectionUtils.getClass`
  47
  48 ```
  49 c(C)                -->  s(C)
  50 c(a)                --> Object
  51 c(t1 t2)            --> c(t1)
  52 c(forall a.t)       --> c(t)
  53 c(P t1 ... tn => t) --> Function
  54 ```
  55
  56 A singleton `MinimalTypeBindingScheme` implements `TypeBindingScheme` that uses extensions to find bindings from type constructors to classes. It must be extended elsewhere in order to get for example the types defined in the database.
  57
  58 The following bindings are defined even when no extensions are defined:
  59
  60 ```
  61 (->)    -->  Function
  62 []      -->  List
  63 ()      -->  Tuple0
  64 (,)     -->  Tuple2
  65 (,,)    -->  Tuple3
  66 ...
  67 Boolean --> Boolean
  68 Byte    --> Byte
  69 ...
  70 Long    --> Long
  71 String  --> String
  72 ```
  73
  74 ## Values
  75
  76 The type conversion rules in the previous section already dictate the Java class of the values of a certain SCL type. Depending on the type constructor, there are additional constraints. For example, values of type `[a]` must implement interface `java.util.List` and additionally elements of the list must be compatible with `a`. Values of type `a -> b` must implement the interface `Function` and additionally when method `appl` is called with a parameter compatible with type `a` the method must return a value compatible with type `b`.
  77
  78 ### Finding values
  79
  80 Values are found using `ReflectionUtils.getValue`. The method requires the URI of the value. This method does not cache the values.
  81
  82 ## Contributing types and values
  83
  84 Type are contributed putting SCLType-annotations to classes and values with `@SCLValue`-annotations on fields, constructors and methods. Both annotations have an optional name-attribute, which can be used to override the default name that is the name of the class or method annotated. SCLValue -annotation has also a required type-annotation where the SCL type of the value must be declared.
  85
  86 In addition, classes containing these annotations must be declared using the extension point `org.simantics.scl.reflection.binding`. It has the following elements
  87
  88 * **namespace**
  89   * **attributes**: path
  90   * **possible children**: class, namespace, externalClass, externalMethod, import
  91     Represents a library or type in semantic graph. If the element is the root of the extension,
  92 path is an absolute uri of the resource. Otherwise it is relative path from its parent element.
  93 * **class**
  94   * **attributes**: className
  95     Declares a Java class to be searched for annotations.
  96 * **import**
  97   * **attributes**: path, localName (optional)
  98     Gives a path a localName that can be used to refer it in type declarations.
  99 * **externalClass**
 100   * **attributes**: className, alternativeName (optional)
 101     Contributes a class without annotations.
 102 * **externalMethod**
 103   * **attributes**: className, methodName, alternativeName (optional)<br/>
 104     Contributes a method without annotations.