• Lexical
Show / Hide Table of Contents
  • Lexical.FileSystem
    • Introduction
    • Abstractions
      • IFileSystem
        • IFileSystem
        • IFileSystemBrowse
        • IFileSystemCreateDirectory
        • IFileSystemDelete
        • IFileSystemFileAttribute
        • IFileSystemMount
        • IFileSystemMove
        • IFileSystemObserve
        • IFileSystemOpen
      • IEvent
      • IEntry
      • IOption
      • IToken
    • FileSystem
    • VirtualFileSystem
    • MemoryFileSystem
    • EmbeddedFileSystem
    • HttpFileSystem
    • Decoration
    • IFileProvider
    • Utility
      • DisposeList
      • FileScanner
      • VisitTree
      • File Operation
  • Lexical.FileProvider
    • Introduction
    • Package
    • Package.Abstractions
    • Root
    • Zip
    • Dll
    • SharpCompress
    • SharpZipLib
    • FileScanner
    • Utils
  • Lexical.Localization
    • Introduction
    • Tutorial
    • Asset
      • IAsset
      • IStringAsset
    • Line
      • ILine
      • ILineFactory
      • ILineRoot
      • ILineFormat
      • ILineLogger
      • LineComparer
    • File
      • ILineReader
      • ILineWriter
      • Ini
      • Json
      • Xml
      • Resx
      • Resources
    • Miscellaneous
      • Plurality
      • ICulturePolicy
      • IStringFormat
      • Dependency Injection
    • Practices
      • Class Library
      • Class Library DI
      • Class Library DI opt.
  • Lexical.Utilities
    • Introduction
    • UnicodeString
    • FileScanner
    • Permutation
    • Tuples
    • StructList

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);
Back to top Copyright © 2015-2020 Toni Kalajainen