Improved documentation of SCL routines in the R integration plugins. (refs #6431)

[simantics/r.git] / org.simantics.r / scl / R / RConfiguration.scl

diff --git a/org.simantics.r/scl/R/RConfiguration.scl b/org.simantics.r/scl/R/RConfiguration.scl
index f2bde7a4474e0b0aeb1e800d9d1a9677fb384835..05217d7902e0c0cf8406ee3995045901f8a210dc 100644 (file)
--- a/org.simantics.r/scl/R/RConfiguration.scl
+++ b/org.simantics.r/scl/R/RConfiguration.scl
@@ -4,7 +4,7 @@ import "Simantics/DB"
 import "http://www.simantics.org/R-1.0" as ROntology\r
 import "http://www.simantics.org/Layer0-1.1" as L0\r
 \r
-"""Creates a new session configuration to graph. This function does\r
+"""Creates a new session configuration to graph as a part of the parent resource. This function does\r
 not link it to any other resources."""\r
 createSessionConfiguration :: Resource -> R.SessionConfiguration -> <WriteGraph> Resource\r
 createSessionConfiguration parent (R.SessionConfiguration host port username password) = do \r
@@ -18,6 +18,7 @@ createSessionConfiguration parent (R.SessionConfiguration host port username pas
     claimRelatedValue r ROntology.SessionConfiguration.password password\r
     r\r
 \r
+"""Add an R script into the session configuration resource. The script is executed when a new session is opened with the createSession function."""\r
 addScript :: Resource -> String -> <WriteGraph> Resource\r
 addScript sessionConfiguration scriptText = do \r
     r = newResource ()\r
@@ -26,6 +27,7 @@ addScript sessionConfiguration scriptText = do
     claimRelatedValue r ROntology.Script.text scriptText\r
     r\r
 \r
+"""Read session configuration from the database."""\r
 readSessionConfiguration :: Resource -> <ReadGraph> R.SessionConfiguration\r
 readSessionConfiguration r = R.SessionConfiguration\r
     (relatedValue r ROntology.SessionConfiguration.host)\r
@@ -33,6 +35,7 @@ readSessionConfiguration r = R.SessionConfiguration
     (relatedValue r ROntology.SessionConfiguration.username)\r
     (relatedValue r ROntology.SessionConfiguration.password)\r
 \r
+"""Write an R session into the database."""\r
 writeSession :: R.Session -> <WriteGraph> Resource\r
 writeSession session = do \r
     r = newResource ()\r
@@ -40,24 +43,35 @@ writeSession session = do
     claimRelatedValue r L0.HasName $ R.sessionIdOf session\r
     r\r
 \r
+"""Execute the scripts defined for a session configuration using the given session."""\r
+executeScripts :: Resource -> R.Session -> <ReadGraph,Proc> ()\r
+executeScripts configurationResource session = for (configurationResource # ROntology.SessionConfiguration.hasScript) $ \s -> do\r
+    scriptText = relatedValue s ROntology.Script.text\r
+    R.asyncExec session (R.evalR_ scriptText)\r
+\r
+"""Read an R session from the database. If the session has been closed, a new session is opened with the\r
+same configuration."""\r
 readSession :: Resource -> <ReadGraph,Proc> R.Session\r
 readSession r = let\r
     sessionId = relatedValue r L0.HasName\r
   in match R.sessionById sessionId with\r
-    Just session -> session\r
-    Nothing -> R.getOrCreateSession (readSessionConfiguration $ singleObject r L0.PartOf) sessionId\r
+      Just session -> session\r
+      Nothing -> do\r
+        configurationResource = singleObject r L0.PartOf\r
+        session = R.getOrCreateSession (readSessionConfiguration $ configurationResource) sessionId\r
+        executeScripts configurationResource session\r
+        session\r
       \r
-\r
+"""Create a session based on a given session configuration resource."""\r
 createSession :: Resource -> <WriteGraph,Proc> Resource\r
 createSession configurationResource = do\r
     session = R.createSession $ readSessionConfiguration configurationResource\r
-    for (configurationResource # ROntology.SessionConfiguration.hasScript) $ \s -> do\r
-        scriptText = relatedValue s ROntology.Script.text\r
-        R.asyncExec session (R.evalR_ scriptText)\r
+    executeScripts configurationResource session\r
     sessionResource = writeSession session\r
     claim configurationResource L0.ConsistsOf sessionResource\r
     sessionResource\r
 \r
+"""Delete a session resource and close the session that it represents."""\r
 deleteSession :: Resource -> <WriteGraph,Proc> ()\r
 deleteSession r = do\r
     session = readSession r\r