@mirascript/mirascript 0.1.0

package/src/vm/lib/_helpers.ts

@@ -0,0 +1,215 @@
+import { VmError } from '../error.js';
+import { $ToNumber, $Type } from '../operations.js';
+import {
+    isVmArray,
+    isVmExtern,
+    isVmFunction,
+    type VmExtern,
+    type VmFunction,
+    type VmAny,
+    type VmArray,
+    type VmValue,
+    isVmRecord,
+    type VmRecord,
+    type VmModule,
+    isVmPrimitive,
+    type VmConst,
+    isVmConst,
+    VM_ARRAY_MAX_LENGTH,
+} from '../types/index.js';
+import type { VmFunctionLike, VmFunctionOption } from '../types/function.js';
+import { Cp } from '../helpers.js';
+import { isNaN, entries, fromEntries } from '../../helpers/utils.js';
+
+/** 抛出异常 */
+export function throwError(message: string, recovered: VmAny | (() => VmAny)): never {
+    const recoveredValue = typeof recovered === 'function' && !isVmFunction(recovered) ? recovered() : recovered;
+    throw new VmError(message, recoveredValue);
+}
+
+/** 抛出预期外类型异常 */
+export function throwUnexpectedTypeError(
+    name: string | number,
+    expected: string,
+    value: VmAny,
+    recovered: VmAny | (() => VmAny),
+): never {
+    const actual = $Type(value);
+    if (typeof name == 'string') throwError(`Expected ${expected} for parameter '${name}', got ${actual}`, recovered);
+    const pos = name <= 0 ? 'first' : name <= 1 ? 'second' : name + 1 + 'th';
+    throwError(`Expected ${expected} at the ${pos} position, got ${actual}`, recovered);
+}
+
+/** 重新抛出异常 */
+export function rethrowError(prefix: string, error: unknown, recovered: VmAny | (() => VmAny)): never {
+    const recoveredValue = typeof recovered === 'function' && !isVmFunction(recovered) ? recovered() : recovered;
+    throw VmError.from(prefix, error, recoveredValue);
+}
+
+/** 标记参数为必须项 */
+export function required<const T = VmValue>(
+    name: string | number,
+    value: T | undefined,
+    recovered: VmAny | (() => VmAny),
+): asserts value is T {
+    if (value === undefined) {
+        if (typeof name == 'string') throwError(`Missing required parameter '${name}'`, recovered);
+        const pos = name <= 0 ? 'first' : name <= 1 ? 'second' : name + 1 + 'th';
+        throwError(`Missing required parameter at the ${pos} position`, recovered);
+    }
+}
+
+/** 标记参数为数组 */
+export function expectArray(
+    name: string | number,
+    value: VmAny,
+    recovered: VmAny | (() => VmAny),
+): asserts value is VmArray {
+    required(name, value, recovered);
+    if (!isVmArray(value)) {
+        throwUnexpectedTypeError(name, 'array', value, recovered);
+    }
+}
+
+/** 标记参数为记录 */
+export function expectRecord(
+    name: string | number,
+    value: VmAny,
+    recovered: VmAny | (() => VmAny),
+): asserts value is VmRecord {
+    required(name, value, recovered);
+    if (!isVmRecord(value)) {
+        throwUnexpectedTypeError(name, 'record', value, recovered);
+    }
+}
+
+/** 标记参数为数组或记录 */
+export function expectArrayOrRecord(
+    name: string | number,
+    value: VmAny,
+    recovered: VmAny | (() => VmAny),
+): asserts value is VmArray | VmRecord {
+    required(name, value, recovered);
+    if (!isVmArray(value) && !isVmRecord(value)) {
+        throwUnexpectedTypeError(name, 'array | record', value, recovered);
+    }
+}
+
+/** 标记参数为复合类型 */
+export function expectCompound(
+    name: string | number,
+    value: VmAny,
+    recovered: VmAny | (() => VmAny),
+): asserts value is VmArray | VmRecord | VmModule | VmExtern {
+    required(name, value, recovered);
+    if (isVmPrimitive(value) || isVmFunction(value)) {
+        throwUnexpectedTypeError(name, 'array | record | module | extern', value, recovered);
+    }
+}
+
+/** 标记参数为常量 */
+export function expectConst(
+    name: string | number,
+    value: VmAny,
+    recovered: VmAny | (() => VmAny),
+): asserts value is VmConst {
+    required(name, value, recovered);
+    if (!isVmConst(value)) {
+        throwUnexpectedTypeError(name, 'nil | number | boolean | string | array | record', value, recovered);
+    }
+}
+
+/** 标记为可调用 */
+export function expectCallable(
+    name: string | number,
+    value: VmAny,
+    recovered: VmAny | (() => VmAny),
+): asserts value is VmFunction | VmExtern {
+    required(name, value, recovered);
+    const callable = isVmFunction(value) || isVmExtern(value);
+    if (!callable) {
+        throwUnexpectedTypeError(name, 'callable', value, recovered);
+    }
+}
+
+/** Get numbers from the arguments. */
+export function getNumbers(args: readonly VmAny[]): number[] {
+    if (args.length === 0) return [];
+    if (args.length === 1 && isVmArray(args[0])) args = args[0];
+    const numbers: number[] = [];
+    for (const arg of args) {
+        if (arg == null) continue;
+        numbers.push($ToNumber(arg));
+    }
+    return numbers;
+}
+
+/** 将值转为数组长度 */
+export function arrayLen(len: number | null | undefined): number {
+    if (len == null || isNaN(len) || len <= 0) return 0;
+    len = Math.trunc(len);
+    if (len > VM_ARRAY_MAX_LENGTH) throwError(`Array length exceeds maximum limit of ${VM_ARRAY_MAX_LENGTH}`, null);
+    return len;
+}
+
+/** 应用映射函数 */
+export function map(
+    data: VmConst,
+    mapper: (value: VmConst, index: number | string | null, data: VmConst) => VmConst | undefined,
+): VmConst {
+    if (isVmPrimitive(data)) {
+        return mapper(data, null, data) ?? null;
+    }
+    if (isVmArray(data)) {
+        const result: VmConst[] = [];
+        const { length } = data;
+        for (let i = 0; i < length; i++) {
+            Cp();
+            const ret = mapper(data[i] ?? null, i, data);
+            if (ret === undefined) continue;
+            if (isVmConst(ret)) {
+                result.push(ret);
+            } else {
+                result.push(null);
+            }
+        }
+        return result;
+    } else {
+        const e: Array<[string, VmConst]> = [];
+        for (const [key, value] of entries(data)) {
+            Cp();
+            const ret = mapper(value ?? null, key, data);
+            if (ret === undefined) continue;
+            if (isVmConst(ret)) {
+                e.push([key, ret]);
+            } else {
+                e.push([key, null]);
+            }
+        }
+        return fromEntries(e);
+    }
+}
+
+/** 库函数选项 */
+export type VmLibOption = Pick<
+    VmFunctionOption,
+    'summary' | 'params' | 'paramsType' | 'returns' | 'returnsType' | 'examples'
+>;
+/** 库函数 */
+export type VmLib<T extends VmFunctionLike = VmFunctionLike> = T & VmLibOption;
+
+/** 创建库函数 */
+export function VmLib<T extends VmFunctionLike>(fn: T, option: VmLibOption): VmLib<T> {
+    /* c8 ignore next 2 */
+    if (typeof fn != 'function') throw new TypeError('Invalid function');
+    if (isVmFunction(fn)) throw new TypeError('Cannot create VmLib from a VmFunction');
+
+    const ret = fn as T & VmLibOption as Writable<VmLibOption>;
+    ret.params = option.params;
+    ret.paramsType = option.paramsType;
+    ret.returns = option.returns;
+    ret.returnsType = option.returnsType;
+    ret.summary = option.summary;
+    ret.examples = option.examples;
+    return ret as T & VmLibOption;
+}

package/src/vm/lib/_loader.ts

@@ -0,0 +1,51 @@
+import { VmFunction, VmModule, type VmConst, type VmFunctionLike, type VmImmutable } from '../types/index.js';
+import { create, defineProperty, entries } from '../../helpers/utils.js';
+import { VmSharedContext } from '../types/context.js';
+
+import type { VmLib, VmLibOption } from './_helpers.js';
+import * as global from './global/index.js';
+
+for (const [name, value] of entries(global)) {
+    VmSharedContext[name] = wrapEntry(name, value as RawValue);
+}
+
+/** 原始值 */
+type RawValue = VmLib | VmConst | VmModule;
+/** 包装值 */
+type ToWrappedValue<V extends RawValue> = V extends VmFunctionLike ? VmFunction<V> : V;
+/** 包装值 */
+function wrapEntry<const T extends RawValue>(name: string, value: T): ToWrappedValue<T> {
+    if (typeof value == 'function') {
+        if (value.name !== name) {
+            // 如果函数名和导出名不一致，则重命名
+            defineProperty(value, 'name', {
+                value: name,
+                configurable: true,
+            });
+        }
+        return VmFunction(value, {
+            isLib: true,
+            injectCp: true,
+            fullName: `global.${name}`,
+            ...(value as VmLibOption),
+        }) as ToWrappedValue<T>;
+    } else {
+        return value as ToWrappedValue<T>;
+    }
+}
+
+/** 创建模块 */
+export type ToWrappedModule<T extends Record<string, RawValue>> = VmModule<{
+    [key in keyof T]: ToWrappedValue<T[key]>;
+}>;
+
+/** 创建模块 */
+export function createModule<const T extends Record<string, RawValue>>(name: string, lib: T): ToWrappedModule<T> {
+    const mod = create(null) as Record<string, VmImmutable>;
+    for (const [key, value] of entries(lib)) {
+        mod[key] = wrapEntry(key, value);
+    }
+    return new VmModule(name, mod) as ToWrappedModule<T>;
+}
+
+export const lib = global;

package/src/vm/lib/global/bit.ts

@@ -0,0 +1,93 @@
+import { $ToNumber } from '../../operations.js';
+import { VmLib } from '../_helpers.js';
+
+export const b_and = VmLib(
+    (x, y) => {
+        return $ToNumber(x) & $ToNumber(y);
+    },
+    {
+        summary: '返回两个数的按位与',
+        params: { x: '第一个操作数', y: '第二个操作数' },
+        paramsType: { x: 'number', y: 'number' },
+        returnsType: 'number',
+        examples: ['b_and(6, 3) // 2'],
+    },
+);
+
+export const b_or = VmLib(
+    (x, y) => {
+        return $ToNumber(x) | $ToNumber(y);
+    },
+    {
+        summary: '返回两个数的按位或',
+        params: { x: '第一个操作数', y: '第二个操作数' },
+        paramsType: { x: 'number', y: 'number' },
+        returnsType: 'number',
+        examples: ['b_or(5, 2) // 7'],
+    },
+);
+
+export const b_not = VmLib(
+    (x) => {
+        return ~$ToNumber(x);
+    },
+    {
+        summary: '返回一个数的按位取反',
+        params: { x: '操作数' },
+        paramsType: { x: 'number' },
+        returnsType: 'number',
+        examples: ['b_not(0) // -1'],
+    },
+);
+
+export const b_xor = VmLib(
+    (x, y) => {
+        return $ToNumber(x) ^ $ToNumber(y);
+    },
+    {
+        summary: '返回两个数的按位异或',
+        params: { x: '第一个操作数', y: '第二个操作数' },
+        paramsType: { x: 'number', y: 'number' },
+        returnsType: 'number',
+        examples: ['b_xor(5, 3) // 6'],
+    },
+);
+
+export const shl = VmLib(
+    (x, y) => {
+        return $ToNumber(x) << $ToNumber(y);
+    },
+    {
+        summary: '返回第一个操作数左移指定的位数',
+        params: { x: '第一个操作数', y: '位数' },
+        paramsType: { x: 'number', y: 'number' },
+        returnsType: 'number',
+        examples: ['shl(3, 2) // 12'],
+    },
+);
+
+export const sar = VmLib(
+    (x, y) => {
+        return $ToNumber(x) >> $ToNumber(y);
+    },
+    {
+        summary: '返回第一个操作数右移指定的位数',
+        params: { x: '第一个操作数', y: '位数' },
+        paramsType: { x: 'number', y: 'number' },
+        returnsType: 'number',
+        examples: ['sar(-8, 1) // -4'],
+    },
+);
+
+export const shr = VmLib(
+    (x, y) => {
+        return $ToNumber(x) >>> $ToNumber(y);
+    },
+    {
+        summary: '返回第一个操作数无符号右移指定的位数',
+        params: { x: '第一个操作数', y: '位数' },
+        paramsType: { x: 'number', y: 'number' },
+        returnsType: 'number',
+        examples: ['shr(8, 1) // 4'],
+    },
+);

package/src/vm/lib/global/debug.ts

@@ -0,0 +1,36 @@
+import { VmError } from '../../error.js';
+import { $ToString } from '../../operations.js';
+import type { VmAny } from '../../types/index.js';
+import { VmLib } from '../_helpers.js';
+
+export const debug_print = VmLib(
+    (...args) => {
+        // eslint-disable-next-line no-console
+        console.log('\u001B[46;30m MiraScript \u001B[0m', ...args);
+    },
+    {
+        summary: '打印调试信息到控制台',
+        params: { '..args': '要打印的调试信息，可以是任意类型' },
+        paramsType: { '..args': 'any[]' },
+        returnsType: 'nil',
+        examples: ['debug_print("value:", 42);'],
+    },
+);
+
+export const panic = VmLib(
+    (message: VmAny) => {
+        // eslint-disable-next-line no-console
+        if (message === undefined) console.error('\u001B[41;37m MiraScript \u001B[0m');
+        // eslint-disable-next-line no-console
+        else console.error('\u001B[41;37m MiraScript \u001B[0m', message);
+        const error = message == null ? 'panic' : 'panic: ' + $ToString(message);
+        throw new VmError(error, undefined);
+    },
+    {
+        summary: '产生错误，并打印错误信息到控制台',
+        params: { message: '要打印的错误信息' },
+        paramsType: { message: 'string' },
+        returnsType: 'never',
+        examples: ['panic("boom");'],
+    },
+);

package/src/vm/lib/global/index.ts

@@ -0,0 +1,9 @@
+export * from './math.js';
+export * from './bit.js';
+export * from './sequence/index.js';
+export * from './debug.js';
+export * from './json.js';
+export * from './to-primitive.js';
+export * from './string.js';
+export * from './time.js';
+export * from './mod/index.js';

package/src/vm/lib/global/json.ts

@@ -0,0 +1,45 @@
+import { isVmExtern, isVmModule } from '../../types/index.js';
+import { required, rethrowError, VmLib } from '../_helpers.js';
+const { parse, stringify } = JSON;
+
+export const to_json = VmLib(
+    (data) => {
+        required('data', data, null);
+        if (isVmExtern(data) || isVmModule(data)) {
+            try {
+                return stringify(data.value) ?? null;
+            } catch (ex) {
+                rethrowError('Failed to convert extern to JSON', ex, '{}');
+            }
+        }
+        if (typeof data == 'function') return null;
+        return stringify(data);
+    },
+    {
+        summary: '将数据转换为 JSON 字符串',
+        params: { data: '要转换为 JSON 的数据' },
+        paramsType: { data: 'any' },
+        returnsType: 'string',
+        examples: ['to_json([1, 2, 3]) // "[1,2,3]"'],
+    },
+);
+
+export const from_json = VmLib(
+    (json, fallback) => {
+        required('json', json, null);
+        if (typeof json != 'string') return json;
+        try {
+            return parse(json);
+        } catch (ex) {
+            if (fallback != null) return fallback;
+            rethrowError('Invalid JSON', ex, null);
+        }
+    },
+    {
+        summary: '将 JSON 字符串转换为数据',
+        params: { json: '要转换的 JSON 字符串', fallback: '如果转换失败，返回的默认值' },
+        paramsType: { json: 'string', fallback: 'any' },
+        returnsType: 'any',
+        examples: [`from_json('{"a":1}') // (a: 1)`],
+    },
+);

package/src/vm/lib/global/math-additional.ts

@@ -0,0 +1,71 @@
+/* eslint-disable no-loss-of-precision */
+import { isInteger, isNaN } from '../../../helpers/utils.js';
+import { $ToNumber } from '../../operations.js';
+import { required, VmLib } from '../_helpers.js';
+const { sqrt, pow, exp } = Math;
+
+const GAMMA_G = 4.742_187_5;
+
+const GAMMA_P = [
+    0.999_999_999_999_997_091_82, 57.156_235_665_862_923_517, -59.597_960_355_475_491_248, 14.136_097_974_741_747_174,
+    -0.491_913_816_097_620_199_78, 0.339_946_499_848_118_886_99e-4, 0.465_236_289_270_485_756_65e-4,
+    -0.983_744_753_048_795_646_77e-4, 0.158_088_703_224_912_488_84e-3, -0.210_264_441_724_104_883_19e-3,
+    0.217_439_618_115_212_643_2e-3, -0.164_318_106_536_763_890_22e-3, 0.844_182_239_838_527_432_93e-4,
+    -0.261_908_384_015_814_086_7e-4, 0.368_991_826_595_316_227_04e-5,
+];
+
+const SQRT_2_PI = sqrt(2 * Math.PI);
+
+export const factorial = VmLib(
+    (x): number => {
+        required('x', x, Number.NaN);
+        let n = $ToNumber(x);
+        if (isNaN(n) || n < 0) return Number.NaN;
+        if (n >= 171) return Number.POSITIVE_INFINITY; // will overflow
+
+        if (isInteger(n)) {
+            if (n === 0 || n === 1) return 1;
+
+            let r = 1;
+            for (let i = 2; i <= n; i++) {
+                r *= i;
+            }
+            return r;
+        }
+
+        if (n > 85) {
+            // Extended Stirling Approx
+            n = n + 1;
+            const twoN = n * n;
+            const threeN = twoN * n;
+            const fourN = threeN * n;
+            const fiveN = fourN * n;
+            return (
+                sqrt((2 * Math.PI) / n) *
+                pow(n / Math.E, n) *
+                (1 +
+                    1 / (12 * n) +
+                    1 / (288 * twoN) -
+                    139 / (51840 * threeN) -
+                    571 / (2_488_320 * fourN) +
+                    163_879 / (209_018_880 * fiveN) +
+                    5_246_819 / (75_246_796_800 * fiveN * n))
+            );
+        }
+
+        let p = GAMMA_P[0]!;
+        for (let i = 1; i < GAMMA_P.length; ++i) {
+            p += GAMMA_P[i]! / (n + i);
+        }
+
+        const t = n + GAMMA_G + 0.5;
+        return SQRT_2_PI * pow(t, n + 0.5) * exp(-t) * p;
+    },
+    {
+        summary: '返回一个数的阶乘',
+        params: { x: '要计算阶乘的数值' },
+        paramsType: { x: 'number' },
+        returnsType: 'number',
+        examples: ['factorial(5) // 120'],
+    },
+);

package/src/vm/lib/global/math-arr.ts

@@ -0,0 +1,62 @@
+import type { VmAny } from '../../types/index.js';
+import { getNumbers, VmLib } from '../_helpers.js';
+
+/** 生成函数 */
+function build(f: (...values: readonly number[]) => number): (...values: readonly VmAny[]) => number {
+    return (...values) => {
+        const numbers = getNumbers(values);
+        return f(...numbers);
+    };
+}
+
+export const max = VmLib(build(Math.max), {
+    summary: '返回一组数中的最大值',
+    params: { '..values': '要比较的数值' },
+    paramsType: { '..values': 'number[]' },
+    returnsType: 'number',
+    examples: ['max(3, 7, 2) // 7'],
+});
+
+export const min = VmLib(build(Math.min), {
+    summary: '返回一组数中的最小值',
+    params: { '..values': '要比较的数值' },
+    paramsType: { '..values': 'number[]' },
+    returnsType: 'number',
+    examples: ['min(3, 7, 2) // 2'],
+});
+
+export const hypot = VmLib(build(Math.hypot), {
+    summary: '返回所有参数平方和的平方根',
+    params: { '..values': '要计算的数值' },
+    paramsType: { '..values': 'number[]' },
+    returnsType: 'number',
+    examples: ['hypot(3, 4) // 5'],
+});
+
+export const sum = VmLib(
+    (...values: readonly VmAny[]) => {
+        const numbers = getNumbers(values);
+        return numbers.reduce((a, b) => a + b, 0);
+    },
+    {
+        summary: '返回一组数的总和',
+        params: { '..values': '要计算的数值' },
+        paramsType: { '..values': 'number[]' },
+        returnsType: 'number',
+        examples: ['sum(1, 2, 3, 4) // 10'],
+    },
+);
+
+export const product = VmLib(
+    (...values: readonly VmAny[]) => {
+        const numbers = getNumbers(values);
+        return numbers.reduce((a, b) => a * b, 1);
+    },
+    {
+        summary: '返回一组数的乘积',
+        params: { '..values': '要计算的数值' },
+        paramsType: { '..values': 'number[]' },
+        returnsType: 'number',
+        examples: ['product(2, 3, 4) // 24'],
+    },
+);

package/src/vm/lib/global/math-const.ts

@@ -0,0 +1,2 @@
+const { PI, E } = Math;
+export { PI as '@pi', E as '@e' };