X-Git-Url: https://gerrit.simantics.org/r/gitweb?p=simantics%2Fplatform.git;a=blobdiff_plain;f=docs%2FDeveloper%2FSCL%2FSCLRegistry.md;fp=docs%2FDeveloper%2FSCL%2FSCLRegistry.md;h=7a75fa6ddd0c43778bf49d696607d3f8a9a30b32;hp=0000000000000000000000000000000000000000;hb=cc48f111d9d7b053693c0c988b9caeef8e445ade;hpb=107a72960d307d614a1e165dbe3dc1316b286c86
diff --git a/docs/Developer/SCL/SCLRegistry.md b/docs/Developer/SCL/SCLRegistry.md
new file mode 100644
index 000000000..7a75fa6dd
--- /dev/null
+++ b/docs/Developer/SCL/SCLRegistry.md
@@ -0,0 +1,104 @@
+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`.
+
+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*.
+
+## Types
+
+### Grammar and representation
+
+SCL types are written according to the following grammar:
+
+```
+t ::= C // Type constructor
+ | a // Type variable
+ | t1 t2 // Type application
+ | forall a. t // Universal quantification
+ | P t1 ... tn => t // Qualified type
+```
+
+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.
+
+Types are represented in Java using the following subtypes of Type (org.simantics.scl.types)
+
+```
+TCon(String module, String name)
+TVar()
+TApply(Type function, Type parameter)
+TForAll(TVar var, Type type)
+TPred(TFuncApply predicate, Type type)
+```
+
+Some type constructors have special syntax:
+
+```
+a -> b = TApply(TApply(TCon(Types.BUILTIN, "->"), a), b)
+[a] = TApply(TCon(Types.BUILTIN, "[]"), a)
+() = TCon(Types.BUILTIN, "()")
+(a,b) = TApply(TApply(TCon(Types.BUILTIN, "(,)"), a), b)
+(a,b,c) = TApply(TApply(TApply(TCon(Types.BUILTIN, "(,,)"), a), b), c)
+...
+```
+
+A type is converted from a String to Type using Types.parseType.
+
+### Converting types to classes
+
+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`
+
+```
+c(C) --> s(C)
+c(a) --> Object
+c(t1 t2) --> c(t1)
+c(forall a.t) --> c(t)
+c(P t1 ... tn => t) --> Function
+```
+
+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.
+
+The following bindings are defined even when no extensions are defined:
+
+```
+(->) --> Function
+[] --> List
+() --> Tuple0
+(,) --> Tuple2
+(,,) --> Tuple3
+...
+Boolean --> Boolean
+Byte --> Byte
+...
+Long --> Long
+String --> String
+```
+
+## Values
+
+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`.
+
+### Finding values
+
+Values are found using `ReflectionUtils.getValue`. The method requires the URI of the value. This method does not cache the values.
+
+## Contributing types and values
+
+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.
+
+In addition, classes containing these annotations must be declared using the extension point `org.simantics.scl.reflection.binding`. It has the following elements
+
+* **namespace**
+ * **attributes**: path
+ * **possible children**: class, namespace, externalClass, externalMethod, import
+ Represents a library or type in semantic graph. If the element is the root of the extension,
+path is an absolute uri of the resource. Otherwise it is relative path from its parent element.
+* **class**
+ * **attributes**: className
+ Declares a Java class to be searched for annotations.
+* **import**
+ * **attributes**: path, localName (optional)
+ Gives a path a localName that can be used to refer it in type declarations.
+* **externalClass**
+ * **attributes**: className, alternativeName (optional)
+ Contributes a class without annotations.
+* **externalMethod**
+ * **attributes**: className, methodName, alternativeName (optional)
+ Contributes a method without annotations.