Syntax, Terminology

Terminology

A Format String is the template that defines how the data should be formatted.

Let's analyze the following Format String:

"The user {Name} was born in {Birthday:MMMM}, is {Age:000} {Age:year|years} old, and lives in {Address.City}."

Placeholders are defined by { and }, so this example has 5 placeholders: {Name}, {Birthday:MMMM}, {Age:000}, {Age:year|years}, and {Address.City}.

Literal text is the area in-between placeholders: The user , was born in, , is , , old, and lives in.

Each placeholder starts with a list of Selectors, such as Name and Birthday.
Selectors are separated by a period . or ?. for nullable, known as an Operator, such as Address.City.
Selectors determine what data will be used in the output.

If the placeholder contains a colon :, the remaining text is known as the Item Format.
For example, MMMM, 000, and year|years are Item Formats.
Note that there is a distinction between the entire Format String and the placeholder's Item Format. The Item Format determines how that data will be formatted. For example, MMMM tells the DateTime to output the name of the Month, like January. 000 tells an integer to use 3 digits.

General Template Syntax

Literal text { Selector(s) [, Align ] [: Formatter-Name(Options) ] [: Item-Format ] }

Parts within square braces [ and ] are optional.

Usage:

var data = new { Item = 9 };
Smart.Format("There are {Item,7:default:000} items", data);
// Outputs: "There are     009 items"

• Placeholder is everything between { and } curly braces. Each placeholder starts with a list of Selectors.
• Selector(s) is Item, which evaluates data.Item and gives us 9. Selectors can be concatenated with a dot . operator between them ("dot notation"), or ?. for nullable. Selectors determine what data will be used in the output.
• Align is 7, which causes the output to be padded with 4 extra FormatterSettings.AlignmentFillCharacters, which defaults to blank.
• Formatter Name is "default", which explicitly uses the DefaultFormatter. If omitted, a matching formatter flagged with CanAutoDetect=true will be chosen implicitly.
• Item Format is "000", which causes the number 9 to be padded with zeros. Note that there is a distinction between the entire Format String and the Placeholder's Item Format.
• Options are used as arguments to a format extension. options must be surrounded by parenthesis. See the example below.

Examples

It's as simple as:

using SmartFormat;
Smart.Format("{0} {1}", "Hello", "World") 
// outputs "Hello World"
Smart.Format("{h} {w}", new{ h = "Hello", w = "World" }) 
// outputs "Hello World"

// More than 1 selector
Smart.Format("{0.ToUpper} {1.ToLower}", "Hello", "World") 
// outputs "HELLO world"

Using options for the PluralLocalizationFormatter:

Smart.Format("{0:plural(en):zero|one|many}", 1);
// outputs "one" for the English language option

Output a List Element

Literal text { selector[n] }

or

Literal text { selector.n }

Example:

var data = new {Numbers = new List<int>{0,1,2,3}};
Smart.Format("{Numbers[1]}", data);
Smart.Format("{Numbers.1}", data);
// both output "1"

• placeholder is everything between { and } curly braces.
• selector is Number, which evaluates data.Number
• operators are either [ ] or . to access an item in the list, where 1 for "n" is the list index.

Nullable Notation

Nullable notation syntax is equivalent to C# Nullable<T>. Use it in the format string, whenever a selector may be null. By default null will output string.Empty.

Literal text { selector?.selector }

If any of the selectors is null, the placeholder is evaluated as null.

Literal text { selector?[n] }

If the selector is null, the placeholder is evaluated as null.

Examples:

public class Person
{ 	
    public string? Name {get; set;}
    public DateTime? Birthday {get; set;}
}

With nullable notation in the format string:

var data = new Person { Name = "Joe", Birthday = new DateTime(2000, 6, 30) };
Smart.Format("Name: {Name?.ToUpper} - Birthday: {Birthday?.Date:yyyy-MM-dd}", data);
// Outputs: "Name: JOE - Birthday: 2000-06-30"

data = new Person { Name = null, Birthday = null };
Smart.Format("Name: {Name?.ToUpper} - Birthday: {Birthday?.Date:yyyy-MM-dd}", data);
// Outputs: "Name:  - Birthday:"

// Or nicer by using the IsNullFormatter:
Smart.Format("Name: {Name?.ToUpper:isnull:n/a|{}} - Birthday: {Birthday?.Date:isnull:n/a|{:yyyy-MM-dd}}", data)
// Outputs: "Name: n/a - Birthday: n/a"

Without nullable notation in the format string:

Smart.Format("Name: {Name.ToUpper} - Birthday: {Birthday.Date:yyyy-MM-dd}", data);
// Throws a FormattingException
// Name: {Name.ToUpper} 
// ------------^