SmartFormat.NET String Formatting Framework

string.Format has very limited functionality; therefore, the SmartFormat.NET framework is needed to achieve rich string interpolation features. It can format various data sources into strings using a minimal and intuitive syntax similar to that of strings. All formatting occurs at runtime. SmartFormat uses extensions to provide named placeholders, localization, plurals, gender combination, as well as list and time formatting. Nesting formatting extension plugins is also supported.

Framework links:

https://github.com/axuno/SmartFormat
https://github.com/axuno/SmartFormat/wiki

Basic Usage

There are two common usages of SmartFormat: one is through object property interpolation, and the other is through dictionary interpolation.

When interpolating through an object, string template placeholders use {Property or Field Name}.

    var data = new { Library = "SmartFormat" };
    var str = Smart.Format("Composed with {Library}.", data);
    Console.WriteLine(str);

// Output: Composed with SmartFormat.

When using dictionary interpolation, the Key should match the placeholder name.

    var data = new Dictionary<string, string> { { "Library", "SmartFormat" } };
    var str = Smart.Format("Composed with {Library}.", data);
    Console.WriteLine(str);

In development, there are often many customization requirements, so we can define custom formatters.

    var sf = Smart.CreateDefaultSmartFormat();
    var data = new Dictionary<string, string> { { "Library", "SmartFormat" } };
    var str = sf.Format("Composed with {Library}.", data);
    Console.WriteLine(str);

For example, if the placeholder used does not exist in the object or dictionary, it will normally throw an error.

    var data = new Dictionary<string, string> { { "Library", "SmartFormat" } };
    var str = sf.Format("Composed with {Library1}.", data);

The handling method can be defined through the FormatErrorAction and ParseErrorAction enumerations.

public enum FormatErrorAction
{
    // Default throws an exception
    ThrowError,
    // No error thrown, outputs error message at placeholder position
    OutputErrorInResult,
    // Ignore, unassociated placeholders will print blank values
    Ignore,
    // Placeholder position remains the same.
    MaintainTokens
}

For example:

    var sf = Smart.CreateDefaultSmartFormat();
    sf.Settings.Formatter.ErrorAction = FormatErrorAction.MaintainTokens;
    sf.Settings.Parser.ErrorAction = ParseErrorAction.Ignore;

    var data = new Dictionary<string, string> { { "Library", "SmartFormat" } };
    var str = sf.Format("Composed with {Library1}.", data);
    Console.WriteLine(str);
    // Outputs: Composed with {Library1}.

    var sf = Smart.CreateDefaultSmartFormat();
    sf.Settings.Formatter.ErrorAction = FormatErrorAction.OutputErrorInResult;
    sf.Settings.Parser.ErrorAction = ParseErrorAction.Ignore;

    var data = new Dictionary<string, string> { { "Library", "SmartFormat" } };
    var str = sf.Format("Composed with {Library1}.", data);
    Console.WriteLine(str);
    // Outputs: Composed with Error parsing format string: No source extension could handle the selector named "Library1" at 15
    Composed with {Library1}.
    ---------------^.
}

Handling Special Characters { and }

By default, SmartFormat recognizes { and } as placeholders, so we cannot print { and } symbols through escaping or other methods. That is, when we want to print these two symbols instead of them being recognized as placeholders, the following methods are invalid:

"{ } is pig."
"{\0{ is nice."

To directly print these two symbols in a string, there are two methods.

One is to customize the placeholder mapping corresponding to the symbols.

    var sf = Smart.CreateDefaultSmartFormat();
    sf.Settings.Formatter.ErrorAction = FormatErrorAction.MaintainTokens;
    var dict1 = new Dictionary<string, string> { { "LF", "{" }, { "RF", "}" } };
    var dict2 = new Dictionary<string, string> { { "dict2key", "dict2 Value" } };

    var value = sf.Format("{LF} {dict2key} {RF}", (dict1, dict2));
    value.Dump();
    
    // Outputs: { dict2 Value }

The downside is that it is cumbersome and less readable.

The other is to set compatibility SmartSettings.StringFormatCompatibility = true.

    var sf = Smart.CreateDefaultSmartFormat();
    sf.Settings.Formatter.ErrorAction = FormatErrorAction.MaintainTokens;
    sf.Settings.Parser.ErrorAction = ParseErrorAction.ThrowError;
    sf.Settings.StringFormatCompatibility = true;
    
    var dict2 = new Dictionary<string, string> { { "dict2key", "dict2 Value" } };
    var value = sf.Format(" {{dict2key}} ", (dict2));
    value.Dump();
    // Outputs: {dict2key} 

    var value = sf.Format("{{ {dict2key} }}", (dict2));
    // Outputs: { dict2 Value }

SmartFormat also supports various powerful features such as localization for currency, time, and formatting expressions.