Introducción a numericalio
==========================

El paquete numericalio define funciones para leer y escribir ficheros de datos y flujos.

Cada elemento a leer o escribir en un fichero debe ser necesariamente un átomo: un número entero, decimal, decimal grande, una cadena o un símbolo; no se admiten fracciones, números complejos o cualquier otra expresión no atómica. Estas funciones pueden llegar a realizar operaciones válidas con expresiones no atómicas, pero estos resultados no se documentan y están sujetos a cambios ulteriores.

Los átomos, tanto en los ficheros de entrada como en los de salida, tienen el mismo formato que en los ficheros por lotes de Maxima o en la consola interactiva. En particular, las cadenas deben encerrarse entre comillas dobles, la barra invertida \ evita cualquier interpretación especial del carácter siguiente, y el símbolo de interrogación ? se reconoce como el comienzo de un símbolo de Lisp. No se reconoce ningún carácter de continuación de línea interrumpida.

El argumento opcional SEPARATOR_FLAG, común a todas las funciones de lectura y escritura, indica qué carácter será el utilizado para separar elementos.

Separadores válidos para lectura
--------------------------------

Para la lectura de ficheros se reconocen los siguientes valores de la variable SEPARATOR_FLAG: comma para los valores separados por comas, pipe para los valores separados por el carácter de la barra vertical |, semicolon para los valores separados por punto y coma ;, y space para cuando los valores se separan por espacios o tabulaciones. Si el nombre del fichero tiene extensión .csv y no se especifica el argumento SEPARATOR_FLAG, se tomará por defecto comma. Si el fichero tiene cualquier otra extensión diferente de .csv y no se especifica separator_flag, se usará por defecto space.

En la lectura, varios espacios y tabulaciones sucesivos cuentan como un único separador. Sin embargo, varias comas, barras verticales o punto y comas sucesivos se interpretan que tienen el símbolo false entre ellos; por ejemplo, 1234,,Foo se interpreta lo mismo que si fuese 1234,false,Foo. En la salida, los átomos false deben escribirse explícitamente, por lo que la lista [1234, false, Foo] debe escribirse 1234,false,Foo.

Separadores válidos para escritura
----------------------------------

Para la escritura, tab, para valores separados por tabuladores, se acepta como valor de SEPARATOR_FLAG, así como comma, pipe, semicolon y space.

En la escritura, el átomofalse se escribe tal cual y una lista [1234, false, Foo] se escribe 1234,false,Foo.

Funciones y variables para numericalio
======================================

 -- Función: read_matrix (FILE_NAME)
 -- Función: read_matrix (FILE_NAME, SEPARATOR_FLAG)
 -- Función: read_matrix (S)
 -- Función: read_matrix (S, SEPARATOR_FLAG)

     Lee el fichero FILE_NAME o el flujo S y devuelve su contenido completo en forma de matriz. Si no se especifica SEPARATOR_FLAG, se entiende que los valores están separados por espacios.

     La función read_matrix obtiene el tamaño de la matriz a partir de los datos de entrada. Cada línea del fichero forma una fila de la matriz. Si hay filas con diferente número de elementos, read_matrix emite un mensaje de error.

 -- Función: read_lisp_array (FILE_NAME, A)
 -- Función: read_lisp_array (FILE_NAME, A, SEPARATOR_FLAG)
 -- Función: read_lisp_array (S, A)
 -- Función: read_lisp_array (S, A, SEPARATOR_FLAG)

     La función read_lisp_array requiere que el arreglo sea declarado por make_array antes de solicitar la lectura del fichero, lo cual evita la necesidad de calcular las dimensiones del arreglo, especialmente en el caso de arreglos multidimensionales.

     La función read_lisp_array no comprueba si el fichero de entrada es compatible con las dimensiones del arreglo; la entrada se lee como una lista para a continuación completar el arreglo con fillarray.

 -- Función: read_maxima_array (FILE_NAME, A)
 -- Función: read_maxima_array (FILE_NAME, A, SEPARATOR_FLAG)
 -- Función: read_maxima_array (S, A)
 -- Función: read_maxima_array (S, A, SEPARATOR_FLAG)

     Lee el fichero FILE_NAME o el flujo S y devuelve su contenido completo en forma de array de Maxima. Si no se especifica SEPARATOR_FLAG, se entiende que los valores están separados por espacios.

     La función read_maxima_array requiere que el arreglo sea declarado por array antes de solicitar la lectura del fichero, lo cual evita la necesidad de calcular las dimensiones del arreglo, especialmente en el caso de arreglos multidimensionales.

     La función read_maxima_array no comprueba si el fichero de entrada es compatible con las dimensiones del arreglo; la entrada se lee como una lista para a continuación completar el arreglo con fillarray.

 -- Función: read_hashed_array (FILE_NAME, A)
 -- Función: read_hashed_array (FILE_NAME, A, SEPARATOR_FLAG)
 -- Función: read_hashed_array (S, A)
 -- Función: read_hashed_array (S, A, SEPARATOR_FLAG)

     Lee el fichero FILE_NAME o el flujo S y devuelve su contenido completo en forma de arreglo hash. Si no se especifica SEPARATOR_FLAG, se entiende que los valores están separados por espacios.

     La función read_hashed_array considera el primer término de la línea como un índice, asociando a éste el resto de la línea. Por ejemplo, una fila con el contenido 567 12 17 32 55 equivale a  A[567]: [12, 17, 32, 55]$. Las filas no necesitan tener el mismo número de elementos.

 -- Función: read_nested_list (FILE_NAME)
 -- Función: read_nested_list (FILE_NAME, SEPARATOR_FLAG)
 -- Función: read_nested_list (S)
 -- Función: read_nested_list (S, SEPARATOR_FLAG)

     La función read_nested_list devuelve una lista con una sublista por cada fila de entrada. Las filas no necesitan tener el mismo número de elementos. Las filas vacías no se ignoran, dando lugar a sublistas vacías.

 -- Función: read_list (FILE_NAME)
 -- Función: read_list (FILE_NAME, SEPARATOR_FLAG)
 -- Función: read_list (S)
 -- Función: read_list (S, SEPARATOR_FLAG)

     La función read_list o flujo S y lee todo el fichero de entrada como una lista simple. Si no se especifica SEPARATOR_FLAG, se entiende que los valores están separados por espacios.

 -- Función: write_data (X, FILE_NAME)
 -- Función: write_data (OBJECT, FILE_NAME, SEPARATOR_FLAG)
 -- Función: write_data (X, S)
 -- Función: write_data (OBJECT, S, SEPARATOR_FLAG)

     La función write_data escribe el objeto X en el fichero FILE_NAME o flujo S.

     write_data escribe las matrices fila a fila.

     write_data escribe arreglos de Maxima y Lisp fila a fila, con un salto de línea al final de cada tabla. Las tablas multidimensionales se separan con saltos de línea adicionales.

     write_data escribe arreglos codificados con un índice seguido de una lista asociativa en cada  línea.

     write_data escribe una lista anidada con una sublista por línea.

     write_data escribe una lista simple en una única línea.

     Cuando write_data escribe a un fichero, la variable global file_output_append controla si los datos se añaden a fichero o si éste es borrado antes de la escritura.

     En el caso de flujos, no se toman acciones especiales relacionadas con la sobreescritura. La función write_data no cierra el flujo.