/*!
  @header ECParameterString
  @abstract Module of Encore
 
  @availability OS X, GNUstep
  @copyright 2004, 2005, 2006 Oliver Langer

  Author: Oliver Langer

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA

  <pre>
  -------------------------------------------------------------------------
  Modification history

  18.01.06 ola     initial version
  22.08.06 ola     license changed
  -------------------------------------------------------------------------
  </pre>
*/

#if !defined(__ECParameterString_H)
#define __ECParameterString_H

#include <Foundation/Foundation.h>
#include <Encore/ECObject.h>

@protocol ECParameterEvaluater;

/*!
 * @class ECParameterString
 * @abstractThis string class allows the usage of parameters which are 
 *   substituted during the formatting of the string.
 * @discussion
 *  This class expects format strings like e.g. 
 * <pre>"Here is variableA=${variableA} and here is variable=${variableB}"</pre>
 * In conjunction with a current set of parameter values this class
 * substitutes the placeholders accordingly and returns a standard
 * NSString implementation.<p/>
 * It is important that the hand-off format string <b>does notcontain any
 * formatting characters</b> (see NSString). It may only contain parameters!
 * But the values of a parameter may contain formatting characters...<p/>
 * <b>Note:</b> At present the implementation only allows the usage of
 *   up to (not necessarely unique) variables in a format string.
 */
@interface ECParameterString : ECObject {
  @private
    NSMutableString *formatString;
    NSMutableArray *parameters;
    id <ECParameterEvaluater> parameterEvaluater;
}


/*!
 * @method initWithFormat
 * @param aFormatString string containing variables which have to be
 *   substituted.
 * It is important that the hand-off format string <b>does notcontain any
 * formatting characters</b> (see NSString). It may only contain parameters!
 * @param aParameterEvaluator used to bind the variabes. The binding
 * will <b>not</b> be performed with this call.
 * @result self
 */
- initWithFormat: (NSString *) aFormatString
  parameterEvaluater: (id <ECParameterEvaluater>) aParameterEvaluater;
     
- (void) dealloc;


/*!
 * @method parseFormatString
 * @abstract internal method used to parse the specified format string
 * @discussion modifies the internal variable {@link formatString}
 * @param aFormatString format string given by method -init
 * @result self
 */
- parseFormatString: (NSString *) aFormatString;


/*!
 * @method substituteVariables
 * @abstract Using the current variable binding this method substitutes all
 *   variables by their assigned values.
 * @discussion The binding of the variables, that is the evaluation on behalf
 *   of the ECParameterEvaluater instance is done when calling this method.
 *   Up to this time variables may be changed etc. But when calling this
 *   method all bindings must have been done so far.
 * @result resulting string
 */
- (NSString *) substituteVariables;
@end


// --------------------------------------------- ECParameterEvaluater
/*!
 * @protocol ECParameterEvaluater
 * @abstract Instances implementing this interface are use to bind variables
 *   of a parameterized String ({@link ECParameterString}).
 * @discussion For each evaluation the ECParameterEvaluator is called to set
 *   the string values for the hand-off parameters.
 */
@protocol ECParameterEvaluater <ECObject>
/*!
 * @method evaluateParameters
 * @abstract Used to bind variables to a specific value.
 * @discussion This method is called when constructing strings of a 
 *   ECParameterString. The evaluator has to return a dictionary which maps
 *   a parameter to a corresponding string
 * @parameter parameters set of NSString instances which specify a parameter
 * @result a dictionary mapping each parameter to a string value (NSString
 *   instance)
 */
- (NSDictionary *) evaluateParameters: (NSArray *) parameters;
@end

// --------------------------------------------- ECDefaultParameterEvaluaterImpl

/*!
 * @class ECDefaultParameterEvaluaterImpl
 * @abstract performs a simple parameter substiution based on an dictionary
 */
@interface ECDefaultParameterEvaluaterImpl : ECObject <ECParameterEvaluater> {
  @private
    NSMutableDictionary *parameterToValue;
}

- init;
- (void) dealloc;

/*!
 * @method evaluateParameters
 * @abstract Used to bind variables to a specific value.
 * @discussion This method is called when constructing strings of a 
 *   ECParameterString. The evaluator has to return a dictionary which maps
 *   a parameter to a corresponding string
 * @parameter parameters set of NSString instances which specify a parameter
 * @result a dictionary mapping each parameter to a string value (NSString
 *   instance)
 */
- (NSDictionary *) evaluateParameters: (NSArray *) parameters;


/*!
 * @method parameterValues
 * @result current set of variables and their valus
 */
- (NSDictionary *) parameterValues;


/*!
 * @method removeAllVariables
 * @abstract removes all variables
 */
- removeAllVariables;


/*! 
 * @method setParameterValues
 * @abstract used to hand-off all parameters. The previously set of varaible
 *   values is being deleted with this call.
 * @paramater dictionary Maps a variable (dictionary key of type NSString)
 *   to a value (dictionary value of type NSString)
 * @result self
 */
- setParameterValues: (NSDictionary *) dictionary;


/*!
 * @method setValue
 * @abstract sets/overwrites a value for a variable
 * @parameter aValue value to set
 * @parameter aVariable variable to add/modify
 * @result self
 */
- setValue: (NSString *) aValue forVariable: (NSString *) aVariable;
@end

#endif