fmpp.tdd.EvaluationEnvironment Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of fmpp Show documentation
General-purpose text file preprocessor tool that uses FreeMarker templates.
The newest version!
/*
 * Copyright 2014 Attila Szegedi, Daniel Dekany, Jonathan Revusky
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package fmpp.tdd;

/**
 * Callbacks that let you control the behaviour of TDD expression evaluation.
 */
public interface EvaluationEnvironment {
    /**
     * The code of event that indicates that we have started to evaluate the
     * value in a key:value pair.
     */
    int EVENT_ENTER_HASH_KEY = 1;
    
    /**
     * The code of event that indicates that we have finished to evaluate the
     * value in a key:value pair.
     */
    int EVENT_LEAVE_HASH_KEY = -1;

    /**
     * The code of event that indicates that we have started to evaluate the
     * parameter list in a function call.
     */
    int EVENT_ENTER_FUNCTION_PARAMS = 3;
    
    /**
     * The code of event that indicates that we have finished to evaluate the
     * parameter list in a function call.
     */
    int EVENT_LEAVE_FUNCTION_PARAMS = -3;

    /**
     * The code of event that indicates that we have started to evaluate the
     * items in a sequence. This does not include function call parameter lists.
     */
    int EVENT_ENTER_SEQUENCE = 4;
    
    /**
     * The code of event that indicates that we have finished to evaluate the
     * items in a sequence.
     */
    int EVENT_LEAVE_SEQUENCE = -4;


    /**
     * The code of event that indicates that we have started to evaluate the
     * items in a hash.
     */
    int EVENT_ENTER_HASH = 5;
    
    /**
     * The code of event that indicates that we have finished to evaluate the
     * items in a sequence.
     */
    int EVENT_LEAVE_HASH = -5;
    
    Object RETURN_SKIP = new Object();

    Object RETURN_FRAGMENT = new Object();
    
    /**
     * Evaluates the function call. This method may simply returns its
     * parameter, which means that the function was not resolved, and thus the
     * function call will be availble for further interpretation in the result
     * of the TDD expression evaluation.
     * 
     * @param fc the function call to evaluate.
     *   
     * @return the return value of the function call. During the evaluation of
     *     a TDD expression, function calls will be replaced with their return
     *     values. 
     *     If the return value is a {@link FunctionCall} object, it will not be
     *     evaluated again. This way, the final result of a TDD expression
     *     evaluation can contain {@link FunctionCall} objects.
     */
    Object evalFunctionCall(FunctionCall fc, Interpreter ip) throws Exception;
    
    /**
     * Notifies about an event during expression evaluation.
     * 
     * @param event An EVENT_... constant. Further events may will
     *     be added later, so the implementation must silently ignore events
     *     that it does not know. It is guaranteed that for each
     *     EVENT_ENTER_... event there will be an
     *     EVENT_LEAVE_... event later, except if
     *     notifyContextChange has thrown exception during handling
     *     EVENT_ENTER_..., in which case it is guaranteed that
     *     there will be no corresponding EVENT_LEAVE_... event.
     * @param ip the {@link Interpreter} instance that evaluates the text.
     *      The value returned by {@link Interpreter#getPosition()} will be
     *      the position in the text where the this even has been created:
     *      
     *        {@link #EVENT_ENTER_HASH_KEY}: points the first character
     *            of the value of the key:value pair.
     *        
{@link #EVENT_ENTER_SEQUENCE}, {@link #EVENT_ENTER_HASH}, and
     *            {@link #EVENT_ENTER_FUNCTION_PARAMS}: points the first
     *            character after the [ and ( respectively.  
     *        
{@link #EVENT_LEAVE_SEQUENCE}, {@link #EVENT_LEAVE_HASH}, and
     *            {@link #EVENT_LEAVE_FUNCTION_PARAMS}: points the
     *            terminating character, that is, the ] or )
     *            or the character after the end of the string.
     *        
     * @param name For {@link #EVENT_ENTER_HASH_KEY} and
     *     {@link #EVENT_ENTER_FUNCTION_PARAMS}, the name of the hash key or
     *     function. It is null otherwise.
     * @param extra Even specific extra information.
     *     
     *       For {@link #EVENT_ENTER_HASH}, {@link #EVENT_LEAVE_HASH}, 
     *           {@link #EVENT_ENTER_SEQUENCE}, {@link #EVENT_LEAVE_SEQUENCE} it
     *           is the Map or List that is being
     *           built by the hash or sequence. It's OK to modify this
     *           Map or List.
     *       
For other events it's
     *           value is currently null.  
     *     
     * @return return The allowed return values and their meaning depends on
     *     the event. But return value null always means
     *     "do nothing special". The currently defiend non-null
     *     return values for the events:
     *     
     *       {@link #EVENT_ENTER_HASH_KEY}:
     *          
     *            {@link #RETURN_SKIP}: Skip the key:value
     *                pair. That is, the key:value pair will not be added to
     *                the map. The value expression will not be evaluated.
     *            
{@link #RETURN_FRAGMENT}: The value of the key:value pair
     *                will be the {@link Fragment} that stores the value
     *                expression. The value expression will not be evaluated.
     *                However, if the value is implicit boolean 
     *                true, (i.e. you omit the value) then
     *                {@link #RETURN_FRAGMENT} has no effect. 
     *          
     *       

     *       
{@link #EVENT_ENTER_HASH} if the hash uses { and
     *           }):
     *          
     *            {@link #RETURN_FRAGMENT}: The value of the hash will be
     *                the {@link Fragment} that stores the hash expression.
     *                The hash expression will not be evaluated.
     *          
     *       
     *     
     */
    Object notify(int event, Interpreter ip, String name, Object extra)
            throws Exception;
}