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);