littlewing 0.9.2 → 0.9.3

package/dist/index.d.ts

@@ -596,6 +596,94 @@ declare class Executor {
 */
 declare function execute(input: string | ASTNode, context?: ExecutionContext): RuntimeValue;
 /**
+* Options for customizing the humanization output
+*/
+interface HumanizeOptions {
+	/**
+	* Enable HTML output with wrapper tags
+	* @default false
+	*/
+	html?: boolean;
+	/**
+	* CSS classes to apply to different node types when html is true
+	*/
+	htmlClasses?: {
+		number?: string;
+		identifier?: string;
+		operator?: string;
+		function?: string;
+	};
+	/**
+	* Custom phrases for function names
+	* Maps function name to human-readable phrase
+	* Example: { 'MAX': 'the maximum of', 'CUSTOM': 'my custom function with' }
+	*/
+	functionPhrases?: Record<string, string>;
+	/**
+	* Custom phrases for operators
+	* Overrides default operator text
+	*/
+	operatorPhrases?: Partial<Record<Operator, string>>;
+	/**
+	* Use more verbose, descriptive phrasing
+	* @default false
+	*/
+	verbose?: boolean;
+}
+/**
+* Converts an AST node to human-readable English text
+*/
+declare class Humanizer {
+	private readonly options;
+	private readonly operatorPhrases;
+	private readonly functionPhrases;
+	constructor(options?: HumanizeOptions);
+	/**
+	* Humanize an AST node into English text
+	*/
+	humanize(node: ASTNode): string;
+	private humanizeProgram;
+	private humanizeNumberLiteral;
+	private humanizeIdentifier;
+	private humanizeBinaryOp;
+	private humanizeUnaryOp;
+	private humanizeFunctionCall;
+	private humanizeAssignment;
+	private humanizeConditionalExpression;
+	/**
+	* Wrap text in HTML tag if html option is enabled
+	*/
+	private wrapHtml;
+}
+/**
+* Humanize an AST node into human-readable English text
+*
+* @param node - The AST node to humanize
+* @param options - Optional configuration for the output
+* @returns Human-readable English text
+*
+* @example
+* ```typescript
+* const ast = parseSource('price * quantity > 100 ? (price * quantity - discount) * (1 + tax_rate) : MAX(price * quantity, 50)')
+* const text = humanize(ast)
+* // "if price times quantity is greater than 100 then (price times quantity minus discount) times (1 plus tax_rate), otherwise the maximum of price times quantity and 50"
+* ```
+*
+* @example
+* ```typescript
+* // With HTML formatting
+* const text = humanize(ast, {
+*   html: true,
+*   htmlClasses: {
+*     identifier: 'variable',
+*     operator: 'op',
+*     number: 'num'
+*   }
+* })
+* ```
+*/
+declare function humanize(node: ASTNode, options?: HumanizeOptions): string;
+/**
 * Lexer - converts source code into tokens
 * Implements a single-pass O(n) tokenization algorithm
 */
@@ -720,4 +808,4 @@ declare class Parser {
 * @returns Parsed AST
 */
 declare function parseSource(source: string): ASTNode;
-export { parseSource, optimize, isUnaryOp, isProgram, isNumberLiteral, isIdentifier, isFunctionCall, isConditionalExpression, isBinaryOp, isAssignment, generate, extractInputVariables, execute, defaultContext, exports_date_utils as dateUtils, exports_ast as ast, UnaryOp, TokenType, Token, RuntimeValue, Program, Parser, Operator, NumberLiteral, Lexer, Identifier, FunctionCall, Executor, ExecutionContext, ConditionalExpression, CodeGenerator, BinaryOp, Assignment, ASTNode };
+export { parseSource, optimize, isUnaryOp, isProgram, isNumberLiteral, isIdentifier, isFunctionCall, isConditionalExpression, isBinaryOp, isAssignment, humanize, generate, extractInputVariables, execute, defaultContext, exports_date_utils as dateUtils, exports_ast as ast, UnaryOp, TokenType, Token, RuntimeValue, Program, Parser, Operator, NumberLiteral, Lexer, Identifier, Humanizer, HumanizeOptions, FunctionCall, Executor, ExecutionContext, ConditionalExpression, CodeGenerator, BinaryOp, Assignment, ASTNode };

package/dist/index.js

@@ -1037,6 +1037,188 @@ function execute(input, context) {
   const executor = new Executor(context);
   return executor.execute(node);
 }
+// src/humanizer.ts
+var DEFAULT_OPERATOR_PHRASES = {
+  "+": "plus",
+  "-": "minus",
+  "*": "times",
+  "/": "divided by",
+  "%": "modulo",
+  "^": "to the power of",
+  "==": "equals",
+  "!=": "is not equal to",
+  "<": "is less than",
+  ">": "is greater than",
+  "<=": "is less than or equal to",
+  ">=": "is greater than or equal to",
+  "&&": "and",
+  "||": "or"
+};
+var DEFAULT_FUNCTION_PHRASES = {
+  ABS: "the absolute value of",
+  CEIL: "the ceiling of",
+  FLOOR: "the floor of",
+  ROUND: "the rounded value of",
+  SQRT: "the square root of",
+  MIN: "the minimum of",
+  MAX: "the maximum of",
+  CLAMP: "clamped",
+  SIN: "the sine of",
+  COS: "the cosine of",
+  TAN: "the tangent of",
+  LOG: "the natural logarithm of",
+  LOG10: "the base-10 logarithm of",
+  EXP: "e raised to the power of",
+  NOW: "the current time",
+  DATE: "the date",
+  GET_YEAR: "the year of",
+  GET_MONTH: "the month of",
+  GET_DAY: "the day of",
+  GET_HOUR: "the hour of",
+  GET_MINUTE: "the minute of",
+  GET_SECOND: "the second of",
+  START_OF_DAY: "the start of day for",
+  END_OF_DAY: "the end of day for",
+  START_OF_MONTH: "the start of month for",
+  END_OF_MONTH: "the end of month for",
+  ADD_DAYS: "add days to",
+  ADD_MONTHS: "add months to",
+  ADD_YEARS: "add years to",
+  DIFFERENCE_IN_DAYS: "the difference in days between",
+  DIFFERENCE_IN_HOURS: "the difference in hours between",
+  DIFFERENCE_IN_MINUTES: "the difference in minutes between",
+  IS_WEEKEND: "whether it is a weekend for",
+  IS_LEAP_YEAR: "whether it is a leap year for"
+};
+
+class Humanizer {
+  options;
+  operatorPhrases;
+  functionPhrases;
+  constructor(options = {}) {
+    this.options = options;
+    this.operatorPhrases = {
+      ...DEFAULT_OPERATOR_PHRASES,
+      ...options.operatorPhrases
+    };
+    this.functionPhrases = {
+      ...DEFAULT_FUNCTION_PHRASES,
+      ...options.functionPhrases
+    };
+  }
+  humanize(node) {
+    if (isProgram(node)) {
+      return this.humanizeProgram(node);
+    }
+    if (isNumberLiteral(node)) {
+      return this.humanizeNumberLiteral(node);
+    }
+    if (isIdentifier(node)) {
+      return this.humanizeIdentifier(node);
+    }
+    if (isBinaryOp(node)) {
+      return this.humanizeBinaryOp(node);
+    }
+    if (isUnaryOp(node)) {
+      return this.humanizeUnaryOp(node);
+    }
+    if (isFunctionCall(node)) {
+      return this.humanizeFunctionCall(node);
+    }
+    if (isAssignment(node)) {
+      return this.humanizeAssignment(node);
+    }
+    if (isConditionalExpression(node)) {
+      return this.humanizeConditionalExpression(node);
+    }
+    throw new Error(`Unknown node type: ${JSON.stringify(node)}`);
+  }
+  humanizeProgram(node) {
+    const statements = node.statements.map((stmt) => {
+      const text = this.humanize(stmt);
+      return text.charAt(0).toUpperCase() + text.slice(1);
+    });
+    return statements.join(". ");
+  }
+  humanizeNumberLiteral(node) {
+    const text = String(node.value);
+    return this.wrapHtml(text, "number");
+  }
+  humanizeIdentifier(node) {
+    return this.wrapHtml(node.name, "identifier");
+  }
+  humanizeBinaryOp(node) {
+    const left = this.humanize(node.left);
+    const right = this.humanize(node.right);
+    const operator = this.operatorPhrases[node.operator];
+    const operatorText = this.wrapHtml(operator, "operator");
+    return `${left} ${operatorText} ${right}`;
+  }
+  humanizeUnaryOp(node) {
+    const arg = this.humanize(node.argument);
+    if (node.operator === "-") {
+      const needsGrouping = !isNumberLiteral(node.argument) && !isIdentifier(node.argument);
+      if (needsGrouping) {
+        return `the negative of ${arg}`;
+      }
+      return `negative ${arg}`;
+    }
+    if (node.operator === "!") {
+      return `not ${arg}`;
+    }
+    throw new Error(`Unknown unary operator: ${node.operator}`);
+  }
+  humanizeFunctionCall(node) {
+    const funcName = this.wrapHtml(node.name, "function");
+    const args = node.arguments.map((arg) => this.humanize(arg));
+    const phrase = this.functionPhrases[node.name];
+    if (phrase) {
+      if (args.length === 0) {
+        return phrase;
+      }
+      if (args.length === 1) {
+        return `${phrase} ${args[0]}`;
+      }
+      const lastArg2 = args[args.length - 1];
+      const otherArgs2 = args.slice(0, -1).join(", ");
+      return `${phrase} ${otherArgs2} and ${lastArg2}`;
+    }
+    if (args.length === 0) {
+      return `the result of ${funcName}`;
+    }
+    if (args.length === 1) {
+      return `the result of ${funcName} with ${args[0]}`;
+    }
+    const lastArg = args[args.length - 1];
+    const otherArgs = args.slice(0, -1).join(", ");
+    return `the result of ${funcName} with ${otherArgs} and ${lastArg}`;
+  }
+  humanizeAssignment(node) {
+    const name = this.wrapHtml(node.name, "identifier");
+    const value = this.humanize(node.value);
+    return `set ${name} to ${value}`;
+  }
+  humanizeConditionalExpression(node) {
+    const condition = this.humanize(node.condition);
+    const consequent = this.humanize(node.consequent);
+    const alternate = this.humanize(node.alternate);
+    return `if ${condition} then ${consequent}, otherwise ${alternate}`;
+  }
+  wrapHtml(text, type) {
+    if (!this.options.html) {
+      return text;
+    }
+    const className = this.options.htmlClasses?.[type];
+    if (className) {
+      return `<span class="${className}">${text}</span>`;
+    }
+    return `<span>${text}</span>`;
+  }
+}
+function humanize(node, options) {
+  const humanizer = new Humanizer(options);
+  return humanizer.humanize(node);
+}
 // src/optimizer.ts
 function optimize(node) {
   if (isNumberLiteral(node)) {
@@ -1099,6 +1281,7 @@ export {
   isConditionalExpression,
   isBinaryOp,
   isAssignment,
+  humanize,
   generate,
   extractInputVariables,
   execute,
@@ -1108,6 +1291,7 @@ export {
   TokenType,
   Parser,
   Lexer,
+  Humanizer,
   Executor,
   CodeGenerator
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "littlewing",
-	"version": "0.9.2",
+	"version": "0.9.3",
 	"description": "A minimal, high-performance arithmetic expression language with lexer, parser, and executor. Optimized for browsers with zero dependencies and type-safe execution.",
 	"keywords": [
 		"arithmetic",