Índice

Apéndice B: Módulos de la biblioteca estándar

Nyx incluye 37 módulos en la biblioteca estándar. Importalos con import "std/nombre_modulo".

Core

Módulo Descripción
std/prelude Auto-cargado. Define Option, Result, traits de operadores (Add, Sub, Mul, Eq, Ord, Display), e implementaciones por defecto. Nunca necesitas importar esto — siempre está disponible.
std/math Funciones matemáticas: abs, min, max, pow, sqrt, floor, ceil, round, log, sin, cos, tan, PI, E.
std/math_ext Matemáticas extendidas: gcd, lcm, factorial, fibonacci, is_prime, clamp, lerp, operaciones con matrices.
std/array Utilidades de arrays: map, filter, reduce, zip, enumerate, flatten, chunk, take, skip, find, any, all, sort_by, group_by, unique.
std/map Utilidades de maps: map_from_arrays, map_merge, map_filter, map_map_values, map_invert.
std/io Utilidades de I/O: read_line (stdin), print_err, format.

Estructuras de datos

Módulo Descripción
std/collections Set (respaldado por Map), Deque (cola de doble extremo), PriorityQueue (min-heap).
std/btreemap Mapa de árbol binario balanceado. Claves ordenadas, operaciones O(log n).
std/linkedlist Lista doblemente enlazada. Inserción/eliminación O(1) en cabeza/cola.
std/graph Estructura de datos de grafo con BFS, DFS, camino más corto de Dijkstra, ordenamiento topológico.
std/matrix Operaciones con matrices: crear, multiplicar, transponer, determinante, identidad.

Formatos de datos

Módulo Descripción
std/json Parser y serializador JSON. json_parse(str) -> Map, json_stringify(map) -> String. Maneja objetos anidados, arrays, strings, números, booleanos, null.
std/toml Parser TOML. toml_parse(str) -> Map. Soporta tablas, arrays, strings, enteros, booleanos.
std/csv Lector/escritor CSV. csv_parse(str) -> Array, csv_stringify(rows) -> String. Maneja campos entrecomillados y escape.
std/msgpack Serialización binaria MessagePack. msgpack_encode(value) -> String, msgpack_decode(bytes) -> value. Formato binario compacto.

Archivo e I/O

Módulo Descripción
std/file Operaciones de archivo: read_file(path) -> String, write_file(path, content), file_exists(path) -> bool, file_size(path) -> int, list_dir(path) -> Array, delete_file(path), rename_file(old, new).
std/compress Compresión zlib: deflate(data) -> String, inflate(data) -> String.

Networking

Módulo Descripción
std/http Servidor y cliente HTTP. Servidor: http_serve(port, handler), http_serve_mt(port, workers, handler). Cliente: http_get(url), http_post(url, body). Maneja requests como [id, method, path, headers, body].
std/web Framework web: structs App/Request/Response, routing (app_get, app_post, app_put, app_delete), cadena de middleware (app_use, mw_logging, mw_cors), APIs JSON (req_json, response_json_map), servicio de archivos estáticos, parsing de query/formularios.
std/http2 Servidor HTTP/2 (h2c cleartext). h2_serve(port, workers, callback) — el callback recibe (method, path, headers, body) y retorna [status, headers, body]. Framing binario, compresión de headers HPACK, multiplexación de streams. I/O de frames en C (runtime/http2.c).
std/session Sesiones con cookies almacenadas en nyx-kv via RESP. session_configure(host, port, ttl), session_start(req, resp), session_get(req, key), session_set(req, key, value), session_destroy(req, resp).
std/url Codificación/decodificación URL: url_encode(str) -> String, url_decode(str) -> String, url_parse(str) -> Map.
std/websocket WebSocket RFC 6455: handshake, codificación/decodificación de frames, ws_send, ws_recv.
std/proxy Utilidades de proxy inverso: selección de backend, round-robin, health checking, forwarding de headers.

Concurrencia

Módulo Descripción
std/sync Primitivas de sincronización: WaitGroup (esperar N tareas), Semaphore (limitar concurrencia), Once (ejecutar exactamente una vez), AtomicCounter (contador thread-safe), Barrier (sincronizar N threads).

Base de datos

Módulo Descripción
std/sqlite Bindings SQLite3 (via dlopen): db_open(path), db_exec(db, sql), db_query(db, sql) -> Array, db_close(db). Soporta transacciones, sentencias preparadas, migraciones.
std/pool Pool de conexiones: pool_new(factory, size), pool_acquire(pool), pool_release(pool, conn). Genérico — funciona con cualquier recurso.

Seguridad

Módulo Descripción
std/regex Expresiones regulares POSIX: regex_match(pattern, text) -> bool, regex_find(pattern, text) -> Array, regex_replace(pattern, text, replacement) -> String.
std/random Generación de números aleatorios (xorshift64): random_int(min, max), random_float(), random_choice(array), random_shuffle(array).
std/uuid Generación de UUID: uuid_v4() -> String.

Texto y codificación

Módulo Descripción
std/semver Versionado semántico: semver_parse(str) -> Map, semver_compare(a, b) -> int, semver_satisfies(version, range) -> bool.
std/base64 Codificación/decodificación Base64 y Base64URL: base64_encode(str) -> String, base64_decode(str) -> String, base64url_encode(str) -> String, base64url_decode(str) -> String.

Patrones y arquitectura

Módulo Descripción
std/events Event bus / patrón observable: event_bus_new(), on(bus, event, handler), emit(bus, event, data). Comunicación pub/sub desacoplada.
std/statemachine Máquina de estados finita genérica: fsm_new(states, transitions), fsm_transition(fsm, event), fsm_current(fsm).
std/owned Wrappers de ownership: Box (propiedad única), Rc (conteo de referencias), MoveOnly (no copiable). Basado en convención, no enforced por el compilador.
std/proptest Testing basado en propiedades (estilo QuickCheck): prop_check(name, generator, property), generación de inputs aleatorios, shrinking en fallo.

Sistema

Módulo Descripción
std/log Logging: log_info(msg), log_warn(msg), log_error(msg), log_debug(msg). Nivel de log y salida configurables.
std/args Parsing de argumentos de línea de comandos: args_parse(spec) -> Map. Soporta flags, opciones con valores, argumentos posicionales, generación de ayuda.

Builtins del runtime (agregados en v0.12.0)

Estas funciones están implementadas en el runtime C y disponibles sin imports:

Función Descripción
hmac_sha256(key, data) Código de autenticación HMAC-SHA256. Retorna string hexadecimal.
getenv_default(name, default) Leer variable de entorno con valor por defecto.
crc32_bytes(data, len) Checksum CRC32 para datos binarios.
string_from_bytes(ptr, len) Crear un string Nyx desde un puntero raw de bytes y longitud.
rename_file(old, new) Renombrar un archivo atómicamente.
tcp_read_exact(fd, n) Leer exactamente n bytes de un socket TCP. Bloquea hasta que lleguen todos.
setup_shutdown_handler(callback) Registrar un callback para señales SIGTERM/SIGINT.

Builtins de Terminal I/O (agregados en v0.12.0)

Estas funciones proveen acceso raw al terminal para construir aplicaciones TUI interactivas:

Función Descripción
raw_mode_enter() Poner terminal en modo raw (sin eco, sin buffering de línea). Usar con defer { raw_mode_exit() } para limpieza segura.
raw_mode_exit() Restaurar terminal a modo normal (cooked).
read_byte() Leer un solo byte de stdin. Devuelve int (0-255), o -1 en EOF.
chr(code) Convertir un código ASCII (int) a un String de un carácter. Ejemplo: chr(65) devuelve "A".
term_cols() Devolver ancho del terminal en columnas (default 80 si no disponible).
term_rows() Devolver alto del terminal en filas (default 24 si no disponible).

Array insert/remove (agregados en v0.12.0)

Los arrays ahora soportan inserción y eliminación en posiciones arbitrarias:

Método Descripción
arr.insert(índice, valor) Insertar valor en índice, desplazando los elementos siguientes a la derecha. Tiempo O(n).
arr.remove(índice) Quitar y devolver el elemento en índice, desplazando los elementos siguientes a la izquierda. Tiempo O(n).

Builtins de control de procesos (agregados en v0.12.0)

Primitivas POSIX para construir shells, pipelines y gestores de procesos:

Funcion Descripcion
fork()Fork del proceso. Retorna 0 en hijo, pid en padre, -1 en error.
execvp(programa, args)Reemplaza imagen del proceso con programa. args es un Array de Strings.
waitpid(pid, opts)Espera hijo. opts: 0=bloquear, 1=WNOHANG. Retorna exit status.
dup2(old_fd, new_fd)Redirige file descriptor new_fd para referir a old_fd.
pipe_new()Crea un pipe. Retorna [read_fd, write_fd].
close_fd(fd)Cierra un file descriptor raw.
open_fd(path, mode)Abre archivo retornando fd raw. mode: 0=lectura, 1=escritura(trunc), 2=append.
getcwd()Retorna directorio actual como String.
chdir(path)Cambia directorio de trabajo. Retorna 0 en exito.
stat(path)Info de archivo: [size, mode, mtime, is_dir, is_file].
isatty(fd)Retorna 1 si fd es terminal, 0 si no.
getpid()Retorna PID del proceso actual.
kill_process(pid, sig)Envia signal al proceso (ej. 15=SIGTERM, 9=SIGKILL).

Seguridad GC: Despues de fork(), el hijo debe llamar execvp() inmediatamente sin alocar memoria GC.

Ejemplo de uso

import "std/json"
import "std/http"
import "std/file"

fn main() {
    // Leer y parsear un archivo de configuración
    let config_text: String = read_file("config.json")
    let config: Map = json_parse(config_text)

    let port: int = string_to_int(config.get("port"))

    // Iniciar un servidor web
    http_serve_mt(port, 4, fn(req: Array) -> String {
        return http_response(200, "¡Hola desde Nyx!")
    })
}

← Volver al Índice

← Anterior: Apéndice A: Referencia rápida de sintaxis Siguiente: Apéndice C: Mensajes de error comunes →