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

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

diff --git a/org.simantics.r.scl/scl/R/R.scl b/org.simantics.r.scl/scl/R/R.scl
index 28b2bacf6c502034e75afe0f92dfc42e7e670ecd..dc542d5c2a1521544b9666d4cdf4e3c2575ab442 100644 (file)
--- a/org.simantics.r.scl/scl/R/R.scl
+++ b/org.simantics.r.scl/scl/R/R.scl
@@ -2,58 +2,76 @@ import "Stream"
 import "Serialization"\r
 include "R/RExp"\r
 \r
+"""The effect <R> for a routine means that it needs to be dispatched to an R session using a suitable\r
+R execution routine. (syncExec, asyncExec, withConfiguration.)"""\r
 effect R \r
     "r" \r
     "org.rosuda.REngine.Rserve.RConnection"\r
 \r
 importJava "org.simantics.r.scl.RSessionConfiguration" where\r
+    """SessionConfiguration is a configuration element for the Session.\r
+    \r
+    The fields of the type are: SessionConfiguration <host name> <port number> <user name> <password>"""\r
     data SessionConfiguration = \r
         @FieldNames [host, port, username, password]\r
         SessionConfiguration String Integer String String\r
 \r
 importJava "org.simantics.r.scl.RSession" where\r
+    "Session represents an open R session with an Rserve instance."\r
     data Session\r
+    "Execute a given R operation synchronously. sychExec <session> <r operation>." \r
     syncExec :: Session -> (<R> a) -> <Proc> a\r
+    "Execute a given R operation asynchronously. asychExec <session> <r operation>." \r
     asyncExec :: Session -> (<R> a) -> <Proc> ()\r
+    "Get the session id of an open R session." \r
     @JavaName getId\r
     sessionIdOf :: Session -> String\r
+    "Close the given R session." \r
     @JavaName close\r
     closeSession :: Session -> <Proc> ()  \r
+    "Refresh the variables of a given R session." \r
     @JavaName refreshVariablesSync\r
     refreshVariables :: Session -> <Proc> ()\r
 \r
 importJava "org.simantics.r.scl.RSessionManager" where\r
+    "Get a session using a given session id." \r
     @JavaName getSession\r
     sessionById :: String -> <Proc> Maybe Session\r
+    "Create a new session with a given configuration." \r
     createSession :: SessionConfiguration -> <Proc> Session\r
+    "Execute a given R operation using a temporary session with the given configuration." \r
     withConfiguration :: SessionConfiguration-> (<R,e> a) -> <Proc,e> a\r
+    "Get a session with the given session id or create a new session, if not found." \r
     getOrCreateSession :: SessionConfiguration -> String -> <Proc> Session\r
     \r
 importJava "org.rosuda.REngine.Rserve.RConnection" where\r
+    "Evaluate an R expression, returning the result as an RExp object." \r
     @JavaName eval\r
     evalRExp:: String -> <R> RExp\r
+    "Evaluate an R expression and ignore the result." \r
     @JavaName voidEval\r
     evalR_ :: String -> <R> ()\r
+    "Evaluate an R expression and return the result as a string." \r
     @JavaName voidEvalS\r
     evalRS_ :: String -> <R> String\r
+    "Assign an RExp value to a variable in R." \r
     @JavaName assign\r
     assignRExp :: String -> RExp -> <R> ()\r
+    "Create a file on the R server and a return an OutputStream for it." \r
     @JavaName createFile\r
     createFileR :: String -> <R> OutputStream\r
+    "Open a file on the R server for reading and return a InputStream for it." \r
     @JavaName openFile\r
     openFileR :: String -> <R> InputStream\r
 \r
+"Evaluate an R expression and return the result as an SCL value. May fail, if the value is not compatible with the expected data type."\r
 evalR :: RCompatible a => String -> <R> a\r
 evalR = fromRExp . evalRExp\r
 \r
+"Assign an SCL value to a variable in R." \r
 assignR :: RCompatible a => String -> a -> <R> ()\r
 assignR name = assignRExp name . toRExp\r
 \r
+"Read the contents of a file on the R server into a string."\r
 readFileAsStringR :: String -> <R> String\r
 readFileAsStringR name = runProc (readAllString (openFileR name))\r
-\r
-test () = do\r
-    conf = SessionConfiguration "localhost" 6311 "simupedia" "simupedia"\r
-    session = createSession conf\r
-    print $ syncExec session (evalR "1+1")\r
-    closeSession session
\ No newline at end of file