codexivo 0.0.0-stage → 0.2.3

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/suggest.ts

@@ -0,0 +1,33 @@
+const distance = (a: string, b: string): number => {
+  const previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i++) {
+    let diagonal = previous[0]!;
+    previous[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const above = previous[j]!;
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      previous[j] = Math.min(previous[j]! + 1, previous[j - 1]! + 1, diagonal + cost);
+      diagonal = above;
+    }
+  }
+  return previous[b.length]!;
+};
+
+const fold = (text: string): string => text.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+
+/** El nombre más parecido a `name` entre `candidates`, si hay uno razonablemente cerca. */
+export const suggestName = (name: string, candidates: Iterable<string>): string | undefined => {
+  const target = fold(name);
+  const limit = target.length <= 3 ? 1 : 2;
+  let best: string | undefined;
+  let bestDistance = Infinity;
+  for (const candidate of new Set(candidates)) {
+    if (candidate === name) continue;
+    const current = distance(target, fold(candidate));
+    if (current <= limit && current < bestDistance) {
+      best = candidate;
+      bestDistance = current;
+    }
+  }
+  return best;
+};

package/src/runtime/values.ts

@@ -0,0 +1,241 @@
+import type { CodexivoError } from '../errors';
+import type { RobotEvent } from '../world';
+import type { Chunk } from './compiler';
+
+/**
+ * Valores en tiempo de ejecución. Números, textos, lógicos y `nulo` son primitivos de JavaScript;
+ * 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 | DictValue | DomainValue | ProcedureValue | NativeValue;
+
+export interface ListValue {
+  kind: 'lista';
+  id: number;
+  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;
+  name?: string;
+  chunk: Chunk;
+  closure: Scope;
+}
+
+/** Contexto que la máquina le da a los procedimientos nativos. */
+export interface NativeContext {
+  write(text: string): void;
+  /** 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'
+  | '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' | 'diccionario' | 'dominio' | 'procedimiento';
+
+export const typeOf = (value: Value): TypeName => {
+  if (value === null) return 'nulo';
+  switch (typeof value) {
+    case 'number':
+      return 'número';
+    case 'string':
+      return 'texto';
+    case 'boolean':
+      return 'lógico';
+    default:
+      return value.kind === 'lista' || value.kind === 'diccionario' || value.kind === 'dominio'
+        ? value.kind
+        : 'procedimiento';
+  }
+};
+
+/** "un número", "una lista"… para mensajes. */
+export const describeType = (type: TypeName): string => {
+  switch (type) {
+    case 'lista':
+      return 'una lista';
+    case 'nulo':
+      return '`nulo`';
+    default:
+      return `un ${type}`;
+  }
+};
+
+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');
+
+const formatNumber = (value: number): string => {
+  if (Object.is(value, -0)) return '0';
+  if (value === Infinity) return 'infinito';
+  if (value === -Infinity) return '-infinito';
+  return String(value);
+};
+
+/** Representación como se escribiría en código: los textos van entre comillas. */
+export const repr = (value: Value, seen: Set<ListValue | DictValue> = new Set()): string => {
+  if (value === null) return 'nulo';
+  switch (typeof value) {
+    case 'number':
+      return formatNumber(value);
+    case 'string':
+      return JSON.stringify(value);
+    case 'boolean':
+      return value ? 'verdadero' : 'falso';
+  }
+  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.kind === 'lista'
+        ? value.items.map(item => repr(item, seen))
+        : [...value.entries].map(([key, item]) => `${repr(key)}: ${repr(item, seen)}`);
+    seen.delete(value);
+    return value.kind === 'lista' ? `[${inner.join(', ')}]` : `{${inner.join(', ')}}`;
+  }
+  return value.name ? `procedimiento ${value.name}` : 'procedimiento';
+};
+
+/** Como lo muestra `imprimir`: los textos sin comillas. */
+export const show = (value: Value): string => (typeof value === 'string' ? value : repr(value));
+
+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;
+  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));
+  }
+  seen.pop();
+  return result;
+};
+
+/**
+ * Un alcance: las variables de un bloque. `parent` apunta al alcance que lo contiene.
+ */
+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) {}
+
+  lookup(name: string): Scope | undefined {
+    let scope: Scope | undefined = this;
+    while (scope) {
+      if (scope.variables.has(name)) return scope;
+      scope = scope.parent;
+    }
+    return undefined;
+  }
+}