@minecraft/creator-tools/lib/dataform/SummarizerEvaluator.d.ts

Minecraft Creator Tools command line and libraries.

import IFormDefinition from "./IFormDefinition";
import ISummarizer, { ISummarizerEvaluatedResult, ISummarizerOptions, ISummarizerResult } from "./ISummarizer";
/**
 * Evaluates summarizer definitions against data objects.
 *
 * ## Design Philosophy
 *
 * Summarizers are **authored**, not dynamically generated. When creating a
 * summarizer (by AI or human), the author looks at form samples and bakes in
 * meaningful comparisons as literal text (e.g., "stronger than an Iron Golem").
 *
 * This evaluator focuses on:
 * - Evaluating conditions to select which phrases/tokens to display
 * - Formatting values with units and humanification
 * - Combining phrases with proper grammar
 *
 * It does NOT maintain a catalog of reference values - comparisons are
 * baked into the summarizer definition as literal text.
 */
export default class SummarizerEvaluator {
    private formDefinition?;
    private currentData?;
    private options;
    /**
     * Create a new SummarizerEvaluator.
     */
    constructor();
    /**
     * Evaluate a summarizer against data to produce natural language phrases.
     *
     * @param summarizer The summarizer definition
     * @param data The data object to summarize
     * @param formDefinition Optional form definition for sample lookup
     * @param options Evaluation options
     * @returns Result containing phrases and formatted output
     *
     * @example
     * const result = evaluator.evaluate(
     *   healthSummarizer,
     *   { max: 500, value: 500 },
     *   healthForm
     * );
     * // result.phrases = ["has god-tier health (500 HP)"]
     * // result.asCompleteSentence = "This entity has god-tier health (500 HP)."
     */
    evaluate(summarizer: ISummarizer, data: object, formDefinition?: IFormDefinition, options?: ISummarizerOptions): ISummarizerResult;
    /**
     * Evaluate a summarizer against data with structured token output for rich rendering.
     *
     * This method is similar to evaluate() but returns structured data that preserves
     * token boundaries and effects, allowing the UI to render tokens with styling.
     *
     * @param summarizer The summarizer definition
     * @param data The data object to summarize
     * @param formDefinition Optional form definition for sample lookup
     * @param options Evaluation options
     * @returns Result containing structured tokens with effects
     *
     * @example
     * const result = evaluator.evaluateWithEffects(
     *   healthSummarizer,
     *   { max: 500, value: 500 },
     *   healthForm
     * );
     * // result.evaluatedPhrases[0].tokens = [
     * //   { text: "has ", effects: undefined },
     * //   { text: "god-tier health", effects: { emphasis: "strong", sentiment: "positive" } },
     * //   { text: " (", effects: { emphasis: "subtle" } },
     * //   { text: "500 HP", effects: { emphasis: "strong", role: "value" } },
     * //   { text: ")", effects: { emphasis: "subtle" } }
     * // ]
     */
    evaluateWithEffects(summarizer: ISummarizer, data: object, formDefinition?: IFormDefinition, options?: ISummarizerOptions): ISummarizerEvaluatedResult;
    /**
     * Join phrases into a grammatically correct sentence.
     */
    private joinPhrases;
    /**
     * Evaluate an array of tokens and return structured output with effects.
     *
     * This method preserves token boundaries and effects for rich rendering.
     */
    private evaluateTokensWithEffects;
    /**
     * Evaluate a single token and return structured output with effects.
     *
     * Some token types (like switch, list, template) recursively evaluate
     * child tokens and inherit effects from the parent.
     */
    private evaluateTokenWithEffects;
    /**
     * Apply parent effects to child tokens that don't have their own effects.
     *
     * Child effects take precedence. This allows a parent switch token to
     * set a sentiment (e.g., "positive" for high health) that applies to
     * all its children unless they override it.
     */
    private applyEffectsToChildren;
    /**
     * Evaluate an array of tokens and concatenate their output.
     */
    private evaluateTokens;
    /**
     * Evaluate a single token and return its string output.
     */
    private evaluateToken;
    /**
     * Evaluate a value token: insert a field value from the data.
     */
    private evaluateValueToken;
    /**
     * Evaluate a switch token: select tokens based on conditions.
     */
    private evaluateSwitchToken;
    /**
     * Evaluate a list token: render items as a grammatically correct list.
     */
    private evaluateListToken;
    /**
     * Evaluate a template token: string interpolation.
     */
    private evaluateTemplateToken;
    /**
     * Evaluate a plural token: handle singular/plural forms.
     */
    private evaluatePluralToken;
    /**
     * Evaluate a sample token: pull a sample value from the form definition.
     */
    private evaluateSampleToken;
    /**
     * Evaluate a unit token: format value with units.
     */
    private evaluateUnitToken;
    /**
     * Evaluate an exists token: check if a field is defined.
     */
    private evaluateExistsToken;
    /**
     * Evaluate a conjunction token: join items with a conjunction.
     */
    private evaluateConjunctionToken;
    /**
     * Get a field value from the data object only (literal value).
     * Does NOT fall back to default values from the form definition.
     * Use this when you need to check if a value is explicitly set.
     * Supports dot notation for nested fields: "damage.min"
     */
    private getLiteralFieldValue;
    /**
     * Get the default value for a field from the form definition.
     */
    private getFieldDefaultValue;
    /**
     * Get a field value from the data object, falling back to the
     * form definition's default value if not explicitly set.
     *
     * This is the "effective" value - what the user would see in the form.
     * Supports dot notation for nested fields: "damage.min"
     */
    private getFieldValue;
    /**
     * Check if all conditions are met.
     */
    private checkConditions;
    /**
     * Check a single condition against data.
     * Uses effective values (data + defaults) unless checking for literallyDefined.
     */
    private checkCondition;
    /**
     * Format a value according to a format string.
     */
    private formatValue;
    /**
     * Apply humanification to a value.
     */
    private humanifyValue;
}