codexivo 0.2.0 → 1.0.0

package/src/runtime/prelude.ts

@@ -0,0 +1,230 @@
+import { parse } from '../syntax/parser';
+import { compileProcedure } from './compiler';
+import { COSTS } from './costs';
+import type { Chunk } from './compiler';
+import { Scope } from './values';
+import type { ProcedureDoc, ProcedureValue } from './values';
+
+/**
+ * Los procedimientos de la biblioteca que reciben procedimientos están escritos en Codexivo. Así, cuando
+ * llaman a `f`, la llamada pasa por la máquina como cualquier otra: se puede pausar dentro de `f`, cuenta
+ * para el límite de llamadas, emite sus eventos y sus operaciones se cuentan igual que siempre.
+ *
+ * Su propio código se compila como oculto (`Chunk.hidden`): no pausa ni emite pasos, y en lugar de contar
+ * cada instrucción se cobra lo que dice `costs.ts`. Los `revisar_*` y `ordenar_natural` son nativos internos
+ * que solo se ven desde aquí (`internals` en `builtins.ts`).
+ */
+const SOURCE = `
+procedimiento mapear(lista, f) {
+  revisar_lista("mapear", lista);
+  revisar_procedimiento("mapear", f);
+  variable resultado = [];
+  para_cada elemento en lista {
+    agregar(resultado, f(elemento));
+  }
+  regresa resultado;
+}
+
+procedimiento filtrar(lista, f) {
+  revisar_lista("filtrar", lista);
+  revisar_procedimiento("filtrar", f);
+  variable resultado = [];
+  para_cada elemento en lista {
+    si (revisar_logico("filtrar", f(elemento))) {
+      agregar(resultado, elemento);
+    }
+  }
+  regresa resultado;
+}
+
+procedimiento reducir(lista, f, inicial) {
+  revisar_lista("reducir", lista);
+  revisar_procedimiento("reducir", f);
+  variable acumulado = inicial;
+  para_cada elemento en lista {
+    acumulado = f(acumulado, elemento);
+  }
+  regresa acumulado;
+}
+
+procedimiento alguno(lista, f) {
+  revisar_lista("alguno", lista);
+  revisar_procedimiento("alguno", f);
+  para_cada elemento en lista {
+    si (revisar_logico("alguno", f(elemento))) {
+      regresa verdadero;
+    }
+  }
+  regresa falso;
+}
+
+procedimiento todos(lista, f) {
+  revisar_lista("todos", lista);
+  revisar_procedimiento("todos", f);
+  para_cada elemento en lista {
+    si (no revisar_logico("todos", f(elemento))) {
+      regresa falso;
+    }
+  }
+  regresa verdadero;
+}
+
+procedimiento buscar(lista, f) {
+  revisar_lista("buscar", lista);
+  revisar_procedimiento("buscar", f);
+  para_cada elemento en lista {
+    si (revisar_logico("buscar", f(elemento))) {
+      regresa elemento;
+    }
+  }
+  regresa nulo;
+}
+
+procedimiento ordenar(lista, va_antes) {
+  revisar_lista("ordenar", lista);
+  si (va_antes == nulo) {
+    regresa ordenar_natural(lista);
+  }
+  revisar_procedimiento("ordenar", va_antes);
+
+  // Ordenamiento por mezcla: estable, porque solo adelanta un elemento de la derecha si va antes.
+  procedimiento mezclar(parte) {
+    si (longitud(parte) <= 1) {
+      regresa copiar(parte);
+    }
+    variable medio = longitud(parte) div 2;
+    variable izquierda = mezclar(rebanar(parte, 0, medio));
+    variable derecha = mezclar(rebanar(parte, medio, longitud(parte)));
+    variable resultado = [];
+    variable i = 0;
+    variable j = 0;
+    mientras (i < longitud(izquierda) y j < longitud(derecha)) {
+      si (revisar_logico("ordenar", va_antes(derecha[j], izquierda[i]))) {
+        agregar(resultado, derecha[j]);
+        j++;
+      } si_no {
+        agregar(resultado, izquierda[i]);
+        i++;
+      }
+    }
+    mientras (i < longitud(izquierda)) {
+      agregar(resultado, izquierda[i]);
+      i++;
+    }
+    mientras (j < longitud(derecha)) {
+      agregar(resultado, derecha[j]);
+      j++;
+    }
+    regresa resultado;
+  }
+  regresa mezclar(lista);
+}
+`;
+
+const each = (): ProcedureDoc['params'] => [
+  { name: 'lista', type: 'lista' },
+  { name: 'f', type: 'procedimiento' },
+];
+
+/** Documentación de cada procedimiento de `SOURCE`, para el catálogo. */
+export const libraryDocs: Readonly<Record<string, ProcedureDoc>> = {
+  mapear: {
+    level: 'avanzado',
+    category: 'procedimientos',
+    params: each(),
+    returns: 'lista',
+    description: 'Una lista nueva con el resultado de `f(x)` para cada elemento.',
+    examples: [{ code: 'mapear([1, 2, 3], procedimiento(x) { regresa x * 2 })', result: '[2, 4, 6]' }],
+  },
+  filtrar: {
+    level: 'avanzado',
+    category: 'procedimientos',
+    params: each(),
+    returns: 'lista',
+    description: 'Una lista nueva con los elementos para los que `f(x)` es `verdadero`.',
+    examples: [{ code: 'filtrar([1, 2, 3, 4], procedimiento(x) { regresa x mod 2 == 0 })', result: '[2, 4]' }],
+  },
+  reducir: {
+    level: 'avanzado',
+    category: 'procedimientos',
+    params: [...each(), { name: 'inicial', type: 'cualquiera' }],
+    returns: 'cualquiera',
+    description: 'Junta la lista en un solo valor: empieza con `inicial` y en cada elemento hace `f(acumulado, x)`.',
+    examples: [{ code: 'reducir([1, 2, 3], procedimiento(total, x) { regresa total + x }, 0)', result: '6' }],
+  },
+  alguno: {
+    level: 'avanzado',
+    category: 'procedimientos',
+    params: each(),
+    returns: 'lógico',
+    description: '`verdadero` si `f(x)` es `verdadero` para al menos un elemento.',
+    examples: [{ code: 'alguno([1, 5], procedimiento(x) { regresa x > 3 })', result: 'verdadero' }],
+  },
+  todos: {
+    level: 'avanzado',
+    category: 'procedimientos',
+    params: each(),
+    returns: 'lógico',
+    description: '`verdadero` si `f(x)` es `verdadero` para todos los elementos.',
+    examples: [{ code: 'todos([1, 5], procedimiento(x) { regresa x > 3 })', result: 'falso' }],
+  },
+  buscar: {
+    level: 'avanzado',
+    category: 'procedimientos',
+    params: each(),
+    returns: 'cualquiera',
+    description: 'El primer elemento para el que `f(x)` es `verdadero`, o `nulo` si no hay.',
+    examples: [{ code: 'buscar([1, 5, 7], procedimiento(x) { regresa x > 3 })', result: '5' }],
+  },
+  ordenar: {
+    level: 'intermedio',
+    category: 'listas',
+    params: [
+      { name: 'lista', type: 'lista' },
+      { name: 'va_antes', type: 'procedimiento', optional: true },
+    ],
+    returns: 'lista',
+    description:
+      'Una lista nueva ordenada. Sin comparador, todos tienen que ser números o todos textos; `va_antes(a, b)` responde «¿va `a` antes que `b`?». Es estable.',
+    examples: [
+      { code: 'ordenar([3, 1, 2])', result: '[1, 2, 3]' },
+      { code: 'ordenar([3, 1, 2], procedimiento(a, b) { regresa a > b })', result: '[3, 2, 1]' },
+    ],
+  },
+};
+
+/** Parámetros que se pueden omitir (llegan como `nulo`). */
+const OPTIONAL: Readonly<Record<string, number>> = { ordenar: 1 };
+
+const compileLibrary = (): Map<string, Chunk> => {
+  const { program, errors } = parse(SOURCE);
+  if (errors.length > 0) throw new Error(`La biblioteca en Codexivo tiene errores: ${errors[0]!.message}`);
+  const chunks = new Map<string, Chunk>();
+  for (const statement of program.statements) {
+    if (statement.kind !== 'FunctionDeclaration') continue;
+    const chunk = compileProcedure(statement.function, true);
+    const optional = OPTIONAL[statement.name.name];
+    if (optional !== undefined) chunk.minParams = optional;
+    chunks.set(statement.name.name, chunk);
+  }
+  return chunks;
+};
+
+/**
+ * Los procedimientos de la biblioteca escritos en Codexivo, por nombre. Son inmutables, así que todas las
+ * máquinas los comparten. Sus `id` son negativos para no mover los de los valores del programa.
+ */
+export const libraryProcedures: Readonly<Record<string, ProcedureValue>> = (() => {
+  const scope = new Scope();
+  const table: Record<string, ProcedureValue> = {};
+  let id = -1;
+  for (const [name, chunk] of compileLibrary()) {
+    const procedure: ProcedureValue = { kind: 'procedimiento', id: id--, name, chunk, closure: scope };
+    scope.variables.set(name, procedure);
+    table[name] = procedure;
+  }
+  return table;
+})();
+
+/** Costo de llamar a un procedimiento de la biblioteca escrito en Codexivo. */
+export const libraryCost = (name: string) => COSTS[name];

package/src/runtime/values.ts

@@ -1,4 +1,5 @@
 import type { CodexivoError } from '../errors';
+import type { RobotEvent } from '../world';
 import type { Chunk } from './compiler';
 
 /**
@@ -6,7 +7,8 @@ import type { Chunk } from './compiler';
  * listas y procedimientos son objetos con un `id` para poder dibujar cuándo dos variables
  * comparten el mismo valor.
  */
-export type Value = number | string | boolean | null | ListValue | ProcedureValue | NativeValue;
+export type Value =
+  number | string | boolean | null | ListValue | DictValue | DomainValue | ProcedureValue | NativeValue;
 
 export interface ListValue {
   kind: 'lista';
@@ -14,6 +16,28 @@ export interface ListValue {
   items: Value[];
 }
 
+/** Clave de un diccionario: un texto o un número. */
+export type DictKey = string | number;
+
+/** Diccionario: conserva el orden en que se agregaron las claves. */
+export interface DictValue {
+  kind: 'diccionario';
+  id: number;
+  entries: Map<DictKey, Value>;
+}
+
+/**
+ * Un `dominio`: un espacio de nombres. Sus miembros son las variables de `scope`; desde fuera se usan con `.` y
+ * solo se pueden cambiar los que se declararon con `variable` (`writable`).
+ */
+export interface DomainValue {
+  kind: 'dominio';
+  id: number;
+  name: string;
+  scope: Scope;
+  writable: ReadonlySet<string>;
+}
+
 export interface ProcedureValue {
   kind: 'procedimiento';
   id: number;
@@ -28,21 +52,70 @@ export interface NativeContext {
   /** Siguiente línea de entrada, `null` si ya no hay, o `WAIT_FOR_INPUT` si hay que pedirla. */
   readLine(): string | null | typeof WAIT_FOR_INPUT;
   newList(items: Value[]): ListValue;
+  newDict(entries: Map<DictKey, Value>): DictValue;
+  /** Número pseudoaleatorio en [0, 1) del generador con semilla de la máquina. */
+  random(): number;
   /** Error de ejecución ubicado en la llamada actual. */
   fail(code: string, message: string, hint?: string): CodexivoError;
+  /** Emite un evento propio del procedimiento (el modo mundo emite `robot`), ubicado en la llamada actual. */
+  emit(event: RobotEvent): void;
 }
 
 export const WAIT_FOR_INPUT: unique symbol = Symbol('esperar-entrada');
 
+export type ProcedureLevel = 'principiante' | 'intermedio' | 'avanzado';
+
+export type ProcedureCategory =
+  | 'entrada y salida'
+  | 'tipos'
+  | 'verificación'
+  | 'matemáticas'
+  | 'texto'
+  | 'listas'
+  | 'diccionarios'
+  | 'procedimientos'
+  | 'estructuras'
+  | 'mundo';
+
+/** Ejemplo ejecutable de un procedimiento: `result` es el valor final como se escribiría en código. */
+export interface ProcedureExample {
+  code: string;
+  result?: string;
+  output?: string;
+}
+
+/** Documentación de un procedimiento de la biblioteca; de aquí sale el catálogo (`catalog.ts`). */
+export interface ProcedureDoc {
+  level: ProcedureLevel;
+  category: ProcedureCategory;
+  /** Tipos con los nombres de `tipo(x)`, `cualquiera`, o varios separados por ` | `. */
+  params: Array<{ name: string; type: string; optional?: boolean }>;
+  /** `true` si el último parámetro se puede repetir (`imprimir(a, b, …)`). */
+  variadic?: boolean;
+  /** Lo que regresa; `nulo` si no regresa nada útil. */
+  returns: string;
+  /** `true` si cambia su primer argumento. */
+  mutates?: boolean;
+  description: string;
+  examples: ProcedureExample[];
+}
+
 export interface NativeValue {
   kind: 'nativo';
   name: string;
+  /** Documentación para el catálogo. Los nativos internos de la biblioteca no la tienen. */
+  doc?: ProcedureDoc;
   /** Cantidad de argumentos: exacta, o `[mínimo, máximo]` (`máximo` puede ser `Infinity`). */
   arity: number | [number, number];
   call(args: Value[], context: NativeContext): Value | typeof WAIT_FOR_INPUT;
+  /**
+   * Cuántas operaciones debería costar una llamada con estos argumentos (§10). Sin `cost`, cuesta 1.
+   * Se registra aquí para que la tabla de costos viva junto a cada procedimiento.
+   */
+  cost?: (args: Value[]) => number;
 }
 
-export type TypeName = 'número' | 'texto' | 'lógico' | 'nulo' | 'lista' | 'procedimiento';
+export type TypeName = 'número' | 'texto' | 'lógico' | 'nulo' | 'lista' | 'diccionario' | 'dominio' | 'procedimiento';
 
 export const typeOf = (value: Value): TypeName => {
   if (value === null) return 'nulo';
@@ -54,7 +127,9 @@ export const typeOf = (value: Value): TypeName => {
     case 'boolean':
       return 'lógico';
     default:
-      return value.kind === 'lista' ? 'lista' : 'procedimiento';
+      return value.kind === 'lista' || value.kind === 'diccionario' || value.kind === 'dominio'
+        ? value.kind
+        : 'procedimiento';
   }
 };
 
@@ -73,6 +148,12 @@ export const describeType = (type: TypeName): string => {
 export const isList = (value: Value): value is ListValue =>
   typeof value === 'object' && value !== null && value.kind === 'lista';
 
+export const isDomain = (value: Value): value is DomainValue =>
+  typeof value === 'object' && value !== null && value.kind === 'dominio';
+
+export const isDict = (value: Value): value is DictValue =>
+  typeof value === 'object' && value !== null && value.kind === 'diccionario';
+
 export const isCallable = (value: Value): value is ProcedureValue | NativeValue =>
   typeof value === 'object' && value !== null && (value.kind === 'procedimiento' || value.kind === 'nativo');
 
@@ -84,7 +165,7 @@ const formatNumber = (value: number): string => {
 };
 
 /** Representación como se escribiría en código: los textos van entre comillas. */
-export const repr = (value: Value, seen: Set<ListValue> = new Set()): string => {
+export const repr = (value: Value, seen: Set<ListValue | DictValue> = new Set()): string => {
   if (value === null) return 'nulo';
   switch (typeof value) {
     case 'number':
@@ -94,12 +175,16 @@ export const repr = (value: Value, seen: Set<ListValue> = new Set()): string =>
     case 'boolean':
       return value ? 'verdadero' : 'falso';
   }
-  if (value.kind === 'lista') {
-    if (seen.has(value)) return '[…]';
+  if (value.kind === 'dominio') return `dominio ${value.name}`;
+  if (value.kind === 'lista' || value.kind === 'diccionario') {
+    if (seen.has(value)) return value.kind === 'lista' ? '[…]' : '{…}';
     seen.add(value);
-    const inner = value.items.map(item => repr(item, seen)).join(', ');
+    const inner =
+      value.kind === 'lista'
+        ? value.items.map(item => repr(item, seen))
+        : [...value.entries].map(([key, item]) => `${repr(key)}: ${repr(item, seen)}`);
     seen.delete(value);
-    return `[${inner}]`;
+    return value.kind === 'lista' ? `[${inner.join(', ')}]` : `{${inner.join(', ')}}`;
   }
   return value.name ? `procedimiento ${value.name}` : 'procedimiento';
 };
@@ -107,18 +192,31 @@ export const repr = (value: Value, seen: Set<ListValue> = new Set()): string =>
 /** Como lo muestra `imprimir`: los textos sin comillas. */
 export const show = (value: Value): string => (typeof value === 'string' ? value : repr(value));
 
-/** Igualdad por valor: dos listas son iguales si tienen los mismos elementos en el mismo orden. */
-export const equals = (a: Value, b: Value, seen: Array<[ListValue, ListValue]> = []): boolean => {
+type Container = ListValue | DictValue;
+
+/**
+ * Igualdad por valor: dos listas son iguales si tienen los mismos elementos en el mismo orden, y dos
+ * diccionarios si tienen las mismas claves con los mismos valores, en cualquier orden.
+ */
+export const equals = (a: Value, b: Value, seen: Array<[Container, Container]> = []): boolean => {
   if (a === b) return true;
-  if (isList(a) && isList(b)) {
-    if (a.items.length !== b.items.length) return false;
-    if (seen.some(([x, y]) => x === a && y === b)) return true;
-    seen.push([a, b]);
-    const result = a.items.every((item, index) => equals(item, b.items[index]!, seen));
-    seen.pop();
-    return result;
+  const bothLists = isList(a) && isList(b);
+  const bothDicts = isDict(a) && isDict(b);
+  if (!bothLists && !bothDicts) return false;
+  if (seen.some(([x, y]) => x === a && y === b)) return true;
+  seen.push([a as Container, b as Container]);
+  let result: boolean;
+  if (bothLists) {
+    const [x, y] = [a as ListValue, b as ListValue];
+    result = x.items.length === y.items.length && x.items.every((item, index) => equals(item, y.items[index]!, seen));
+  } else {
+    const [x, y] = [a as DictValue, b as DictValue];
+    result =
+      x.entries.size === y.entries.size &&
+      [...x.entries].every(([key, item]) => y.entries.has(key) && equals(item, y.entries.get(key)!, seen));
   }
-  return false;
+  seen.pop();
+  return result;
 };
 
 /**
@@ -126,6 +224,10 @@ export const equals = (a: Value, b: Value, seen: Array<[ListValue, ListValue]> =
  */
 export class Scope {
   readonly variables = new Map<string, Value>();
+  /** Nombres de este alcance declarados con `constante`. */
+  readonly constants = new Set<string>();
+  /** Variables de `para … desde … hasta` en este alcance: avanzan solas. */
+  readonly loopVariables = new Set<string>();
 
   constructor(readonly parent?: Scope) {}