IStringFormat

IStringFormat is interface for printers and parsers of string formats.

/// <summary>
/// String format of string value. 
/// 
/// For example C# format that uses numbered arguments "{0[,parameters]}" that are written inside braces and have
/// parameters after number.
/// 
/// It has following sub-interfaces:
/// <list type="bullet">
/// <item><see cref="IStringFormatParser"/></item>
/// </list>
/// </summary>
public interface IStringFormat
{
    /// <summary>
    /// Name of the format name, e.g. "csharp", "c", or "lexical"
    /// </summary>
    string Name { get; }
}

/// <summary>
/// Parses arguments from format strings. Handles escaping.
/// 
/// For example "You received {caridnal:0} coin(s)." is a format string
/// that parsed into argument and non-argument sections.
/// </summary>
public interface IStringFormatParser : IStringFormat
{
    /// <summary>
    /// Parse format string into an <see cref="IString"/>.
    /// 
    /// If parse fails this method should return an instance where state is <see cref="LineStatus.StringFormatErrorMalformed"/>.
    /// If parse succeeds, the returned instance has state <see cref="LineStatus.StringFormatOkString"/> or some other format state.
    /// If <paramref name="str"/> is null then stat is <see cref="LineStatus.StringFormatFailedNull"/>.
    /// </summary>
    /// <param name="str"></param>
    /// <returns>format string</returns>
    IString Parse(string str);
}

/// <summary>
/// Prints <see cref="IString"/> into the format.
/// </summary>
public interface IStringFormatPrinter : IStringFormat
{
    /// <summary>
    /// Print <paramref name="str"/> into string that represents the notation of this <see cref="IStringFormat"/>.
    /// 
    /// If print fails status is:
    /// <list type="bullet">
    ///     <item><see cref="LineStatus.StringFormatErrorPrintNoCapabilityPluralCategory"/></item>
    ///     <item><see cref="LineStatus.StringFormatErrorPrintNoCapabilityPlaceholder"/></item>
    ///     <item><see cref="LineStatus.StringFormatErrorPrintUnsupportedExpression"/></item>
    ///     <item><see cref="LineStatus.StringFormatFailed"/></item>
    /// </list>
    /// 
    /// If formulated ok, status is <see cref="LineStatus.StringFormatOkString"/>.
    /// </summary>
    /// <param name="str"></param>
    /// <returns>format string</returns>
    LineString Print(IString str);
}

Implementations

Class	Description	Extension Method
CSharpFormat	Uses C# String.Format() notation.	ILine.Format(string)
TextFormat	Uses plain text notation.	ILine.String(string)

CSharpFormat

CSharpFormat.Default represents a string format that is similar to String.Format.

CSharpFormat.Default.Parse(string) parses placeholders from a string.

IStringFormat stringFormat = CSharpFormat.Default;
IString str = stringFormat.Parse("Hello, {0}.");

Extension method .Format(string) appends CSharpFormat string to ILine as "String" parameter.

ILine line = LineRoot.Global.Key("").Format("Hello, {0}.");

CSharpFormat uses following format. "Text {[pluralCategory:]argumentIndex:[,alignment][:format]} text".

It uses the following rules:

1. Placeholders are inside braces and contain numbered arguments: "Hello {0} and {1}"
2. Braces are escaped. "Control characters are \{\}."
3. "format"-specifier is after : colon. "Hex value {0:X4}."
4. PluralCategory is before : colon.

TextFormat

TextFormat.Default is a string format that contains plain text without placeholders. It doesn't need or use escaping.

IStringFormat stringFormat = TextFormat.Default;
IString str = stringFormat.Parse("{in braces}");

Extension method .Text(string) appends TextFormat string to ILine as "String" parameter.

ILine line = LineRoot.Global.Key("").Text("{in braces}");

Escaping

Two IStringFormats can be used for escaping and unescaping.

// Convert unescaped string "{not placeholder}" to IString
IString ss = TextFormat.Default.Parse("{not placeholder}");
// Escape with CSharpFormat to "\{not placeholder\}"
string str = CSharpFormat.Default.Print(ss);
// Convert escaped string back to IString
IString cs = CSharpFormat.Default.Parse(str);
// Unescape IString back to "{not placeholder}"
string tt = TextFormat.Default.Print(cs);

Resolving string

String is parsed into IString that contains placeholders and texts.

IStringFormat stringFormat = CSharpFormat.Default;
IString str = stringFormat.Parse("Hello, {0}.");

.String(string) extension method appends IString to ILine.

ILine line = LineRoot.Global.Key("Hello").String(str);

An argument is applied to placeholder {0} and resolved string is returned in a LineString record.

LineString lineString = line.Value("Corellia Melody").ResolveString();

If it resolved to an OK or non-Failed result, then the .Value can be used.

if (!lineString.Failed) Console.WriteLine(lineString.Value);