Parte II - Rutinas de librería

1. Introducción

 
Se provee una gran cantidad de rutinas de librería. Algunas están incorporadas dentro del intérprete, ex.exe, exw.exe o exu. Otras están escritas en Euphoria y tiene que incluir alguno de los archivos .e que están en euphoria\include para poder usarlas. Cuando este es el caso, se incluye el nombre del archivo adecuado en el apartado "Sintaxis" de la descripción. Por supuesto, un archivo de inclusión solamente se necesita incluirlo una única vez en el programa. El editor muestra en magenta a aquellas rutinas que están incorporadas dentro del intérprete, y que no requieren de ningún archivo de inclusión. Puede redefinir la definición de estas rutinas internas, haciendo su propia rutina con el mismo nombre. Obtendrá una advertencia suprimible si hace esto.

Para indicar que tipo de objeto se puede pasar y devolver, se usan estos prefijos:

x - un objeto general (átomo o secuencia)
s - una secuencia
a - un átomo
i - un entero
fn - un entero usado como número de archivo
st - una secuencia de cadena, o un átomo de un caracter

Algunas rutinas están solamente disponibles para uno, dos o tres de las plataformas. Esto está indicado con "Plataforma: DOS32" o "Plataforma: WIN32" o "Plataforma: Linux" en la descripción de las rutinas, y con (DOS32) o (WIN32) o (Linux) en algunos otros lugares.

Aparecerá un mensaje de error en tiempo de ejecución si se les pasa un argumento ilegal a cualquiera de esas rutinas.



2. Rutinas por área de aplicación


2.1 Tipos predefinidos

Además de declarar variables de esos tipos, también puede llamar a estas funciones como a cualquier otra función ordinaria para probar si un valor es de un cierto tipo.

integer - comprueba si un objeto es un entero
atom - comprueba si un objeto es un átomo
sequence - comprueba si un objeto es una secuencia
object - comprueba si un objeto es un objeto (siempre verdadero)



2.2 Manipulación de secuencias

length - devuelve la longitud de una secuencia
repeat - repite un objeto n veces para formar una secuencia de longitud n.
reverse - invierte una secuencia
append - agrega un nuevo elemento al final de la secuencia
prepend - agrega un nuevo elemento al comienzo de la secuencia



2.3 Búsqueda y ordenamiento

compare - compara dos objetos
equal - comprueba si dos objetos son idénticos
find - busca un objeto dentro de una secuencia
match - busca una secuencia como una porción dentro de otra secuencia
sort - ordena los elementos de una secuencia en orden ascendente
custom_sort - ordena los elementos de una secuencia basándose en una función de comparación que se le suministra



2.4 Coincidencia de patrones

lower - convierte un átomo o secuencia a minúsculas
upper - convierte un átomo o secuencia a mayúsculas
wildcard_match - busca la coincidencia con un patrón conteniendo los símbolos ? y *
wildcard_file - busca la coincidencia de un nombre de archivo contra un patrón de símbolos



2.5 Matemáticas

Estas rutinas se pueden aplicar a átomos individuales o a secuencias de valores. Ver Parte I - Core Language - Operaciones sobre secuencias.

sqrt - calcula la raíz cuadrada de un objeto
rand - genera números aleatorios
sin - calcula el seno de un ángulo
arcsin - calcula el ángulo para un dado seno
cos - calcula el coseno de un ángulo
arccos - calcula el ángulo para un dado coseno
tan - calcula la tangente de un ángulo
arctan - calcula el arco tangente de un número
log - calcula el logaritmo natural
floor - redondea hacia abajo al entero más próximo
remainder - calcula el resto de la división de dos números
power - calcula un número elevado a una potencia
PI - valor matemático de PI (3.14159...)



2.6 Operaciones lógicas bit a bit

Estas funciones tratan a los números como colecciones de dígitos binarios, y las operaciones lógicas se efectuan sobre los bits correspondientes a la representación binaria de esos números. No hay rutinas para los desplazamientos de bits a izquierda o derecha, pero puede conseguir el mismo efecto mediante multiplicaciones y divisiones por potencias de 2.

and_bits - realiza la operación lógica AND bit a bit
or_bits - realiza la operación lógica OR bit a bit
xor_bits - realiza la operación lógica XOR bit a bit
not_bits - realiza la operación lógica NOT sobre todos los bits



2.7 Archivos y dispositivos de E/S

Para ingresar o extraer información de un archivo o dispositivo, primero tiene que abrirlo, luego usará las rutinas que están más abajo para leer o escribir en él, para finalmente cerrar ese archivo o dispositivo. open() le dará un número de archivo para usar como primer argumento con las otras rutinas de E/S. Ciertos archivos o dispositivos, como los archivos d texto, se abren en forma automática:

0 - entrada estándar
1 - salida estándar
2 - error estándar
A menos que los redirija en la línea de comandos, la entrada estándar viene desde el teclado, la salida y el error estándares van a la pantalla. Cuando escribe algo en pantalla, se escribe inmediatamente sin usar un búfer. Si escribe a un archivo, sus caracteres se ponen dentro de un búfer hasta que su cantidad es suficiente para que su escritura sea eficiente. Al cerrar (close()) o liberar (flush()) el archivo o dispositivo, cualquier caracter restante se escribe. La entrada desde un archivo también usa un búfer. Cuando termina el programa, cualquier archivo que aún está abierto, se cierra automáticamente.
Nota:
Si un programa (escrito en Euphoria o cualquier otro lenguaje) tiene un archivo abierto para escritura y, por ejemplo, se fuerza el reinicio de la computadora por cualquier razón, inmediatamente debería correr el scandisk para reparar cualquier daño que pudiese haber ocurrido en el sistema de archivos.
open - abre un archivo o dispositivo
close - cierra un archivo o dispositivo
flush - descarga los datos en el búfer al archivo o dispositivo
lock_file - bloquea un archivo o dispositivo
unlock_file - desbloquea un archivo o dispositivo
print - imprime un objeto Euphoria en una línea, con llaves y comas {,,} para mostrar la estructura
pretty_print - imprime un objeto Euphoria en una forma agradable, usando varias líneas y la sangría adecuada
? x - abreviatura para print(1, x)
sprint - devuelve un objeto Euphoria impreso como una secuencia de cadena
printf - impresión formateada a un archivo o dispositivo
sprintf - impresión formateada devuelta como una secuencia de cadena
puts - emite una secuencia de cadena a un archivo o dispositivo
getc - lee el siguiente caracter desde un archivo o dispositivo
gets - lee la siguiente línea desde un archivo o dispositivo
get_bytes - lee los siguientes n bytes desde un archivo o dispositivo
prompt_string - solicita al usuario que ingrese una cadena
get_key - verifica la tecla presionada por el usuario , sin espera
wait_key - espera que el usuario presione una tecla
get - lee la representación de cualquier objeto Euphoria desde un archivo
prompt_number - solicita al usuario que ingrese un número
value - lee la representación de cualquier objeto Euphoria desde una cadena
seek - se mueve a la posición de cualquier byte dentro de un archivo abierto
where - informa la posición del byte actual en un archivo abierto
current_dir - devuelve el nombre del directorio actual
chdir - cambia a un nuevo directorio actual
dir - devuelve la información completa de todos los archivos en un directorio
walk_dir - camina recursivamente a través de todos los archivos de un directorio
allow_break - habilita/deshabilita la terminación de un programa con Ctrl+C o Ctrl+Break
check_break - verifica si el usuario presionó Ctrl+C o Ctrl+Break



2.8 Soporte de ratón (DOS32 y Linux)

get_mouse - devuelve los eventos del ratón (clics, desplazamientos)
mouse_events - selecciona los eventos del ratón para esperarlos
mouse_pointer - muestra u oculta el puntero del ratón



2.9 Sistema operativo

time - cantidad de segundos transcurridos desde algún punto fijo en el pasado
tick_rate - establece la cantidad de pulsos del reloj por segundo (DOS32)
date - año, mes, día, hora, minuto, segundo, etc. actuales
command_line - línea de comandos usada para ejecutar este programa
getenv - obtiene el valor de una variable de entorno
system - ejecuta una línea de comandos del sistema operativo
system_exec - ejecuta un programa y obtiene su código de salida
abort - termina la ejecución
sleep - suspende la ejecución por un período de tiempo
platform - determina sobre cuál sistema operativo se está corriendo



2.10 Rutinas especiales dependientes de la máquina

machine_func - operaciones internas especializadas que devuelven un valor
machine_proc - operaciones internas especializadas que no devuelven ningún valor



2.11 Depuración

trace - activa o descativa dinámicamente el trazado
profile - activa o descativa dinámicamente el análisis de perfiles de ejecución



2.12 Gráficos & Sonido

Las siguientes rutinas le permiten mostrar información en pantalla. En DOS, la pantalla de la PC puede estar en uno de muchos modos gráficos. Para ver una descripción de estos modos, consulte la perte superior de include\graphics.e. Hay dos tipos básicos de modo gráfico disponible: los modos de texto que dividen la pantalla en líneas, donde cada línea tiene una cierta cantidad de caracteres y los modos gráficos de píxel que dividen la pantalla en filas de puntos o "pìxeles". Cada píxel puede ser de un color diferente. En los modos de texto, solamente se puede mostrar texto, eligiendo para cada caracter el color de frente y fondo. En los modos gráficos de pìxel, se pueden mostrar líneas, círculos, puntos y también texto. Cualquier píxel que quedase fuera de la pantalla, será recortado en forma segura.

Para DOS32 hemos incluido una rutina para producir sonidos en el parlante de la PC. Para hacer sonidos más sofisticados, obtenga la librería para Sound Blaster desarrollada por Jacques Deschenes. Está disponible en el sitio web de Euphoria.

Las siguientes rutinas trabajan en todos los modos gráficos de píxel y de texto:
clear_screen - limpia la pantalla
position - establece la línea y la columna del cursor
get_position - devuelve la línea y la columna del cursor
graphics_mode - selecciona un nuevo modo de gráficos de píxel o de texto(DOS32)
video_config - devuelve los parámetros del modo actual
scroll - desplaza el texto hacia arriba o hacia abajo
wrap - controla el "wrapping" de las líneas en el borde derecho de la pantalla
text_color - establece el color del texto
bk_color - establece el color de fondo
palette - cambia el color para un número de color (DOS32)
all_palette - cambia el color para todos los números de color (DOS32)
get_all_palette - obtiene los valores de la paleta para todos los colores (DOS32)
read_bitmap - lee un archivo de mapa de bits (.bmp) y devuelve una paleta y una secuencia de píxeles de 2D
save_bitmap - crea un archivo de mapa de bits (.bmp) dada una paleta y una secuencia de píxeles de 2D
get_active_page - devuelve la página en la que se está escribiendo actualmente (DOS32)
set_active_page - cambia la página en la que se está escribiendo actualmente (DOS32)
get_display_page - devuelve la página que se está mostrando actualmente (DOS32)
set_display_page - cambia la página que se está mostrando actualmente (DOS32)
sound - produce un sonido en el parlante de la PC (DOS32)

Las siguientes rutinas trabajan en los modos de texto solamente:
cursor - selecciona la forma del cursor
text_rows - establece la cantidad de líneas en una pantalla de texto
get_screen_char - obtiene un caracter desde la pantalla (DOS32, Linux)
put_screen_char - pone uno o más caracteres en la pantalla (DOS32, Linux)
save_text_image - guarda una región rectangular desde una pantalla de texto (DOS32, Linux)
display_text_image - muestra una imagen en una pantalla de texto (DOS32, Linux)

Las siguientes rutinas trabajan en los modos gráficos de píxel solamente (DOS32):
pixel - establece el color de un píxel o de un conjunto de píxeles
get_pixel - lee el color de un píxel o de un conjunto de píxeles
draw_line - conecta una serie de puntos gráficos con una línea
polygon - dibuja una figura de n lados
ellipse - dibuja una elipse o un círculo
save_screen - guarda la pantalla en un archivo de mapa de bits (.bmp)
save_image - guarda una región rectangular desde una pantalla gráfica de píxeles
display_image - muestra una imagen en una pantalla gráfica de píxeles



2.13 Interfaz a nivel de máquina

Hemos agrupado aquí una cantidad de rutinas que puede usar para acceder a su máquina a bajo nivel. Con esta interfaz de bajo nivel, puede leer y escribir en la memoria. También puede construir sus propias de lenguaje de máquina 386+ y llamarlas.

Algunas de las rutinas listadas más abajo no son seguras, en el sentido que Euphoria no puede protegerlo si las usa de forma incorrecta. Su programa, sino su sistema, podría caerse. Bajo DOS32, si referencia una mala dirección de memoria, frecuentemente será captura en forma segura por el expansor CauseWay DOS, y obtendrá un mensaje de error en pantalla, además de un volcado de información a nivel de la máquina en el archivo cw.err. Bajo WIN32, el sistema operativo mostrará un diálogo de terminación, dándole un mensaje de disgnóstico además de información del registro. Bajo Linux típicamente obtendrá una violación de segmento.

Nota:
Para asistir a los programadores en la depuración del código involucrado en esas rutinas inseguras, hemos suministrado safe.e, una alternativa a machine.e. Si copia euphoria\include\safe.e en el directorio que contiene su programa y renombra safe.e como machine.e en ese directorio, su programa correrá más seguro (aunque más lento) las versiones de esas rutinas de bajo nivel. safe.e puede capturar muchos errores, tales como la escritura en una mala posición de memoria. Vea los comentarios en la parte superior de safe.e para leer las instrucciones de como usar y configurarlo óptimamente para su programa.

Esas rutinas de interfaz a nivel de máquina son importantes porque le permiten a los programadores Euphoria a acceder a características de bajo nivel del hardware y del sistema operativo. Para algunas aplicaciones esto es esencial.

Las rutinas de código de máquina se pueden escribir a mano u obtenerlas de la salida desensablada de un compilador de C o de algún otro lenguaje. Pete Eberlein escribió un "mini-assembler" para usarlo con Euphoria. Véalo en el Archivo. Recuerde que su código de máquina correrá en modo protegido de 32 bits. Vea un ejemplo en demo\callmach.ex.

peek - lee uno o más bytes desde la memoria
peek4s - lee valores de 4 bytes con signo desde la memoria
peek4u - lee valores de 4 bytes sin signo desde la memoria
poke - escribe uno o más bytes en la memoria
poke4 - escribe valores de 4 bytes en la memoria
mem_copy - copia un bloque de memoria
mem_set - establece un bloque de memoria a un valor
call - llama a una rutina en lenguaje de máquina
dos_interrupt - llama a una interrupción de software de DOS (DOS32)
allocate - asigna un bloque de memoria
free - desasigna un bloque de memoria
allocate_low - asigna un bloque de memoria baja (direcciones menores que 1Mb) (DOS32)
free_low - libera un bloque asignado con allocate_low (DOS32)
allocate_string - asigna una cadena de caracteres con el terminador 0
register_block - registra un bloque de memoria asignado externamente
unregister_block - desregistra un bloque de memoria asignado externamente
get_vector - devuelve la dirección de un vector de interrupciones (DOS32)
set_vector - establece la dirección de un vector de interrupciones (DOS32)
lock_memory - asegura que una región de memoria nunca será swapped out (DOS32)
int_to_bytes - convierte un entero a 4 bytes
bytes_to_int - convierte 4 bytes en un entero
int_to_bits - convierte un entero en una secuencia de bits
bits_to_int - convierte una secuencia de bits en un entero
atom_to_float64 - convierte un átomo en una secuencia de 8 bytes en formato IEEE de punto flotante de 64 bits
atom_to_float32 - convierte un átomo en una secuencia de 4 bytes en formato IEEE de punto flotante de 32 bits
float64_to_atom - convierte una secuencia de 8 bytes en formato IEEE de punto flotante de 64 bits en un átomo
float32_to_atom - convierte una secuencia de 4 bytes en formato IEEE de punto flotante de 32 bits en un átomo
set_rand -
establece el generador de números aleatorios, por lo que generará una serie repetible de números aleatorios
use_vesa - fuerza el uso del estándar de gráficos VESA (DOS32)
crash_file - especifica el archivo para escribir el disgnóstico de error si Euphoria detecta un error en su programa
crash_message - especifica el mensaje a imprimirse si Euphoria detecta un error en su programa



2.14 Llamadas dinámicas

Estas rutinas le permiten llamar a procedimientos y funciones de Euphoria, usando un número entero único llamado identificador de rutina, en lugar de especificar el nombre de la rutina.

routine_id - obtiene un único número identificador para una rutina Euphoria
call_proc - llama a un procedimiento Euphoria usando un routine id
call_func - llama a una función Euphoria usando un routine id



2.15 Llamando funciones de C (WIN32 y Linux)

Vea en platform.doc una descripción de la programación en Euphoria para WIN32 y Linux.

open_dll -
abre una librería de enlace dinámico de Windows (archivo .dll) o una librería compartida de Linux (archivo .so)
define_c_proc - define una función de C como VOID (sin valor de retorno), o cuyo valor ignorará el programa
define_c_func - define una función de C que devuelve un valor que usará el programa
define_c_var - obtiene la dirección de memoria de una variable de C
c_proc - llama a una función de C ignorando cualquier valor de retorno
c_func - llama a una función de C y obtiene su valor de retorno
call_back -
obtiene una dirección de máquina de 32 bits para una rutina Euphoria para usarla como dirección de call-back
message_box - emite una pequeña ventana para obtener una respuesta Si/No/Cancelar de parte del usuario
free_console - borra la ventana de texto de la consola
instance - obtiene el identificador de instancia del programa actual

... continua en 3. Listado alfabético de todas las rutinas, A a B