Changes between Initial Version and Version 1 of tolRlink

Timestamp:

Feb 3, 2016, 11:37:18 AM (9 years ago)

Author:

Pedro Gea

Comment:

--

tolRlink

@@ +1 @@
+= tolRlink =
+
+== Introducción ==
+
+{{{tolRlink}}} es uno de los paquetes para R desarrollados para la integración con TOL. Véase [wiki:Rprojects].
+
+{{{tolRlink}}} es el paquete encargado de conectar con el núcleo de TOL. El enlace lo hace a través de la librería {{{tolRlink.dll}}} (o {{{tolRlink.so}}}).
+
+Necesita por tanto de una instalación de TOL compatible con R.
+
+Dispone de métodos para cargar y descargar la dll, iniciar y cerrar la sesión TOL, compilar código en el núcleo de TOL, obtener en R objetos de TOL, trasladar objetos de R hacia TOL, etc.
+
+== Conexión con TOL ==
+
+El paquete {{{tolRlink}}} en R permite la conexión con TOL, para ello ha de existir una instalación de TOL compatible cuyo directorio principal se encuentre apuntado por la variable de entorno {{{TOLGNU_ROOT}}}. Esta variable se creará durante el proceso de instalación de TOL.
+
+Durante el proceso de carga en R, el paquete intentará localizar la instalación de TOL, y en caso de encontrarla emitirá el siguiente mensaje: {{{TOL-GNU was correctly found.}}}.
+
+Una vez cargado el paquete {{{tolRlink}}} en R disponemos de diferentes funciones para cargar o descargar la librería (.dll o .so) e inicializar o salir de TOL:
+ * tolLoad
+ * tolUnload
+ * tolIsLoaded
+ * tolInit
+ * tolExit
+ * tolReinit
+ * tolIsInitialized
+
+Las diferentes llamadas en este paquete desencadenan las correspondientes llamadas para su adecuado funcionamiento, así pues, la llamada a {{{tolInit}}} basta para inicializar TOL, ya que la librería ser cargará automáticamente si no estuviera hecho:
+
+{{{
+#!ruby
+tolInit() # llama a tolLoad() automáticamente
+}}}
+
+== Comunicación con TOL ==
+
+Para la comunicación con TOL disponemos de diferentes funciones que nos permiten interaccionar con las variables y las funciones de TOL:
+ * tolGet
+ * tolRefer
+ * tolExecute
+ * tolDeclare
+
+Mientras {{{tolGet}}} nos permite obtener el valor de una variable en TOL, {{{tolRefer}}} nos permite referirnos a ella sin traer su valor hasta R.
+
+De modo similar {{{tolExecute}}} nos permite ejecutar una función en TOL, mientras que {{{tolDeclare}}} nos permite preparar la expresión para su ejecución sin hacerlo.
+
+Ejemplos:
+
+{{{
+#!ruby
+# Obtener un valor de TOL
+tolGet("Time") #warning
+tolGet("Time", grammar="Text")
+}}}
+
+{{{
+#!ruby
+# Llamar a una función de TOL
+tolExecute("Sin", 3)
+tolExecute("TextLength", "Texto")
+# Con varios argumentos
+tolExecute("TextSub", "Texto", 2, -2)
+}}}
+
+{{{
+#!ruby
+# Encadenar llamadas
+tolExecute("Sin", tolExecute("Sin", 3)) # 2 llamadas
+tolExecute("Sin", tolDeclare("Sin", 3)) # 1 llamada
+}}}
+
+{{{
+#!ruby
+# Usar variables de TOL
+tolExecute("Sin", tolGet("Pi")) # 2 llamadas
+tolExecute("Sin", tolRefer("Pi")) # 1 llamada
+}}}
+
+Las funciones en TOL pueden ser usadas como variables, para hacer esto en R usaremos {{{tolExecute}}} o {{{tolDeclare}}} con un sólo argumento:
+
+{{{
+#!ruby
+# Usar un Code como variable
+tolExecute("CodeGrammar", tolDeclare("Sin")) #warning
+# Obtener el Code para una gramática dada
+tolExecute("Sin", grammar="Real")
+}}}
+
+Las funciones {{{tolExecute}}} y {{{tolDeclare}}} también pueden usarse con operadores:
+
+{{{
+#!ruby
+# Usar operadores
+tolExecute("-", 2) # monario
+tolExecute("-", 2, 1) # binario
+tolExecute("-", 10, 2, 1) # binario
+}}}
+
+== Correspondencias de las variables de TOL ==
+
+Los tipos de variables de TOL (gramáticas) se hacen corresponder con distintos tipos o clases en R.
+A continuación indicamos en una tabla estas correspondencias:
+
+|| '''Grammar'''  || '''R class''' || '''R package''' ||
+|| {{{Real}}} || {{{numeric}}} || base ||
+|| {{{Text}}} || {{{character}}} || base ||
+|| {{{Date}}} || {{{Date}}}, {{{POSIXt}}} || base ||
+|| {{{Matrix}}} || {{{matrix}}} || base ||
+|| {{{TimeSet}}} || {{{Dating}}} || tolBasis ||
+|| {{{Serie}}} || {{{Serie}}} || tolBasis ||
+|| {{{Polyn}}} || {{{Polyn}}} || tolBasis ||
+|| {{{Ratio}}} || {{{Ratio}}} || tolBasis ||
+|| {{{Set}}} || {{{list}}} || base ||
+|| {{{Complex}}} || {{{complex}}} || base ||
+|| {{{NameBlock}}} || ''reference'' || ||
+|| {{{VMatrix}}} || ''reference'' || ||
+|| {{{PolMatrix}}} || ''reference'' || ||
+|| {{{Code}}} || {{{.TolCode}}} || ||
+|| (TOL reference) || {{{.TolReference}}} || tolLink ||
+|| (TOL expression) || {{{.TolDeclaration}}} || tolLink ||
+|| {{{(Struct)}}} || {{{attr(,"struct")}}} || tolLink ||
+|| {{{(Class)}}} || {{{--}}} || ||
+
+== Otras interacciones con TOL ==
+
+Para la declaración de variables en TOL disponemos de dos funciones:
+ * tolDefine 
+ * tolRelease
+
+Para la inclusión de archivos en TOL disponemos de:
+ * tolInclude 
+ * tolExclude
+
+Para la carga de paquetes en TOL tenemos la función:
+ * tolRequire
+
+La función {{{tolExist}}} nos permite determinar si una variable TOL existe antes de intentar obtenerla con {{{tolGet}}}.
+
+la función {{{tolStruct}}} nos permite crear listas estructuradas, compatibles con los conjuntos estructurados en TOL.
+
+Ejemplos:
+
+{{{
+#!ruby
+ss <- tolStruct("@Real", 3);
+tolExecute("StructName", ss) # se obtiene el nombre de la estructura
+}}}
+
+{{{
+#!ruby
+tolExist("test") # -> FALSE
+tolDefine("test", 8)
+tolExist("test") # -> TRUE
+tolGet("test") # -> 8
+tolRelease("test")
+tolExist("test") # -> FALSE
+}}}