// --- Enhance String.prototype -----------------------------------
/**
 * Populates a template: replaces all provided place-holders in a string, with values.
 *
 * @param {object} oMapping
 * A hash in which every key represents a place-holder in the string to be replaced with its correlating value
 */
String.prototype.populateTemplate = function(oMapping)
{
	Claim.isObject(oMapping, "String.populateTemplate(..,oMapping,..)");

	var sTemplate, placehoder, replacement;

	sTemplate = String(this);

	for(placeholder in oMapping)
	{
		replacement = oMapping[placeholder];
		sTemplate = sTemplate.replace(new RegExp(placeholder,"g"), replacement);
	}
	return sTemplate;
}
String.prototype.beutifySerialization = function()
{
	var out = []
	  , indent = ""
	  , i
	  , arr = this.split("");
	  
	for(i = 0; i < arr.length; i++){
		switch(arr[i]){
			case "{":
				indent += "\t";
				out[out.length] = "\n" + indent;
				out[out.length] = arr[i] + "\t";
				break;
			case "}":
				out[out.length] = "\n" + indent;
				out[out.length] = arr[i] + "\t";
				indent = indent.substr(1);
				break;
			case "[":
				indent += "\t";
				out[out.length] = "\n" + indent;
				out[out.length] = arr[i] + "\t";
				break;
			case "]":
				out[out.length] = "\n" + indent;
				out[out.length] = arr[i] + "\t";
				indent = indent.substr(1);
				break;
			case ",":
				out[out.length] = "\n" + indent;
				out[out.length] = arr[i] + "\t";
				break;
			default:
				out[out.length] = arr[i];
		}
	}	
	return out.join("");	
}
/**
 * Binds a template: replaces all indicated placeholders with data. 
 * Data comes from data-properties on the oDataSource, 
 * and the mapping between placeholders in the string and the data-properties 
 * is provided in the oMapping parameter.
 *
 * @param {object} oMapping
 * A hash, in which every key is a placeholder in the string, 
 * and its correlating value can be:
 * - A string representing a data-property on the data-srource in oDataSource
 * - A function that returns value as a function of the oDataSource
 * - Any other value will be casted to string to return the value, and the returned value will be used, regardles to the data-source.
 *
 * @param {object} oDataSource
 * A data-object by which to bind the template
 *
 * @param {object(optional)} oLog
 * When provided - the logging of this execution is emitted to the provided instance.
 * Otherwise - to a casual instance, named "String.bindTemplate".
 */
String.prototype.bindTemplate = function(oMapping, oDataSource, oLog)
{
	Claim.isObject(oMapping, "String.bindTemplate(..,oMapping,..)");
	Claim.isObject(oDataSource , "String.bindTemplate(..,oDataSource)");

	var sTemplate, placehoder, attribute, replacment;
	var log = (oLog && oLog instanceof Log4Js.Logger)? oLog : new Log4Js.Logger("String.bindTemplate");
	
	sTemplate = this.toString();
	
	for(placehoder in oMapping)
	{
		attribute = oMapping[placehoder];
		if(undefined == attribute || null == attribute){
			log.warn("in bindTemplate(...) oMapping dictionary specifies a placeholder without providing its data-attribute name: " + placehoder);
			continue;
		}
		
		switch(typeof(attribute))
		{
			case 'function':
				try
				{
					replacement = attribute(oDataSource, log);
				}catch(ex){
					log.error("String.bindTemplate - Error in mapping-handler for " + placehoder + " : " + attribute.toString() );
					throw ex;
				}
				break;
				
			case 'string':
				replacement = oDataSource[attribute];
				if(null == replacement){
					log.warn("in bindTemplate(...) oMapping dictionary specifies a property that does not exist on the provided oDataSource. Placehoder: " + placehoder +", using the name of the attribute: " + attribute);
					replacement = attribute;
				}
				break;
			
			default:
				replacement = String(attribute);
			
		}
		
		//replacment = replacment.replace(/\$/g,"");
		sTemplate = sTemplate.replace(new RegExp(placehoder,"g"), replacement);
	}
	return sTemplate;
}
// --- /Enhance String.prototype -----------------------------------