com.codemesh.terp.api
Interface Converter<T>

All Known Implementing Classes:

Ant.AntConverter, Ar.ArConverter, Bc.BcConverter, Cpp.AccConverter, Cpp.CppConverter, Cpp.GccConverter, Cpp.IccConverter, Cpp.MsvcConverter, Cpp.QccConverter, Cpp.SunccConverter, Cpp.XlcConverter, Csharp.CsharpConverter, Dotnet.DotnetFrameworkConverter, DPAnalysis.DPAnalysisConverter, Gprof.GprofConverter, Lib.LibConverter, ManifestTool.ManifestToolConverter, ReflectionConverter, Reg.RegConverter, Reg.RegQueryConverter, ToBoolean, ToByte, ToCharacter, ToCodegen, ToDate, ToDouble, ToExec, ToFile, ToFilePattern, ToFloat, ToGuid, ToHost, ToInteger, ToIP, ToIterator, ToJar, ToJava, ToJavac, ToJavadoc, ToJdk, ToJre, ToJuggernet, ToJunction, ToList, ToLong, ToMap, ToObjectConverter, ToOS, ToPath, ToProcArch, ToRegex, ToSet, ToShell, ToShort, ToString, ToURI, ToVersion, VisualBasic.VbConverter, Xargs.XargsConverter

public interface Converter<T>

An interface implemented by all factory types that can create an object of one type from another object. The type parameter T represents the target type constraint. For example, a converter that always returns String instancces would be declared as a Converter<String>. The main terp bundle includes many converters for built-in types but you can create your own converters and register them with a TerpRegistrar.

In a terp expression, converters are a usually invoked via their registered aliases. The converter that returns a string is registered under two aliases, string and the more concise str, so you can write ^string(4), ^str(4), @string(4), or @str(4) to convert/cast the integer 4 to the string "4".

The semnatics of converters are interesting. Mostly, converters are expeceted to return a result value of null for an input value of null. This is not true for some converters that act as lookup services for system objects. The C++ compiler converters are a good example for this type of converter. The ^cpp() converter without any arguments, i.e. with a null argument, is expected to return the default C++ compiler for the host rather than null.

Most converters are expected to perform some meaningful conversion from an input string. What that conversion should be depends again on the particular character of the converter. For the C++ compiler converters, an input string is interpreted as a file path if it starts with a letter and as a version number if it starts with a digit. For an integer converter, the string will be parsed as a number.

For all but the most primitive converters, conversion from Map<String,Object> is also recommended. The map is interpreted as a contraints object where the named values represent constraints or member initializers. For example, the version converter supports an invocation such as

     ^version( { major:1, minor:4, patch:117 } )
 

to create the version number 1.4.117.

See the terp documentation for a full list of registered converter aliases.

Since:

1.0.0

Author:

Alexander R Krapf

Method Summary

T	fromObject(java.lang.Object obj, TerpContext ctx) Converts the given object into an object of the target type.

Method Detail

fromObject

T fromObject(java.lang.Object obj,
             TerpContext ctx)

Converts the given object into an object of the target type. Conversions can be implemented in any way that makes sense. Normally, converters will return null for null, but some converters may choose to interpret null as an indicator to return a default-initialized target object. An example of this type of conversion is the ShellExecutor. null simply indicates that no preference overrides of any kind have been provided.

Parameters:

obj - the source object.

ctx - the context in which the conversion takes place.

Returns:

an instance of the target type or null.