= tolLink =

{{{
#!div style="background:#fcc; border: 1px solid red; color:red; padding-left:1em; margin-right:1em"
Este paquete ha sido sustituido por [wiki:tolRlink].
}}}

== Introducción ==

{{{tolLink}}} es uno de los paquetes para R desarrollados para la integración con TOL. Véase [wiki:Rprojects].

{{{tolLink}}} es el paquete encargado de conectar con el núcleo de TOL. El enlace lo hace a través de la librería {{{libtol.dll}}} (o {{{libtol.so}}}).

Necesita por tanto de una instalación de TOL compatible con R (TOL-GNU). 

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 {{{tolLink}}} en R permite la conexión con TOL, para ello ha de existir una instalación de TOL compatible (TOL-GNU) 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 {{{tolLink}}} 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
}}}