mlogjs 0.2.2 → 0.3.0-beta.0

package/dist/types/types.d.ts

@@ -1,39 +1,122 @@
-export * as es from "estree";
+export * as es from "@babel/types";
 import { Compiler } from "./Compiler";
 import { AddressResolver } from "./instructions";
 import { MacroFunction } from "./macros";
 import { LeftRightOperator, UnaryOperator, UpdateOperator } from "./operators";
-import { StoreValue } from "./values";
 export interface IInstruction {
     hidden: boolean;
     resolve(i: number): void;
 }
 export declare type THandler<T extends IValue | null = IValue> = (compiler: Compiler, scope: IScope, node: any, arg: any) => TValueInstructions<T>;
+/**
+ * The scope manages the source code generated variables and their owners,
+ * as well as break and continue statements and they also work as function
+ * bodies.
+ */
 export interface IScope {
+    /** Every scope except the top level one has a parent */
     parent: IScope | null;
-    data: {};
+    /** The registry of variables contained by this scope */
+    data: Record<string, IValueOwner | null>;
     name: string;
+    /**
+     * Additional instructions required by this scope, such as
+     * the instructions that make the body of a function
+     */
     inst: IInstruction[];
+    /** Where to jump to on a break statement */
     break: AddressResolver;
+    /** Where to jump to on a continue statement */
     continue: AddressResolver;
+    /** The function linked to `this`, is `null` when the scope is not inside a function. */
     function: IFunctionValue;
+    /** Counts the number of temp variables generated during compilaton */
     ntemp: number;
+    /**
+     * Creates a new scope that has `this` as it's parent.
+     */
     createScope(): IScope;
+    /**
+     * Creates a new scope to be used by a function value, the scope has the following properties:
+     * - uses `name` as it's primary name, it changes how variable names are formatted.
+     * - it has `this` as it's parent
+     * - independent variable registry
+     * @param name The name of the scope
+     * @param stacked
+     */
     createFunction(name: string, stacked?: boolean): IScope;
-    has(name: string): boolean;
-    get(name: string): IValue;
+    /** Checks if there is an owner registered with the specified identifier */
+    has(identifier: string): boolean;
+    /** Gets a value by their owner's identifier */
+    get(identifier: string): IOwnedValue;
+    /**
+     * Registers `value` with an owner that uses `name` as both it's name and identifier,
+     * throws an error if there already is an owner with the same identitifer.
+     * @param name
+     * @param value
+     */
     set<T extends IValue>(name: string, value: T): T;
+    /**
+     * Registers `owner` and it's inner value, throws an error
+     * if there already is an owner with the same identifier.
+     */
+    set<T extends IValue>(owner: IValueOwner<T>): T;
+    /**
+     * Registers `value` with an owner that uses `name` as both it's name and identifier,
+     * overriding any preexisting variables with the same identifier.
+     * @param name
+     * @param value
+     */
     hardSet<T extends IValue>(name: string, value: T): T;
-    make(name: string, storeName: string): StoreValue;
+    /**
+     * Registers `owner` and it's inner value, overriding
+     * any preexisting variables with the same identifier.
+     * @param owner
+     */
+    hardSet<T extends IValue>(owner: IValueOwner<T>): T;
+    /**
+     * Creates an owned store and registers it to this scope.
+     * @param identifier The name of the variable that will hold the store
+     * @param name The mlog name that the owner will have
+     */
+    make(identifier: string, name: string): IValue;
+    /**
+     * Creates a shallow copy of this scope.
+     *
+     * Be aware that since the copy is shallow, changes on object fields (except `data`)
+     * reflect on the original scope. Note that changes to the children of data also follow this rule.
+     */
     copy(): IScope;
+    /** Creates a temporary mlog variable name */
+    makeTempName(): string;
 }
-export interface IValue {
+/**
+ * Owners track how variables will behave when it comes to their usage.
+ *
+ * As an example, Stores use their owners to determine what to do during
+ * assignments, like making a compile time alias, moving the values or generating
+ * a `set` instruction.
+ */
+export interface IValueOwner<T extends IValue = IValue> {
     scope: IScope;
     constant: boolean;
-    macro: boolean;
-    eval(scope: IScope): TValueInstructions;
-    call(scope: IScope, args: IValue[]): TValueInstructions<IValue | null>;
-    get(scope: IScope, name: IValue): TValueInstructions;
+    value: T;
+    /** The name of the variable on the source code that generated this value owner */
+    identifier?: string;
+    /** The name this owner has in it's mlog representation */
+    name: string;
+    /** Whether this owner is temporary or persistent */
+    persistent: boolean;
+    /** Set of values owned by this, can be used to get the owned value count  */
+    owned: Set<T>;
+    /** Adds `target` to the {@link owned set of owned values} and sets its owner to `this` */
+    own(target: T): void;
+    /** Replaces the currently held value by `target` */
+    replace(target: T): void;
+    /** Moves all values owned by `this` into `owner` */
+    moveInto(owner: IValueOwner<T>): void;
+}
+export interface IValueOperators {
     "!"(scope: IScope): TValueInstructions;
     "u+"(scope: IScope): TValueInstructions;
     "u-"(scope: IScope): TValueInstructions;
@@ -84,17 +167,43 @@ export interface IValue {
     "|="(scope: IScope, value: IValue): TValueInstructions;
     "="(scope: IScope, value: IValue): TValueInstructions;
 }
+export interface IValue extends IValueOperators {
+    owner: IValueOwner | null;
+    scope: IScope;
+    constant: boolean;
+    macro: boolean;
+    /**
+     * Evaluates `this`, returning it's representation in a more basic
+     * value like `StoreValue` with the instructions required to compute that value
+     */
+    eval(scope: IScope): TValueInstructions;
+    /**
+     * Does the same thing as {@link IValue.eval eval}, but ensures that the resulting value has an owner.
+     *
+     * This behaviour is required when dealing with temporary values inside expressions like comparations.
+     */
+    consume(scope: IScope): TValueInstructions;
+    call(scope: IScope, args: IValue[]): TValueInstructions<IValue | null>;
+    get(scope: IScope, name: IValue): TValueInstructions;
+    ensureOwned(): asserts this is IOwnedValue;
+}
+/** Helper type that is used in some typescript assertions */
+export interface IOwnedValue extends IValue {
+    owner: Exclude<IValue["owner"], null>;
+}
 export declare type TLiteral = string | number;
 export interface IBindableValue extends IValue {
     data: TLiteral;
 }
 export interface IFunctionValue extends IValue {
-    return(scope: IScope, argument: IValue): TValueInstructions<IValue | null>;
+    return(scope: IScope, argument: IValue | null): TValueInstructions<IValue | null>;
 }
+/** Contains a value and the instructions required to compute it */
 export declare type TValueInstructions<Content extends IValue | null = IValue> = [
     Content,
     IInstruction[]
 ];
+/** Map of overridable operators in object macros */
 export declare type TOperatorMacroMap = {
     [K in UnaryOperator | UpdateOperator | LeftRightOperator as `$${K}`]?: MacroFunction;
 };

package/dist/types/utils.d.ts

@@ -1,3 +1,24 @@
 import { es } from "./types";
-export declare function nodeName(node: es.Node): string;
+/**
+ * The prefix for internal variables inside the compiler output
+ */
+export declare const internalPrefix = "&";
+export declare const discardedName: string;
+/**
+ * Returns a string that has the format: [line]:[column].
+ *
+ * If `name` is provided, and it is a string, the resulting string will
+ * have the format: [name]:[line]:[column].
+ */
+export declare function nodeName(node: es.Node, name?: false | string): string;
+/**
+ * Converts a camel case string into a dash case one.
+ *
+ * As an example `camelCase` becomes `camel-case`
+ * @example
+ * ```
+ * camelToDashCase("camelCase") // returns "camel-case"
+ * ```
+ */
 export declare function camelToDashCase(name: string): string;
+export declare const itemNames: string[];

package/dist/types/values/BaseValue.d.ts

@@ -1,5 +1,7 @@
-import { IScope, IValue, TValueInstructions } from "../types";
+import { IOwnedValue, IScope, IValue, TValueInstructions } from "../types";
 import { VoidValue } from ".";
 export declare class BaseValue extends VoidValue implements IValue {
     "u-"(scope: IScope): TValueInstructions;
+    "u+"(scope: IScope): TValueInstructions;
+    ensureOwned(): asserts this is IOwnedValue;
 }

package/dist/types/values/DestructuringValue.d.ts

@@ -0,0 +1,17 @@
+import { IScope, IValue, TValueInstructions } from "../types";
+import { VoidValue } from "./VoidValue";
+/**
+ * Specific case class, required on the ArrayPattern and ObjectPattern handlers
+ * in order to keep the separation of concerns and make the code more modular.
+ *
+ * When it is assign a value, it will get it's own properties and recursively assign
+ * each of them to their counterparts on the right hand value.
+ */
+export declare class DestructuringValue extends VoidValue {
+    members: Map<IValue, IValue>;
+    macro: boolean;
+    constructor(scope: IScope, members: Map<IValue, IValue>);
+    "="(scope: IScope, right: IValue): TValueInstructions;
+    eval(_scope: IScope): TValueInstructions<IValue>;
+    consume(_scope: IScope): TValueInstructions<IValue>;
+}

package/dist/types/values/FunctionValue.d.ts

@@ -2,11 +2,17 @@ import { Compiler } from "../Compiler";
 import { es, IFunctionValue, IScope, IValue, TValueInstructions } from "../types";
 import { StoreValue } from "./StoreValue";
 import { VoidValue } from "./VoidValue";
+export declare type TFunctionValueInitParams = (childScope: IScope) => {
+    paramStores: StoreValue[];
+    paramNames: string[];
+};
 export declare class FunctionValue extends VoidValue implements IFunctionValue {
     constant: boolean;
     macro: boolean;
-    private paramStores;
-    private paramNames;
+    private node;
+    private childScope;
+    private params;
+    private paramOwners;
     private inst;
     private addr;
     private temp;
@@ -14,21 +20,28 @@ export declare class FunctionValue extends VoidValue implements IFunctionValue {
     private inline;
     private tryingInline;
     private body;
-    private name;
     private c;
     private callSize;
     private inlineTemp;
     private inlineEnd;
     private bundled;
-    private createValues;
+    private initialized;
+    constructor({ scope, params, body, c, node, }: {
+        scope: IScope;
+        body: es.BlockStatement;
+        c: Compiler;
+        node: es.Function;
+        params: es.Identifier[];
+    });
     typeof(scope: IScope): TValueInstructions;
-    private createInst;
-    constructor(scope: IScope, name: string, paramNames: string[], paramStores: StoreValue[], body: es.BlockStatement, c: Compiler);
+    private initScope;
+    private ensureInit;
     private normalReturn;
     private normalCall;
     private inlineReturn;
     private inlineCall;
     call(scope: IScope, args: IValue[]): TValueInstructions;
-    return(scope: IScope, arg: IValue): TValueInstructions<IValue | null>;
-    eval(scope: IScope): TValueInstructions;
+    return(scope: IScope, arg: IValue | null): TValueInstructions<IValue | null>;
+    eval(_scope: IScope): TValueInstructions;
+    consume(_scope: IScope): TValueInstructions;
 }

package/dist/types/values/LiteralValue.d.ts

@@ -4,7 +4,8 @@ export declare class LiteralValue extends BaseValue implements IBindableValue {
     data: TLiteral;
     constant: boolean;
     constructor(scope: IScope, data: TLiteral);
-    eval(scope: IScope): TValueInstructions;
+    eval(_scope: IScope): TValueInstructions;
+    consume(_scope: IScope): TValueInstructions;
     toString(): string;
     get(scope: IScope, name: IValue): TValueInstructions;
     get num(): number;

package/dist/types/values/ObjectValue.d.ts

@@ -1,19 +1,23 @@
 import { MacroFunction } from "../macros";
-import { IScope, IValue, TOperatorMacroMap, TValueInstructions } from "../types";
+import { IOwnedValue, IScope, IValue, TOperatorMacroMap, TValueInstructions } from "../types";
 import { LiteralValue } from "./LiteralValue";
 import { VoidValue } from "./VoidValue";
 export interface IObjectValueData extends TOperatorMacroMap {
     [k: string]: IValue | undefined;
     $get?: MacroFunction<IValue>;
     $eval?: MacroFunction<IValue>;
+    $consume?: MacroFunction<IValue>;
 }
 export declare class ObjectValue extends VoidValue {
     constant: boolean;
     macro: boolean;
     data: IObjectValueData;
     constructor(scope: IScope, data?: IObjectValueData);
+    static fromArray(scope: IScope, items: IObjectValueData[keyof IObjectValueData][]): ObjectValue;
     typeof(scope: IScope): TValueInstructions;
     get(scope: IScope, key: LiteralValue): TValueInstructions;
     eval(scope: IScope): TValueInstructions;
+    consume(scope: IScope): TValueInstructions;
     call(scope: IScope, args: IValue[]): TValueInstructions<IValue | null>;
+    ensureOwned(): asserts this is IOwnedValue;
 }

package/dist/types/values/SenseableValue.d.ts

@@ -0,0 +1,23 @@
+import { IScope, IValue, TValueInstructions } from "../types";
+import { StoreValue } from "./StoreValue";
+/**
+ * Senseable values are "objects" in the mlog runtime that
+ * have special properties that can be accessed
+ * via the `sense` instruction.
+ *
+ * This class extends `StoreValue` to allow dynamic behavior
+ * that is not possible with object macros.
+ *
+ * Note that these values are constant by default, so make sure
+ * to set that field to `false` if you want them to be assignable. Example:
+ * ```
+ * const value = new SenseableValue(scope)
+ * value.constant = false
+ * ```
+ */
+export declare class SenseableValue extends StoreValue {
+    constant: boolean;
+    constructor(scope: IScope);
+    get(scope: IScope, prop: IValue): TValueInstructions<IValue>;
+    typeof(scope: IScope): TValueInstructions<IValue>;
+}

package/dist/types/values/StackValue.d.ts

@@ -0,0 +1,16 @@
+import { BaseValue } from ".";
+import { IScope, IValue, TValueInstructions } from "../types";
+/**
+ * `StackValue` represents values unknown at compile time inside a stack memory,
+ * mostly used with mutable variables and temporary values
+ */
+export declare class StackValue extends BaseValue implements IValue {
+    constant: boolean;
+    offset: number;
+    constructor(scope: IScope);
+    typeof(scope: IScope): TValueInstructions;
+    "="(scope: IScope, value: IValue): TValueInstructions;
+    eval(scope: IScope): TValueInstructions;
+    consume(_scope: IScope): TValueInstructions;
+    toString(): string;
+}

package/dist/types/values/StoreValue.d.ts

@@ -1,11 +1,15 @@
 import { BaseValue } from ".";
 import { IScope, IValue, TValueInstructions } from "../types";
+/**
+ * `StoreValue` represents values unknown at compile time,
+ * mostly used with mutable variables and temporary values
+ */
 export declare class StoreValue extends BaseValue implements IValue {
-    name: string;
     constant: boolean;
-    constructor(scope: IScope, name: string);
+    constructor(scope: IScope);
     typeof(scope: IScope): TValueInstructions;
     "="(scope: IScope, value: IValue): TValueInstructions;
-    eval(scope: IScope): TValueInstructions;
+    eval(_scope: IScope): TValueInstructions;
+    consume(_scope: IScope): TValueInstructions;
     toString(): string;
 }

package/dist/types/values/TempValue.d.ts

@@ -1,12 +1,19 @@
 import { IInstruction, IScope, IValue, TValueInstructions } from "../types";
 import { StoreValue } from "./";
-export declare class TempValue extends StoreValue {
+export interface TempValueOptions {
+    scope: IScope;
+    name?: string;
+    renameable?: boolean;
+}
+export declare class TempValue extends StoreValue implements IValue {
     proxied: IValue;
     canProxy: boolean;
     setInst: IInstruction;
-    constructor(scope: IScope, name?: string);
+    renameable: boolean;
+    constructor({ scope, name, renameable }: TempValueOptions);
     eval(scope: IScope): TValueInstructions;
     "="(scope: IScope, value: IValue): TValueInstructions;
     proxy(value: IValue): TValueInstructions;
     noProxy(): void;
+    rename(name: string): void;
 }

package/dist/types/values/ValueOwner.d.ts

@@ -0,0 +1,27 @@
+import { IScope, IValue, IValueOwner } from "../types";
+export interface IValueOwnerParams<T extends IValue> {
+    scope: IScope;
+    constant?: boolean;
+    value: T;
+    /** The identifier of the variable that `this` represents */
+    identifier?: string;
+    /** The name that the variable will have during transpilation to mlog */
+    name?: string;
+}
+export declare class ValueOwner<T extends IValue = IValue> implements IValueOwner<T> {
+    scope: IScope;
+    constant: boolean;
+    value: T;
+    owned: Set<T>;
+    identifier?: string;
+    name: string;
+    persistent: boolean;
+    /**
+     * Creates a new `ValueOwner`, if `value` is already owned,
+     * `this` will be aliased to `value`, else `this` will own `value`
+     */
+    constructor({ scope, constant, value, identifier, name, }: IValueOwnerParams<T>);
+    own(target: T): void;
+    replace(target: T): void;
+    moveInto(owner: IValueOwner<T>): void;
+}

package/dist/types/values/VoidValue.d.ts

@@ -1,13 +1,16 @@
-import { IScope, IValue, TValueInstructions } from "../types";
+import { IScope, IValue, IValueOperators, IValueOwner, TValueInstructions } from "../types";
 export declare class VoidValue implements IValue {
+    owner: IValueOwner | null;
     scope: IScope;
     constant: boolean;
     macro: boolean;
     constructor(scope: IScope);
-    eval(scope: IScope): TValueInstructions;
-    call(scope: IScope, args: IValue[]): TValueInstructions<IValue | null>;
-    get(scope: IScope, name: IValue): TValueInstructions;
+    eval(_scope: IScope): TValueInstructions;
+    consume(_scope: IScope): TValueInstructions<IValue>;
+    call(_scope: IScope, _args: IValue[]): TValueInstructions<IValue | null>;
+    get(_scope: IScope, _name: IValue): TValueInstructions;
+    ensureOwned(): void;
     toString(): string;
 }
-export interface VoidValue extends IValue {
+export interface VoidValue extends IValueOperators {
 }

package/dist/types/values/index.d.ts

@@ -2,5 +2,6 @@ export * from "./VoidValue";
 export * from "./BaseValue";
 export * from "./LiteralValue";
 export * from "./StoreValue";
-export * from "./TempValue";
 export * from "./ObjectValue";
+export * from "./SenseableValue";
+export * from "./DestructuringValue";