@robinpath/robinpath 0.30.0

package/dist/parsers/SubexpressionParser.d.ts

@@ -0,0 +1,33 @@
+import { TokenStream } from '../classes/TokenStream';
+import { Token } from '../classes/Lexer';
+import { SubexpressionExpression, CodePosition, Statement } from '../types/Ast.type';
+export interface SubexpressionParserContext {
+    /**
+     * Parse a statement from the stream
+     */
+    parseStatement: (stream: TokenStream) => Statement | null;
+    /**
+     * Create code position from tokens
+     */
+    createCodePosition: (startToken: Token, endToken: Token) => CodePosition;
+}
+export declare class SubexpressionParser {
+    /**
+     * Parse a subexpression from TokenStream
+     * Expects stream to be positioned at the '$(' token
+     * Syntax: $( ... )
+     *
+     * @param stream - TokenStream positioned at the '$(' token
+     * @param context - Context with helper methods
+     * @returns Parsed SubexpressionExpression
+     */
+    static parse(stream: TokenStream, context: SubexpressionParserContext): SubexpressionExpression;
+    /**
+     * Check if the current token is the start of a subexpression
+     * Subexpressions must start with SUBEXPRESSION_OPEN ($()
+     *
+     * @param stream - TokenStream to check
+     * @returns true if current token is SUBEXPRESSION_OPEN
+     */
+    static isSubexpression(stream: TokenStream): boolean;
+}

package/dist/parsers/TogetherBlockParser.d.ts

@@ -0,0 +1,18 @@
+import { TokenStream } from '../classes/TokenStream';
+import { Token } from '../classes/Lexer';
+import { TogetherBlock, Statement, CodePosition, DecoratorCall } from '../types/Ast.type';
+export interface TogetherBlockParserContext {
+    parseStatement: (stream: TokenStream) => Statement | null;
+    parseComment: (stream: TokenStream) => Statement | null;
+    createCodePosition: (start: Token, end: Token) => CodePosition;
+}
+/**
+ * Parse a 'together' block from TokenStream
+ * Expects stream to be positioned at the 'together' keyword
+ *
+ * @param stream - TokenStream positioned at the 'together' keyword
+ * @param context - Context with helper methods
+ * @param decorators - Optional decorators to attach to this together block
+ * @returns Parsed TogetherBlock
+ */
+export declare function parseTogether(stream: TokenStream, context: TogetherBlockParserContext, decorators?: DecoratorCall[]): TogetherBlock;

package/dist/parsers/WithScopeParser.d.ts

@@ -0,0 +1,24 @@
+import { TokenStream } from '../classes/TokenStream';
+import { ScopeBlock, Statement, DecoratorCall } from '../types/Ast.type';
+export declare class WithScopeParser {
+    /**
+     * Maximum number of iterations allowed before detecting an infinite loop
+     */
+    static readonly MAX_STUCK_ITERATIONS = 100;
+    /**
+     * Debug mode flag - set to true to enable logging
+     * Can be controlled via VITE_DEBUG environment variable or set programmatically
+     */
+    static debug: boolean;
+    /**
+     * Parse a 'with' scope block (callback block)
+     * Expects stream to be positioned at the 'with' keyword
+     *
+     * @param stream - TokenStream positioned at the 'with' keyword
+     * @param parseStatement - Callback to parse a statement from the stream
+     * @param parseComment - Callback to parse a comment from the stream
+     * @param decorators - Optional decorators to attach to this with block
+     * @returns Parsed ScopeBlock (with type 'do' for AST compatibility)
+     */
+    static parse(stream: TokenStream, parseStatement: (stream: TokenStream) => Statement | null, parseComment: (stream: TokenStream) => Statement | null, decorators?: DecoratorCall[]): ScopeBlock;
+}

package/dist/types/Ast.type.d.ts

@@ -0,0 +1,455 @@
+import { Value, AttributePathSegment } from '../utils/types';
+/**
+ * Represents the position of code in the source file
+ */
+export interface CodePosition {
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+}
+/**
+ * Represents a comment with its position in the source code
+ */
+export interface CommentWithPosition {
+    text: string;
+    codePos: CodePosition;
+    inline?: boolean;
+}
+/**
+ * Represents a standalone comment statement in the AST
+ */
+export interface CommentStatement {
+    type: 'comment';
+    nodeKey?: string;
+    comments: CommentWithPosition[];
+    lineNumber: number;
+    /**
+     * Number of blank lines after this statement (for preserving formatting).
+     *
+     * **Semantics:**
+     * - `undefined` or `0`: No trailing blank lines (statement immediately followed by next)
+     * - `1`: One blank line after statement (two consecutive newlines: `\n\n`)
+     * - `2`: Two blank lines after statement (three consecutive newlines: `\n\n\n`)
+     * - ... and so on
+     *
+     * **For the LAST statement in a file:**
+     * - `undefined` or `0`: File does NOT end with a newline
+     * - `1`: File ends with exactly one newline (no blank line at EOF)
+     * - `2`: File ends with one blank line (two newlines at EOF)
+     * - ... and so on
+     *
+     * **Note:** The statement's own ending newline is NOT counted in trailingBlankLines.
+     * Each statement implicitly ends with `\n`. This field only tracks EXTRA blank lines.
+     */
+    trailingBlankLines?: number;
+}
+/**
+ * Represents a variable reference expression
+ */
+export interface VarExpression {
+    type: 'var';
+    name: string;
+    path?: AttributePathSegment[];
+    codePos?: CodePosition;
+}
+/**
+ * Represents the last value expression ($)
+ */
+export interface LastValueExpression {
+    type: 'lastValue';
+    codePos?: CodePosition;
+}
+/**
+ * Represents a literal value expression
+ */
+export interface LiteralExpression {
+    type: 'literal';
+    value: Value;
+    codePos?: CodePosition;
+}
+/**
+ * Represents a number literal expression
+ */
+export interface NumberExpression {
+    type: 'number';
+    value: number;
+    codePos?: CodePosition;
+}
+/**
+ * Represents a string literal expression
+ */
+export interface StringExpression {
+    type: 'string';
+    value: string;
+    codePos?: CodePosition;
+}
+/**
+ * Represents a property in an object literal
+ */
+export interface ObjectProperty {
+    key: string | Expression;
+    value: Expression;
+}
+/**
+ * Represents an object literal expression { ... }
+ */
+export interface ObjectLiteralExpression {
+    type: 'objectLiteral';
+    properties: ObjectProperty[];
+    codePos?: CodePosition;
+}
+/**
+ * Represents an array literal expression [ ... ]
+ */
+export interface ArrayLiteralExpression {
+    type: 'arrayLiteral';
+    elements: Expression[];
+    codePos?: CodePosition;
+}
+/**
+ * Represents $( ... ) – a subexpression that contains statements.
+ * The result value is the lastValue after executing the body.
+ */
+export interface SubexpressionExpression {
+    type: 'subexpression';
+    body: Statement[];
+    codePos: CodePosition;
+}
+/**
+ * Binary operators for expressions
+ */
+export type BinaryOperator = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'and' | 'or' | '+' | '-' | '*' | '/' | '%';
+/**
+ * Represents a binary operation expression
+ */
+export interface BinaryExpression {
+    type: 'binary';
+    operator: BinaryOperator;
+    left: Expression;
+    right: Expression;
+    codePos?: CodePosition;
+}
+/**
+ * Unary operators for expressions
+ */
+export type UnaryOperator = 'not' | '-' | '+';
+/**
+ * Represents a unary operation expression
+ */
+export interface UnaryExpression {
+    type: 'unary';
+    operator: UnaryOperator;
+    argument: Expression;
+    codePos?: CodePosition;
+}
+/**
+ * Represents a function/command call within an expression
+ */
+export interface CallExpression {
+    type: 'call';
+    callee: string;
+    args: Expression[];
+    codePos?: CodePosition;
+}
+/**
+ * Union type representing all possible expression types
+ */
+export type Expression = VarExpression | LastValueExpression | LiteralExpression | NumberExpression | StringExpression | ObjectLiteralExpression | ArrayLiteralExpression | SubexpressionExpression | BinaryExpression | UnaryExpression | CallExpression;
+/**
+ * Represents named arguments (key=value pairs)
+ */
+export interface NamedArgsExpression {
+    type: 'namedArgs';
+    args: Record<string, Expression>;
+}
+/**
+ * Represents an argument passed to a command or function
+ *
+ * @deprecated The old Arg types with code strings are being phased out.
+ * Use Expression nodes instead. For backward compatibility, we keep the old types
+ * but they should be replaced with Expression nodes.
+ */
+export type Arg = Expression | NamedArgsExpression | {
+    type: 'subexpr';
+    code: string;
+} | {
+    type: 'object';
+    code: string;
+} | {
+    type: 'array';
+    code: string;
+};
+/**
+ * Represents a decorator call (e.g., @desc "description")
+ */
+export interface DecoratorCall {
+    name: string;
+    args: Arg[];
+    codePos: CodePosition;
+}
+/**
+ * Represents a command/function call
+ */
+export interface CommandCall {
+    type: 'command';
+    nodeKey?: string;
+    name: string;
+    args: Arg[];
+    syntaxType?: 'space' | 'parentheses' | 'named-parentheses' | 'multiline-parentheses';
+    isTaggedTemplate?: boolean;
+    decorators?: DecoratorCall[];
+    into?: {
+        targetName: string;
+        targetPath?: AttributePathSegment[];
+    };
+    callback?: ScopeBlock;
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents a variable assignment (e.g., $var = value)
+ */
+export interface Assignment {
+    type: 'assignment';
+    nodeKey?: string;
+    targetName: string;
+    targetPath?: AttributePathSegment[];
+    command?: CommandCall;
+    literalValue?: Value;
+    literalValueType?: 'string' | 'number' | 'boolean' | 'null' | 'object' | 'array';
+    isLastValue?: boolean;
+    isSet?: boolean;
+    isVar?: boolean;
+    isConst?: boolean;
+    hasAs?: boolean;
+    isImplicit?: boolean;
+    fallbackValue?: Value;
+    fallbackValueType?: 'string' | 'number' | 'boolean' | 'null';
+    comments?: CommentWithPosition[];
+    decorators?: DecoratorCall[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents a shorthand assignment (e.g., $var = $)
+ */
+export interface ShorthandAssignment {
+    type: 'shorthand';
+    nodeKey?: string;
+    targetName: string;
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents an inline if statement (e.g., if condition then command [else command])
+ */
+export interface InlineIf {
+    type: 'inlineIf';
+    nodeKey?: string;
+    condition: Expression;
+    command: Statement;
+    elseCommand?: Statement;
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents an if/elseif/else block
+ */
+export interface IfBlock {
+    type: 'ifBlock';
+    nodeKey?: string;
+    condition: Expression;
+    thenBranch: Statement[];
+    elseBranch?: Statement[];
+    elseHasThen?: boolean;
+    elseKeywordPos?: CodePosition;
+    elseifBranches?: Array<{
+        condition: Expression;
+        body: Statement[];
+        hasThen?: boolean;
+        keywordPos?: CodePosition;
+    }>;
+    decorators?: DecoratorCall[];
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents an iftrue statement (e.g., iftrue command)
+ */
+export interface IfTrue {
+    type: 'ifTrue';
+    nodeKey?: string;
+    command: Statement;
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents an iffalse statement (e.g., iffalse command)
+ */
+export interface IfFalse {
+    type: 'ifFalse';
+    nodeKey?: string;
+    command: Statement;
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents a function definition (def/enddef)
+ */
+export interface DefineFunction {
+    type: 'define';
+    nodeKey?: string;
+    name: string;
+    paramNames: string[];
+    body: Statement[];
+    decorators?: DecoratorCall[];
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents a scope block (do/enddo)
+ */
+export interface ScopeBlock {
+    type: 'do';
+    nodeKey?: string;
+    paramNames?: string[];
+    body: Statement[];
+    into?: {
+        targetName: string;
+        targetPath?: AttributePathSegment[];
+    };
+    decorators?: DecoratorCall[];
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents a together block (together/endtogether)
+ */
+export interface TogetherBlock {
+    type: 'together';
+    nodeKey?: string;
+    blocks: ScopeBlock[];
+    decorators?: DecoratorCall[];
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents a for loop (for/endfor)
+ */
+export interface ForLoop {
+    type: 'forLoop';
+    nodeKey?: string;
+    varName: string;
+    iterable?: Expression;
+    from?: Expression;
+    to?: Expression;
+    step?: Expression;
+    keyVarName?: string;
+    body: Statement[];
+    decorators?: DecoratorCall[];
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents a return statement
+ */
+export interface ReturnStatement {
+    type: 'return';
+    nodeKey?: string;
+    value?: Arg;
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents a break statement
+ */
+export interface BreakStatement {
+    type: 'break';
+    nodeKey?: string;
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents a continue statement
+ */
+export interface ContinueStatement {
+    type: 'continue';
+    nodeKey?: string;
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents an event handler block (on/endon)
+ */
+export interface OnBlock {
+    type: 'onBlock';
+    nodeKey?: string;
+    eventName: string;
+    body: Statement[];
+    decorators?: DecoratorCall[];
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+    codePos: CodePosition;
+}
+/**
+ * Represents a cell block (---cell <cellType> <meta...>--- ... ---end---)
+ */
+export interface CellBlock {
+    type: 'cell';
+    nodeKey?: string;
+    cellType: string;
+    meta: Record<string, string>;
+    rawBody: string;
+    body?: Statement[];
+    headerPos: CodePosition;
+    bodyPos: CodePosition;
+    codePos: CodePosition;
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+}
+/**
+ * Represents a prompt block statement (--- ... ---)
+ */
+export interface PromptBlockStatement {
+    type: 'prompt_block';
+    nodeKey?: string;
+    rawText: string;
+    fence: '---';
+    codePos: CodePosition;
+    openPos: CodePosition;
+    bodyPos: CodePosition;
+    closePos: CodePosition;
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+}
+/**
+ * Represents a chunk marker statement (--- chunk:<id> ---)
+ */
+export interface ChunkMarkerStatement {
+    type: 'chunk_marker';
+    nodeKey?: string;
+    id: string;
+    meta?: Record<string, string>;
+    codePos: CodePosition;
+    raw?: string;
+    comments?: CommentWithPosition[];
+    trailingBlankLines?: number;
+}
+/**
+ * Union type representing all possible statement types in the AST
+ */
+export type Statement = CommandCall | Assignment | ShorthandAssignment | InlineIf | IfBlock | IfTrue | IfFalse | DefineFunction | ScopeBlock | TogetherBlock | ForLoop | ReturnStatement | BreakStatement | ContinueStatement | OnBlock | CommentStatement | ChunkMarkerStatement | CellBlock | PromptBlockStatement;

package/dist/types/Environment.type.d.ts

@@ -0,0 +1,53 @@
+import { Value } from '../utils';
+import { DefineFunction, OnBlock, Arg } from './Ast.type';
+export type BuiltinCallback = (callbackArgs: Value[]) => Promise<Value> | Value | null;
+export type BuiltinHandler = (args: Value[], callback?: BuiltinCallback | null) => Promise<Value> | Value | null;
+export type DecoratorHandler = (targetName: string, func: DefineFunction | null, originalArgs: Value[], decoratorArgs: Value[], originalDecoratorArgs?: Arg[]) => Promise<Value[] | Value | null | undefined>;
+export type ParseDecoratorHandler = (targetName: string, func: DefineFunction | null, decoratorArgs: Arg[], environment: Environment) => Promise<void> | void;
+export interface Environment {
+    variables: Map<string, Value>;
+    functions: Map<string, DefineFunction>;
+    builtins: Map<string, BuiltinHandler>;
+    decorators: Map<string, DecoratorHandler>;
+    parseDecorators: Map<string, ParseDecoratorHandler>;
+    metadata: Map<string, FunctionMetadata>;
+    moduleMetadata: Map<string, ModuleMetadata>;
+    currentModule: string | null;
+    variableMetadata: Map<string, Map<string, Value>>;
+    functionMetadata: Map<string, Map<string, Value>>;
+    constants: Set<string>;
+    eventHandlers: Map<string, OnBlock[]>;
+}
+export interface Frame {
+    locals: Map<string, Value>;
+    lastValue: Value;
+    isFunctionFrame?: boolean;
+    forgotten?: Set<string>;
+    isIsolatedScope?: boolean;
+}
+export type DataType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'null' | 'any';
+export type FormInputType = 'text' | 'number' | 'textarea' | 'select' | 'checkbox' | 'radio' | 'date' | 'datetime' | 'file' | 'json' | 'code' | 'varname';
+export interface ParameterMetadata {
+    name: string;
+    label?: string;
+    dataType: DataType;
+    description: string;
+    formInputType: FormInputType;
+    required?: boolean;
+    defaultValue?: Value;
+    children?: ParameterMetadata;
+}
+export interface FunctionMetadata {
+    description: string;
+    parameters: ParameterMetadata[];
+    returnType: DataType;
+    returnDescription: string;
+    example?: string;
+}
+export interface ModuleMetadata {
+    description: string;
+    methods: string[];
+    author?: string;
+    category?: string;
+    doc_url?: string;
+}

package/dist/utils/args.d.ts

@@ -0,0 +1,24 @@
+import { Value } from './types';
+/**
+ * Utility function to extract named arguments from function call arguments.
+ * Named arguments are passed as the last argument (an object with string keys).
+ *
+ * @param args The arguments array passed to a BuiltinHandler
+ * @returns An object with `positionalArgs` (Value[]) and `namedArgs` (Record<string, Value>)
+ *
+ * @example
+ * ```typescript
+ * export const MyFunctions: Record<string, BuiltinHandler> = {
+ *   myFunction: (args) => {
+ *     const { positionalArgs, namedArgs } = extractNamedArgs(args);
+ *     const url = namedArgs.url || positionalArgs[0];
+ *     const body = namedArgs.body || positionalArgs[1];
+ *     // ... use url and body
+ *   }
+ * };
+ * ```
+ */
+export declare function extractNamedArgs(args: Value[]): {
+    positionalArgs: Value[];
+    namedArgs: Record<string, Value>;
+};

package/dist/utils/errorFormatter.d.ts

@@ -0,0 +1,22 @@
+import { CodePosition } from '../types/Ast.type';
+import { Token } from '../classes/Lexer';
+export interface ErrorContext {
+    codePos?: CodePosition;
+    code?: string;
+    token?: Token;
+    message: string;
+}
+/**
+ * Format an error message with code context
+ *
+ * @param context - Error context with position and code information
+ * @returns Formatted error message with code snippet
+ */
+export declare function formatErrorWithContext(context: ErrorContext): string;
+/**
+ * Create an error with code context
+ *
+ * @param context - Error context
+ * @returns Error object with formatted message
+ */
+export declare function createErrorWithContext(context: ErrorContext): Error;

package/dist/utils/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility functions for RobinPath
+ */
+export * from './types';
+export * from './stringParsing';
+export * from './valueConversion';
+export * from './args';
+export * from './errorFormatter';

package/dist/utils/stringParsing.d.ts

@@ -0,0 +1,41 @@
+import { AttributePathSegment } from './types';
+/**
+ * Split a script into logical lines, respecting strings, $() subexpressions, and backslash continuation.
+ * Treats ; and \n as line separators, but only at the top level (not inside strings or $()).
+ * Handles backslash line continuation: lines ending with \ are joined with the next line.
+ */
+export declare function splitIntoLogicalLines(script: string): string[];
+/**
+ * Handle backslash line continuation.
+ * Lines ending with \ are joined with the next line, removing the backslash
+ * and replacing the newline + leading whitespace with a single space.
+ */
+export declare function handleBackslashContinuation(script: string): string;
+/**
+ * Lexer utility functions for token parsing
+ */
+export declare class LexerUtils {
+    static parseString(token: string): string;
+    static isString(token: string): boolean;
+    static isNumber(token: string): boolean;
+    static isInteger(token: string): boolean;
+    static isVariable(token: string): boolean;
+    /**
+     * Parse attribute access path from a variable token
+     * Returns the base variable name and path segments
+     * If name is empty string, it means the last value ($) with attributes
+     */
+    static parseVariablePath(token: string): {
+        name: string;
+        path: AttributePathSegment[];
+    };
+    /**
+     * Parse a dynamic key from inside brackets: [$varName] or [$varName.property]
+     * @param str The full string being parsed
+     * @param pos Position right after the '$' character
+     * @returns The parsed segment and the position after the closing ']'
+     */
+    private static parseDynamicKey;
+    static isLastValue(token: string): boolean;
+    static isPositionalParam(token: string): boolean;
+}

package/dist/utils/types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared types for utility functions
+ */
+export type Value = string | number | boolean | null | object;
+export type AttributePathSegment = {
+    type: 'property';
+    name: string;
+} | {
+    type: 'index';
+    index: number;
+} | {
+    type: 'dynamicKey';
+    variable: string;
+    varPath?: AttributePathSegment[];
+};