From: tuorjr Date: Fri, 22 Apr 2016 13:05:29 +0000 (+0000) Subject: Improved documentation of SCL routines in the R integration plugins. (refs #6431) X-Git-Tag: v1.28.0~12 X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=commitdiff_plain;h=a1970c4294dcbca8f74d9e8e9cff4e81387e56c6;p=simantics%2Fr.git Improved documentation of SCL routines in the R integration plugins. (refs #6431) Added a routine for executing the scripts in a session configuration resource. Modified readSession to execute initialization scripts when creating a new session. git-svn-id: https://www.simantics.org/svn/simantics/r/trunk@32697 ac1ea38d-2e2b-0410-8846-a27921b304fc --- diff --git a/org.simantics.r.scl/scl/R/R.md b/org.simantics.r.scl/scl/R/R.md new file mode 100644 index 0000000..a672123 --- /dev/null +++ b/org.simantics.r.scl/scl/R/R.md @@ -0,0 +1,5 @@ +# Module R/R + +This module contains tools for interacting with the R Project via the Rserve package. + +::undocumented[] diff --git a/org.simantics.r.scl/scl/R/R.scl b/org.simantics.r.scl/scl/R/R.scl index 28b2bac..dc542d5 100644 --- 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" include "R/RExp" +"""The effect for a routine means that it needs to be dispatched to an R session using a suitable +R execution routine. (syncExec, asyncExec, withConfiguration.)""" effect R "r" "org.rosuda.REngine.Rserve.RConnection" importJava "org.simantics.r.scl.RSessionConfiguration" where + """SessionConfiguration is a configuration element for the Session. + + The fields of the type are: SessionConfiguration """ data SessionConfiguration = @FieldNames [host, port, username, password] SessionConfiguration String Integer String String importJava "org.simantics.r.scl.RSession" where + "Session represents an open R session with an Rserve instance." data Session + "Execute a given R operation synchronously. sychExec ." syncExec :: Session -> ( a) -> a + "Execute a given R operation asynchronously. asychExec ." asyncExec :: Session -> ( a) -> () + "Get the session id of an open R session." @JavaName getId sessionIdOf :: Session -> String + "Close the given R session." @JavaName close closeSession :: Session -> () + "Refresh the variables of a given R session." @JavaName refreshVariablesSync refreshVariables :: Session -> () importJava "org.simantics.r.scl.RSessionManager" where + "Get a session using a given session id." @JavaName getSession sessionById :: String -> Maybe Session + "Create a new session with a given configuration." createSession :: SessionConfiguration -> Session + "Execute a given R operation using a temporary session with the given configuration." withConfiguration :: SessionConfiguration-> ( a) -> a + "Get a session with the given session id or create a new session, if not found." getOrCreateSession :: SessionConfiguration -> String -> Session importJava "org.rosuda.REngine.Rserve.RConnection" where + "Evaluate an R expression, returning the result as an RExp object." @JavaName eval evalRExp:: String -> RExp + "Evaluate an R expression and ignore the result." @JavaName voidEval evalR_ :: String -> () + "Evaluate an R expression and return the result as a string." @JavaName voidEvalS evalRS_ :: String -> String + "Assign an RExp value to a variable in R." @JavaName assign assignRExp :: String -> RExp -> () + "Create a file on the R server and a return an OutputStream for it." @JavaName createFile createFileR :: String -> OutputStream + "Open a file on the R server for reading and return a InputStream for it." @JavaName openFile openFileR :: String -> InputStream +"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." evalR :: RCompatible a => String -> a evalR = fromRExp . evalRExp +"Assign an SCL value to a variable in R." assignR :: RCompatible a => String -> a -> () assignR name = assignRExp name . toRExp +"Read the contents of a file on the R server into a string." readFileAsStringR :: String -> String readFileAsStringR name = runProc (readAllString (openFileR name)) - -test () = do - conf = SessionConfiguration "localhost" 6311 "simupedia" "simupedia" - session = createSession conf - print $ syncExec session (evalR "1+1") - closeSession session \ No newline at end of file diff --git a/org.simantics.r/scl/R/RConfiguration.md b/org.simantics.r/scl/R/RConfiguration.md new file mode 100644 index 0000000..696fda1 --- /dev/null +++ b/org.simantics.r/scl/R/RConfiguration.md @@ -0,0 +1,5 @@ +# Module R/RConfiguration + +This module contains routines for managing the storage of R session configurations in the Simantics database. + +::undocumented[] diff --git a/org.simantics.r/scl/R/RConfiguration.scl b/org.simantics.r/scl/R/RConfiguration.scl index f2bde7a..05217d7 100644 --- 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 import "http://www.simantics.org/Layer0-1.1" as L0 -"""Creates a new session configuration to graph. This function does +"""Creates a new session configuration to graph as a part of the parent resource. This function does not link it to any other resources.""" createSessionConfiguration :: Resource -> R.SessionConfiguration -> Resource createSessionConfiguration parent (R.SessionConfiguration host port username password) = do @@ -18,6 +18,7 @@ createSessionConfiguration parent (R.SessionConfiguration host port username pas claimRelatedValue r ROntology.SessionConfiguration.password password r +"""Add an R script into the session configuration resource. The script is executed when a new session is opened with the createSession function.""" addScript :: Resource -> String -> Resource addScript sessionConfiguration scriptText = do r = newResource () @@ -26,6 +27,7 @@ addScript sessionConfiguration scriptText = do claimRelatedValue r ROntology.Script.text scriptText r +"""Read session configuration from the database.""" readSessionConfiguration :: Resource -> R.SessionConfiguration readSessionConfiguration r = R.SessionConfiguration (relatedValue r ROntology.SessionConfiguration.host) @@ -33,6 +35,7 @@ readSessionConfiguration r = R.SessionConfiguration (relatedValue r ROntology.SessionConfiguration.username) (relatedValue r ROntology.SessionConfiguration.password) +"""Write an R session into the database.""" writeSession :: R.Session -> Resource writeSession session = do r = newResource () @@ -40,24 +43,35 @@ writeSession session = do claimRelatedValue r L0.HasName $ R.sessionIdOf session r +"""Execute the scripts defined for a session configuration using the given session.""" +executeScripts :: Resource -> R.Session -> () +executeScripts configurationResource session = for (configurationResource # ROntology.SessionConfiguration.hasScript) $ \s -> do + scriptText = relatedValue s ROntology.Script.text + R.asyncExec session (R.evalR_ scriptText) + +"""Read an R session from the database. If the session has been closed, a new session is opened with the +same configuration.""" readSession :: Resource -> R.Session readSession r = let sessionId = relatedValue r L0.HasName in match R.sessionById sessionId with - Just session -> session - Nothing -> R.getOrCreateSession (readSessionConfiguration $ singleObject r L0.PartOf) sessionId + Just session -> session + Nothing -> do + configurationResource = singleObject r L0.PartOf + session = R.getOrCreateSession (readSessionConfiguration $ configurationResource) sessionId + executeScripts configurationResource session + session - +"""Create a session based on a given session configuration resource.""" createSession :: Resource -> Resource createSession configurationResource = do session = R.createSession $ readSessionConfiguration configurationResource - for (configurationResource # ROntology.SessionConfiguration.hasScript) $ \s -> do - scriptText = relatedValue s ROntology.Script.text - R.asyncExec session (R.evalR_ scriptText) + executeScripts configurationResource session sessionResource = writeSession session claim configurationResource L0.ConsistsOf sessionResource sessionResource +"""Delete a session resource and close the session that it represents.""" deleteSession :: Resource -> () deleteSession r = do session = readSession r