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:
- Placeholders are inside braces and contain numbered arguments: "Hello {0} and {1}"
- Braces are escaped. "Control characters are \{\}."
- "format"-specifier is after : colon. "Hex value {0:X4}."
- 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);