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
Show all versions of fmpp Show documentation
General-purpose text file preprocessor tool that uses FreeMarker templates.
/*
* 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;
}