ILineReader

There are following file formats are supported by the Lexical.Localization class library.

Format	Reader Class
.ini	IniLinesWriter
.json	JsonLinesReader
.xml	LocalizationXmlReader
.resx	LocalizationResxReader
.resources	ResourcesLineReader

ILineFileFormat instance can be acquired from LineReaderMap dictionary.

ILineFileFormat format = LineReaderMap.Default["ini"];

And from singleton instances.

ILineFileFormat format = IniLinesReader.Default;

Read IAsset

File can be read right away into an IAsset with .FileAsset() extension method.

IAsset asset = IniLinesReader.Default.FileAsset(
    filename: "localization.ini",
    throwIfNotFound: true);

IAsset asset = LineReaderMap.Default.FileAsset(
    filename: "localization.ini",
    throwIfNotFound: true);

From embedded resource with .EmbeddedAsset() method.

Assembly asm = typeof(LocalizationReader_Examples).Assembly;
IAsset asset = IniLinesReader.Default.EmbeddedAsset(
    assembly: asm,
    resourceName: "docs.localization.ini",
    throwIfNotFound: true);

asset = LineReaderMap.Default.EmbeddedAsset(
    assembly: asm,
    resourceName: "docs.localization.ini",
    throwIfNotFound: true);

And from a file provider with .FileProviderAsset().

IFileProvider fileProvider = new PhysicalFileProvider(Directory.GetCurrentDirectory());
IAsset asset = IniLinesReader.Default.FileProviderAsset(
    fileProvider: fileProvider,
    filepath: "localization.ini",
    throwIfNotFound: true);

asset = LineReaderMap.Default.FileProviderAsset(
    fileProvider: fileProvider,
    filepath: "localization.ini",
    throwIfNotFound: true);

Read IAssetSource

File can be read into an IAssetSource with .FileAssetSource() extension method. IAssetSource is a reference and a reader of asset. It is not read right away, but when the asset is built.

IAssetSource assetSource = IniLinesReader.Default.FileAssetSource(
        filename: "localization.ini",
        throwIfNotFound: true);
IAssetBuilder assetBuilder = new AssetBuilder().AddSource(assetSource);
IAsset asset = assetBuilder.Build();

IAssetSource assetSource = LineReaderMap.Default.FileAssetSource(
    filename: "localization.ini", 
    throwIfNotFound: true);

Reference to embedded resource source with .EmbeddedAssetSource().

Assembly asm = typeof(LocalizationReader_Examples).Assembly;
IAssetSource assetSource = IniLinesReader.Default.EmbeddedAssetSource(
        assembly: asm,
        resourceName: "docs.localization.ini",
        throwIfNotFound: true);

IAssetSource assetSource = LineReaderMap.Default.EmbeddedAssetSource(
        assembly: asm,
        resourceName: "docs.localization.ini",
        throwIfNotFound: true);

And file provider with .FileProviderAssetSource().

IFileProvider fileProvider = new PhysicalFileProvider(Directory.GetCurrentDirectory());
IAssetSource assetSource = IniLinesReader.Default.FileProviderAssetSource(
        fileProvider: fileProvider,
        filepath: "localization.ini",
        throwIfNotFound: true);

IAssetSource assetSource = LineReaderMap.Default.FileProviderAssetSource(
        fileProvider: fileProvider,
        filepath: "localization.ini",
        throwIfNotFound: true);

Read File

Different file formats have different intrinsic formats.

• String list formats are IEnumerable<ILine>.
• Context dependent string list formats are IEnumerable<KeyValuePair<string, IString>>.
• Structural tree formats are ILineTree.

Localization file can be read right away into key lines with .ReadLines().

IEnumerable<ILine> key_lines = LineReaderMap.Default.ReadLines(
    filename: "localization.ini", 
    throwIfNotFound: true);

Into string lines with .ReadUnformedLines().

IEnumerable<KeyValuePair<string, IString>> string_lines = LineReaderMap.Default.ReadUnformedLines(
    filename: "localization.ini", 
    lineFormat: LineFormat.Parameters,
    throwIfNotFound: true);

And into a tree .ReadLineTree().

ILineTree tree = LineReaderMap.Default.ReadLineTree(
    filename: "localization.ini", 
    throwIfNotFound: true);

File Reader

A file reader can be constructed with respective .FileReader(). File reader reads the refered file when .GetEnumerator() is called, and will re-read the file again every time.

IEnumerable<ILine> key_lines_reader = 
    LineReaderMap.Default.FileReader(
        filename: "localization.ini", 
        throwIfNotFound: true);

.FileReaderAsUnformedLines() creates a reader that returns string lines.

IEnumerable<KeyValuePair<string, IString>> string_lines_reader = 
    LineReaderMap.Default.FileReaderAsUnformedLines(
        filename: "localization.ini",
        lineFormat: LineFormat.Parameters,
        throwIfNotFound: true);

And .FileReaderAsLineTree() a tree reader.

IEnumerable<ILineTree> tree_reader = 
    LineReaderMap.Default.FileReaderAsLineTree(
        filename: "localization.ini", 
        throwIfNotFound: true);

Embedded Reader

Embedded resource reader is created with .EmbeddedReader().

Assembly asm = typeof(LocalizationReader_Examples).Assembly;
IEnumerable<ILine> key_lines_reader = 
    LineReaderMap.Default.EmbeddedReader(
        assembly: asm, 
        resourceName: "docs.localization.ini", 
        throwIfNotFound: true);

.EmbeddedReaderAsUnformedLines() creates embedded reader of string lines.

IEnumerable<KeyValuePair<string, IString>> string_lines_reader = 
    LineReaderMap.Default.EmbeddedReaderAsUnformedLines(
        assembly: asm, 
        resourceName: "docs.localization.ini", 
        lineFormat: LineFormat.Parameters,
        throwIfNotFound: true);

And .EmbeddedReaderAsLineTree() reader of trees

IEnumerable<ILineTree> tree_reader = 
    LineReaderMap.Default.EmbeddedReaderAsLineTree(
        assembly: asm, 
        resourceName: "docs.localization.ini", 
        throwIfNotFound: true);

IFileProvider Reader

File provider reader is created with .FileProviderReader().

IFileProvider fileProvider = new PhysicalFileProvider(Directory.GetCurrentDirectory());
IEnumerable<ILine> key_lines_reader = 
    LineReaderMap.Default.FileProviderReader(
        fileProvider: fileProvider, 
        filepath: "localization.ini", 
        throwIfNotFound: true);

.FileProviderReaderAsUnformedLines() creates string lines reader

IFileProvider fileProvider = new PhysicalFileProvider(Directory.GetCurrentDirectory());
IEnumerable<KeyValuePair<string, IString>> string_lines_reader = 
    LineReaderMap.Default.FileProviderReaderAsUnformedLines(
        fileProvider: fileProvider, 
        filepath: "localization.ini", 
        throwIfNotFound: true);

And .FileProviderReaderAsLineTree() tree reader.

IFileProvider fileProvider = new PhysicalFileProvider(Directory.GetCurrentDirectory());
IEnumerable<ILineTree> tree_reader = 
    LineReaderMap.Default.FileProviderReaderAsLineTree(
        fileProvider: fileProvider, 
        filepath: "localization.ini", 
        throwIfNotFound: true);

Read Stream

Text files can be read from Stream into key lines.

using (Stream s = new FileStream("localization.ini", FileMode.Open, FileAccess.Read))
{
    IEnumerable<ILine> key_lines = IniLinesReader.Default.ReadLines(s);
}

Into string lines.

using (Stream s = new FileStream("localization.ini", FileMode.Open, FileAccess.Read))
{
    IEnumerable<KeyValuePair<string, IString>> string_lines = IniLinesReader.Default.ReadUnformedLines(
        stream: s,
        lineFormat: LineFormat.Parameters);
}

And into a tree.

using (Stream s = new FileStream("localization.ini", FileMode.Open, FileAccess.Read))
{
    ILineTree tree = IniLinesReader.Default.ReadLineTree(s);
}

Read TextReader

Text files can be read from TextReader into key lines.

string text = "Culture:en:Type:MyController:Key:Hello = Hello World!\n";
using (TextReader tr = new StringReader(text))
{
    IEnumerable<ILine> key_lines = IniLinesReader.Default.ReadLines(tr);
}

Into string lines.

using (TextReader tr = new StringReader(text))
{
    IEnumerable<KeyValuePair<string, IString>> string_lines = IniLinesReader.Default.ReadUnformedLines(
        srcText: tr,
        lineFormat: LineFormat.Parameters);
}

And into tree.

using (TextReader tr = new StringReader(text))
{
    ILineTree tree = IniLinesReader.Default.ReadLineTree(tr);
}

Read String

And from String into key lines.

string text = "Culture:en:Type:MyController:Key:Hello = Hello World!\n";
IEnumerable<ILine> key_lines = 
    IniLinesReader.Default.ReadString(
        srcText: text);

Into string lines.

IEnumerable<KeyValuePair<string, IString>> string_lines = 
    IniLinesReader.Default.ReadStringAsUnformedLines(
        srcText: text,
        lineFormat: LineFormat.Parameters);

And into a tree.

ILineTree tree = 
    IniLinesReader.Default.ReadStringAsLineTree(
        srcText: text);

Implementing

ILineReader is the root interface for localization reader classes.

/// <summary>
/// Signals that file format can read localization files.
/// 
/// For reading capability, must implement one of:
/// <list type="Bullet">
/// <item><see cref="ILineStreamReader"/></item>
/// <item><see cref="ILineTreeStreamReader"/></item>
/// <item><see cref="ILineTextReader"/></item>
/// <item><see cref="ILineTreeTextReader"/></item>
/// <item><see cref="ILineStringTextReader"/></item>
/// <item><see cref="ILineStringStreamReader"/></item>
/// </list>
/// </summary>
public interface ILineReader : ILineFileFormat { }

/// <summary>
/// Reader that can read lines from a <see cref="Stream"/>.
/// </summary>
public interface ILineStreamReader : ILineReader
{
    /// <summary>
    /// Read <paramref name="stream"/> into lines.
    /// </summary>
    /// <param name="stream"></param>
    /// <param name="lineFormat">(optional) possibly needed for string and line conversions. Used also for choosing whether to instantiate parameter into hint or key</param>
    /// <returns>the read lines</returns>
    /// <exception cref="IOException"></exception>
    IEnumerable<ILine> ReadLines(Stream stream, ILineFormat lineFormat = default);
}

/// <summary>
/// Reader that can read tree format from a <see cref="Stream"/>.
/// </summary>
public interface ILineTreeStreamReader : ILineReader
{
    /// <summary>
    /// Read <paramref name="stream"/> into tree structure.
    /// </summary>
    /// <param name="stream"></param>
    /// <param name="lineFormat">(optional) possibly needed for string and line conversions. Used also for choosing whether to instantiate parameter into hint or key</param>
    /// <returns>lines in tree structure</returns>
    /// <exception cref="IOException"></exception>
    ILineTree ReadLineTree(Stream stream, ILineFormat lineFormat = default);
}

/// <summary>
/// Reader that can read localization lines from a <see cref="TextReader"/>.
/// </summary>
public interface ILineTextReader : ILineReader
{
    /// <summary>
    /// Read <paramref name="text"/> into tree structure.
    /// </summary>
    /// <param name="text"></param>
    /// <param name="lineFormat">(optional) possibly needed for string and line conversions. Used also for choosing whether to instantiate parameter into hint or key</param>
    /// <returns>the read lines</returns>
    /// <exception cref="IOException"></exception>
    IEnumerable<ILine> ReadLines(TextReader text, ILineFormat lineFormat = default);
}

/// <summary>
/// Reader that can read localization lines from a <see cref="TextReader"/>.
/// </summary>
public interface ILineTreeTextReader : ILineReader
{
    /// <summary>
    /// Read <paramref name="text"/> into lines.
    /// </summary>
    /// <param name="text"></param>
    /// <param name="lineFormat">(optional) possibly needed for string and line conversions. Used also for choosing whether to instantiate parameter into hint or key</param>
    /// <returns>lines in tree structure</returns>
    /// <exception cref="IOException"></exception>
    ILineTree ReadLineTree(TextReader text, ILineFormat lineFormat = default);
}

/// <summary>
/// Reader that can read string key-values from a <see cref="TextReader"/>.
/// </summary>
public interface ILineStringTextReader : ILineReader
{
    /// <summary>
    /// Read <paramref name="text"/> into lines.
    /// </summary>
    /// <param name="text"></param>
    /// <param name="lineFormat">(optional) possibly needed for string and line conversions. Used also for choosing whether to instantiate parameter into hint or key</param>
    /// <returns>the read string key-values</returns>
    /// <exception cref="IOException"></exception>
    IEnumerable<KeyValuePair<string, IString>> ReadStringLines(TextReader text, ILineFormat lineFormat = default);
}

/// <summary>
/// Reader that can read string key-values from a <see cref="Stream"/>.
/// </summary>
public interface ILineStringStreamReader : ILineReader
{
    /// <summary>
    /// Read <paramref name="stream"/> into lines.
    /// </summary>
    /// <param name="stream"></param>
    /// <param name="lineFormat">(optional) possibly needed for string and line conversions. Used also for choosing whether to instantiate parameter into hint or key</param>
    /// <returns>the read string key-values</returns>
    /// <exception cref="IOException"></exception>
    IEnumerable<KeyValuePair<string, IString>> ReadStringLines(Stream stream, ILineFormat lineFormat = default);
}

A class that implements ILineReader must to implement one of its sub-interfaces. A one that best suits the underlying format.

class ExtFileFormatReader : ILineTextReader
{
    public string Extension => "ext";

    public IEnumerable<ILine> ReadLines(
        TextReader text, 
        ILineFormat lineFormat = null)
    {
        yield return LineAppender.Default.Section("MyClass").Key("HelloWorld").Culture("en").Format("Hello World!");
    }
}

Reader can be added to LineReaderMap.

// Create writer
ILineReader format = new ExtFileFormatReader();

// Clone formats
LineFileFormatMap formats = LineReaderMap.Default.Clone();
// Add to clone
formats.Add(format);

// Or if in deploying application project, format can be added to the global singleton
(LineReaderMap.Default as IDictionary<string, ILineFileFormat>).Add(format);