Improved Simantics/SCL module SCL module/script functionality

* Added new functions create{SCLModule,SCLScript,PGraph}R that return
  the created resource instead of returning ().
* Added new functions createSCL{Module,Script}WithDefinition for
  directly creating modules/scripts with a specific definition
* Added new functions set{SCLModule,SCLScript,PGraph}Definition for
  setting the definition specific to each entity.
* Added preliminary documentation for the module
* Deprecated create{SCLModule,SCLScript,PGraph} functions in favor of
  create...R

refs #7616

Change-Id: Ia2d97682eb184f5b0edd849f564ca05561938cb4

diff --git a/bundles/org.simantics.modeling/scl/Simantics/SCL.md b/bundles/org.simantics.modeling/scl/Simantics/SCL.md
new file mode 100644 (file)
index 0000000..d985176
--- /dev/null
+++ b/bundles/org.simantics.modeling/scl/Simantics/SCL.md
@@ -0,0 +1,59 @@
+# Simantics/SCL\r
+\r
+This module contains functions closely related to SCL and storing\r
+SCL related constructs in the Simantics database.\r
+\r
+## SCL Command Session\r
+\r
+::data[CommandResponse]\r
+::value[createTextAndErrors]\r
+::value[execute]\r
+::value[isSuccessful]\r
+\r
+### SCL Realm\r
+\r
+::value[getOrCreateSCLRealm]\r
+::value[readSCLRealm]\r
+::value[refreshVariables]\r
+::value[sclRealmById]\r
+::value[syncExec]\r
+\r
+### Command Session Variable Access\r
+\r
+::value[setVariable]\r
+::value[variableValue]\r
+\r
+## SCL Values\r
+\r
+::value[createSCLValue]\r
+::value[createSCLValueIndependent]\r
+::value[setExpression]\r
+\r
+## SCL Modules\r
+\r
+::value[createSCLModuleAction]\r
+::value[createSCLModuleDefault]\r
+::value[createSCLModule]\r
+::value[createSCLModuleR]\r
+::value[createSCLModuleWithDefinition]\r
+::value[setSCLModuleDefinition]\r
+\r
+## SCL Scripts\r
+\r
+::value[createSCLScriptAction]\r
+::value[createSCLScriptDefault]\r
+::value[createSCLScript]\r
+::value[createSCLScriptR]\r
+::value[createSCLScriptWithDefinition]\r
+::value[setSCLScriptDefinition]\r
+\r
+## Ontology definitions (PGraphs)\r
+\r
+PGraph (partial graph) is a textual format for specifying ontologies for Simantics.\r
+For more information on the format, see [this documentation](http://dev.simantics.org/index.php/Graph_File_Format).\r
+\r
+::value[createPGraphAction]\r
+::value[createPGraphDefault]\r
+::value[createPGraph]\r
+::value[createPGraphR]\r
+::value[setPGraphDefinition]\r

diff --git a/bundles/org.simantics.modeling/scl/Simantics/SCL.scl b/bundles/org.simantics.modeling/scl/Simantics/SCL.scl
index 05fbc0ee21af000cfe89cd769532796185956f3a..d636ca8eff2a1c99574ec15125c5691f7ab0f852 100644 (file)
--- a/bundles/org.simantics.modeling/scl/Simantics/SCL.scl
+++ b/bundles/org.simantics.modeling/scl/Simantics/SCL.scl
@@ -42,9 +42,58 @@ importJava "org.simantics.modeling.ModelingUtils" where
     createSCLModuleDefault :: Resource -> <WriteGraph> ()
     createSCLScriptDefault :: Resource -> <WriteGraph> ()
     createPGraphDefault :: Resource -> <WriteGraph> ()
+    "Use [createSCLModuleR](#createSCLModuleR) instead."
+    @deprecated
     createSCLModule :: Resource -> String -> <WriteGraph> ()
+    "Use [createSCLScriptR](#createSCLScriptR) instead."
+    @deprecated
     createSCLScript :: Resource -> String -> <WriteGraph> ()
+    "Use [createPGraphR](#createPGraphR) instead."
+    @deprecated
     createPGraph :: Resource -> String -> <WriteGraph> ()
+    """
+    `createSCLModuleR container name` creates a new empty SCL module under
+    the specified `container` with the specified `name` and returns the created
+    module's Resource.
+    """
+    @JavaName createSCLModule
+    createSCLModuleR :: Resource -> String -> <WriteGraph> Resource
+    """
+    `createSCLScriptR container name` creates a new empty SCL script under
+    the specified `container` with the specified `name` and returns the created
+    script's Resource.
+    """
+    @JavaName createSCLScript
+    createSCLScriptR :: Resource -> String -> <WriteGraph> Resource
+    """
+    `createPGraphR container name` creates a new empty partial graph
+    ontology definition (PGraph) under the specified `container` with
+    the specified `name` and returns the created ontology definition's
+    Resource.
+    """
+    @JavaName createPGraph
+    createPGraphR :: Resource -> String -> <WriteGraph> Resource
+    "`setSCLModuleDefinition module definition` sets the textual `definition` of the specified SCL `module`."
+    setSCLModuleDefinition :: Resource -> String -> <WriteGraph> Resource
+    "`setSCLScriptDefinition module definition` sets the textual `definition` of the specified SCL `module`."
+    setSCLScriptDefinition :: Resource -> String -> <WriteGraph> Resource
+    setPGraphDefinition :: Resource -> String -> <WriteGraph> Resource
+
+"""
+`createSCLModuleWithDefinition container name definition` creates a new SCL module under
+the specified `container` with the specified `name` and `definition` and returns
+the created module's Resource.
+"""
+createSCLModuleWithDefinition :: Resource -> String -> String -> <WriteGraph> Resource
+createSCLModuleWithDefinition container name definition = setSCLModuleDefinition (createSCLModuleR container name) definition
+
+"""
+`createSCLScriptWithDefinition container name definition` creates a new SCL script under
+the specified `container` with the specified `name` and `definition` and returns
+the created script's Resource.
+"""
+createSCLScriptWithDefinition :: Resource -> String -> String -> <WriteGraph> Resource
+createSCLScriptWithDefinition container name definition = setSCLScriptDefinition (createSCLScriptR container name) definition
 
 effect SCL 
     "scl" 

diff --git a/bundles/org.simantics.modeling/src/org/simantics/modeling/ModelingUtils.java b/bundles/org.simantics.modeling/src/org/simantics/modeling/ModelingUtils.java
index e0551eb3e76df1a7193d6e0f4ffcbd85b0715173..a43220f0677a0efc3b6c54a3f4b2c39caded4b83 100644 (file)
--- a/bundles/org.simantics.modeling/src/org/simantics/modeling/ModelingUtils.java
+++ b/bundles/org.simantics.modeling/src/org/simantics/modeling/ModelingUtils.java
@@ -1760,28 +1760,36 @@ public class ModelingUtils {
        
     }
 
-    
-    public static void createSCLModuleDefault(WriteGraph graph, Resource target) throws DatabaseException {
-       String name = NameUtils.findFreshEscapedName(graph, "SCLModule", target);
-       createSCLModule(graph, target, name);
+    public static Resource createSCLModuleDefault(WriteGraph graph, Resource target) throws DatabaseException {
+        String name = NameUtils.findFreshEscapedName(graph, "SCLModule", target);
+        return createSCLModule(graph, target, name);
     }
 
-    public static void createSCLModule(WriteGraph graph, Resource target, String name) throws DatabaseException {
+    public static Resource createSCLModule(WriteGraph graph, Resource target, String name) throws DatabaseException {
         graph.markUndoPoint();
-       Layer0 L0 = Layer0.getInstance(graph);
+        Layer0 L0 = Layer0.getInstance(graph);
         Resource sclModule = GraphUtils.create2(graph, L0.SCLModule,
                 L0.HasName, name,
                 L0.PartOf, target,
                 L0.SCLModule_definition, "");
-       Layer0Utils.addCommentMetadata(graph, "Created SCL Module " + name + " " + sclModule.toString());
+        Layer0Utils.addCommentMetadata(graph, "Created SCL Module " + name + " " + sclModule.toString());
+        return sclModule;
+    }
+
+    public static Resource setSCLModuleDefinition(WriteGraph graph, Resource module, String definition) throws DatabaseException {
+        graph.markUndoPoint();
+        Layer0 L0 = Layer0.getInstance(graph);
+        graph.claimLiteral(module, L0.SCLModule_definition, definition, Bindings.STRING);
+        Layer0Utils.addCommentMetadata(graph, "Set SCL module " + module + " definition.");
+        return module;
     }
 
-    public static void createSCLScriptDefault(WriteGraph graph, Resource target) throws DatabaseException {
+    public static Resource createSCLScriptDefault(WriteGraph graph, Resource target) throws DatabaseException {
         String name = NameUtils.findFreshEscapedName(graph, "SCLScript", target);
-        createSCLScript(graph, target, name);
+        return createSCLScript(graph, target, name);
     }
 
-    public static void createSCLScript(WriteGraph graph, Resource target, String name) throws DatabaseException {
+    public static Resource createSCLScript(WriteGraph graph, Resource target, String name) throws DatabaseException {
         graph.markUndoPoint();
         Layer0 L0 = Layer0.getInstance(graph);
         Resource sclModule = GraphUtils.create2(graph, L0.SCLScript,
@@ -1789,23 +1797,41 @@ public class ModelingUtils {
                 L0.PartOf, target,
                 L0.SCLScript_definition, "");
         Layer0Utils.addCommentMetadata(graph, "Created SCL Script " + name + " " + sclModule.toString());
+        return sclModule;
     }
 
-    public static void createPGraphDefault(WriteGraph graph, Resource target) throws DatabaseException {
-       String name = NameUtils.findFreshEscapedName(graph, "Ontology Definition File", target);
-       createPGraph(graph, target, name);
+    public static Resource setSCLScriptDefinition(WriteGraph graph, Resource script, String definition) throws DatabaseException {
+        graph.markUndoPoint();
+        Layer0 L0 = Layer0.getInstance(graph);
+        graph.claimLiteral(script, L0.SCLScript_definition, definition, Bindings.STRING);
+        Layer0Utils.addCommentMetadata(graph, "Set SCL script " + script + " definition.");
+        return script;
     }
 
-    public static void createPGraph(WriteGraph graph, Resource target, String name) throws DatabaseException {
+    public static Resource createPGraphDefault(WriteGraph graph, Resource target) throws DatabaseException {
+        String name = NameUtils.findFreshEscapedName(graph, "Ontology Definition File", target);
+        return createPGraph(graph, target, name);
+    }
+
+    public static Resource createPGraph(WriteGraph graph, Resource target, String name) throws DatabaseException {
         graph.markUndoPoint();
-       Layer0 L0 = Layer0.getInstance(graph);
+        Layer0 L0 = Layer0.getInstance(graph);
         Resource file = GraphUtils.create2(graph, L0.PGraph,
                 L0.HasName, name,
                 L0.PartOf, target,
                 L0.PGraph_definition, "");
-       Layer0Utils.addCommentMetadata(graph, "Created Ontology Definition File " + name + " " + file.toString());
+        Layer0Utils.addCommentMetadata(graph, "Created Ontology Definition File " + name + " " + file.toString());
+        return file;
     }
-    
+
+    public static Resource setPGraphDefinition(WriteGraph graph, Resource pgraph, String definition) throws DatabaseException {
+        graph.markUndoPoint();
+        Layer0 L0 = Layer0.getInstance(graph);
+        graph.claimLiteral(pgraph, L0.PGraph_definition, definition, Bindings.STRING);
+        Layer0Utils.addCommentMetadata(graph, "Set PGraph " + pgraph + " definition.");
+        return pgraph;
+    }
+
     public static void publish(WriteGraph graph, Resource target) throws DatabaseException {
        Layer0 L0 = Layer0.getInstance(graph);
        graph.claimLiteral(target, L0.Entity_published, true, Bindings.BOOLEAN);