Formatter (SIRIUS kernel 12.0-rc9 API)

java.lang.Object
- sirius.kernel.nls.Formatter

```
public class Formatter
extends Object
```
An alternative for MessageFormat which generates strings by replacing named parameters in a given template.
A formatter is created for a given template string which contains named parameters like ${param1}. Using one of the set methods, values for the parameters can be supplied. Calling #format creates the output string.
Non string objects which are passed in as parameters, will be converted using NLS.toUserString(Object)
A formatter is neither thread safe nor intended for reuse. Instead a formatter is created, supplied with the relevant parameters by chaining calls to set and then discarded after getting the result string via format.
An example call might look like this:
```
 
         System.out.println(
              Formatter.create("Hello ${programmer}")
                       .set("programmer, "Obi Wan")
                       .format());
 
 
```
NLS uses this class by supplied translated patterns when calling NLS.fmtr(String).
See Also:

NLS.fmtr(String)

Constructor Summary

Constructors
Modifier Constructor and Description

protected Formatter()
Use the static factory methods create to obtain a new instance.

Constructors
Modifier	Constructor and Description
`protected`	`Formatter()` Use the static factory methods `create` to obtain a new instance.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static Formatter`	`create(String pattern)` Creates a new formatter with the given pattern.
`static Formatter`	`create(String pattern, String lang)` Creates a new formatter with the given pattern and language.
`static Formatter`	`createURLFormatter(String pattern)` Creates a new formatter with auto url encoding turned on.
`String`	`format()` Generates the formatted string.
`Formatter`	`set(Map<String,Object> ctx)` Sets the whole context as parameters in this formatter.
`Formatter`	`set(String property, Object value)` Adds the replacement value to use for the given `property`.
`Formatter`	`setDirect(String property, String value, boolean urlEncode)` Directly sets the given string value for the given property.
`Formatter`	`setUnencoded(String property, Object value)` Adds the replacement value to use for the given `property`, without url encoding the value.
`String`	`smartFormat()` Generates the formatted string using smart output formatting.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Formatter
```
protected Formatter()
```
    Use the static factory methods create to obtain a new instance.
- Method Detail
  - create
```
public static Formatter create(String pattern,
                               String lang)
```
    Creates a new formatter with the given pattern and language.
    The given language will be used when converting non-string parameters.
    
    Parameters:
    
    pattern - specifies the pattern to be used for creating the output
    
    lang - specifies the language used when converting non-string parameters.
    
    Returns:
    
    this for fluently calling set methods.
  - create
```
public static Formatter create(String pattern)
```
    Creates a new formatter with the given pattern.
    Uses the currently active language when converting non-string parameters.
    
    Parameters:
    
    pattern - specifies the pattern to be used for creating the output
    
    Returns:
    
    this for fluently calling set methods.
  - createURLFormatter
```
public static Formatter createURLFormatter(String pattern)
```
    Creates a new formatter with auto url encoding turned on.
    Any parameters passed to this formatter will be automatically url encoded.
    
    Parameters:
    
    pattern - specifies the pattern to be used for creating the output
    
    Returns:
    
    this for fluently calling set methods.
  - set
```
public Formatter set(String property,
                     Object value)
```
    Adds the replacement value to use for the given property.
    
    Parameters:
    
    property - the parameter in the template string which should be replaced
    
    value - the value which should be used as replacement
    
    Returns:
    
    this to permit fluent method chains
  - setUnencoded
```
public Formatter setUnencoded(String property,
                              Object value)
```
    Adds the replacement value to use for the given property, without url encoding the value.
    Formatters created by #createURLFormatter perform automatic url conversion for all parameters. Using this method however, disables url encoding for the given parameter and value.
    
    Parameters:
    
    property - the parameter in the template string which should be replaced
    
    value - the value which should be used as replacement
    
    Returns:
    
    this to permit fluent method chains
  - set
```
public Formatter set(Map<String,Object> ctx)
```
    Sets the whole context as parameters in this formatter.
    Calls #set for each entry in the given map.
    
    Parameters:
    
    ctx - a Map which provides a set of entries to replace.
    
    Returns:
    
    this to permit fluent method chains
  - setDirect
```
public Formatter setDirect(String property,
                           String value,
                           boolean urlEncode)
```
    Directly sets the given string value for the given property.
    Sets the given string as replacement value for the named parameter. The value will not be sent through NLS.toUserString(Object) and therefore not trimmed etc.
    
    Parameters:
    
    property - the parameter in the template string which should be replaced
    
    value - the value which should be used as replacement
    
    urlEncode - determines if url encoding should be applied. If the parameter is set to false, this method won't perform any url encoding, even if the formatter was created using #createURLFormatter
    
    Returns:
    
    this to permit fluent method chains
  - format
```
public String format()
```
    Generates the formatted string.
    Applies all supplied replacement values on detected parameters formatted like ${param}.
    
    Returns:
    
    the template string with all parameters replaced for which a value was supplied.
    
    Throws:
    
    IllegalArgumentException - if the pattern is malformed
  - smartFormat
```
public String smartFormat()
```
    Generates the formatted string using smart output formatting.
    Applies all supplied replacement values on detected parameters formatted like ${param}. Block can be formed using '[' and ']' a whole block is only output, if at least one replacement was not empty.
    Consider the pattern [${salutation} ][${firstname}] ${lastname}. This will create Mr. Foo Bar if all three parameters are filled, but Mr. Bar if the first name is missing or Foo Bar if the salutation is missing.
    
    Returns:
    
    the template string with all parameters replaced for which a value was supplied.
    
    Throws:
    
    IllegalArgumentException - if the pattern is malformed
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class Formatter

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Formatter

Method Detail

create

create

createURLFormatter

set

setUnencoded

set

setDirect

format

smartFormat

toString