001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.tools.template_engine;
003
004/**
005 * Interface for one node in the abstract syntax tree that is the result of parsing a template
006 * string with {@link TemplateParser}.
007 *
008 * The node can either be branching (condition, context switch) or a leaf node (variable, static text).
009 * The root node, representing the entire template is also a {@code TemplateEntry}.
010 */
011public interface TemplateEntry {
012
013    /**
014     * Execute this template by generating text for a given data provider.
015     * @param dataProvider the data provider from which information should be compiled to a string
016     * @return the generated text
017     */
018    default String getText(TemplateEngineDataProvider dataProvider) {
019        StringBuilder sb = new StringBuilder();
020        appendText(sb, dataProvider);
021        return sb.toString();
022    }
023
024    /**
025     * Execute this template by generating text for a given data provider.
026     * @param result the {@link StringBuilder} to append the text to
027     * @param dataProvider the data provider from which information should be compiled to a string
028     */
029    void appendText(StringBuilder result, TemplateEngineDataProvider dataProvider);
030
031    /**
032     * Check if this template is applicable to the given data provider.
033     *
034     * @param dataProvider the data provider to check
035     * @return true if all conditions are fulfilled to apply the template (for instance all
036     * required key=value mappings are present), false otherwise
037     */
038    boolean isValid(TemplateEngineDataProvider dataProvider);
039}