Class LrcParser

Namespace

ModernLrc

Assembly

ModernLrc.dll

Entry-point for parsing LRC text. All overloads converge on the canonical Parse(ReadOnlySpan<char>, LrcParseOptions?).

public static class LrcParser

Inheritance

object

LrcParser

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

using ModernLrc;

var result = LrcParser.Parse("[ti:Demo]\n[00:01.00]hello\n");
Console.WriteLine(result.Document.Metadata.Title);   // "Demo"
Console.WriteLine(result.Document.Lines.Count);      // 1
foreach (var d in result.Diagnostics)
    Console.WriteLine($"{d.Code} {d.Severity} L{d.Line}:C{d.Column} — {d.Message}");

Remarks

The parser is tolerant by default — every recoverable issue is recorded as a LrcDiagnostic on Diagnostics and parsing continues. Set Strictness to Strict to throw LrcParseException on the first Error-severity diagnostic instead.

Byte / stream / file overloads run a BOM → caller-encoding → UTF-8 → fallback pipeline before scanning. See the articles/encoding-pipeline guide.

Methods

Parse(byte[], LrcParseOptions?)

Parse a byte array (encoding pipeline applied — see the Parse(ReadOnlySpan<byte>, LrcParseOptions?) overload for the order of operations).

public static LrcParseResult Parse(byte[] input, LrcParseOptions? options = null)

Parameters

input byte[]

Source bytes.

options LrcParseOptions

Parser options.

Returns

LrcParseResult

The parsed result.

Exceptions

ArgumentNullException

input is null.

LrcParseException

Encoding could not be detected, or strict-mode error.

Parse(Stream, LrcParseOptions?)

Parse a stream synchronously. Reads all bytes into memory first; for large inputs prefer ParseAsync(Stream, LrcParseOptions?, CancellationToken).

public static LrcParseResult Parse(Stream stream, LrcParseOptions? options = null)

Parameters

stream Stream

Source stream; must be readable.

options LrcParseOptions

Parser options.

Returns

LrcParseResult

The parsed result.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

stream is not readable.

LrcParseException

Encoding could not be detected, or strict-mode error.

Parse(TextReader, LrcParseOptions?)

Parse a TextReader by reading it to end first. For large inputs prefer ParseAsync(TextReader, LrcParseOptions?, CancellationToken).

public static LrcParseResult Parse(TextReader reader, LrcParseOptions? options = null)

Parameters

reader TextReader

Source reader; consumed to end.

options LrcParseOptions

Parser options.

Returns

LrcParseResult

The parsed result.

Exceptions

ArgumentNullException

reader is null.

LrcParseException

Strict mode encountered an Error-severity diagnostic.

Parse(ReadOnlyMemory<char>, LrcParseOptions?)

Parse a ReadOnlyMemory<T> of chars.

public static LrcParseResult Parse(ReadOnlyMemory<char> input, LrcParseOptions? options = null)

Parameters

input ReadOnlyMemory<char>

Source memory region.

options LrcParseOptions

Parser options.

Returns

LrcParseResult

The parsed result.

Exceptions

LrcParseException

Strict mode encountered an Error-severity diagnostic.

Parse(ReadOnlySpan<byte>, LrcParseOptions?)

Parse a span of bytes through the encoding pipeline: BOM (UTF-8 / UTF-16 LE / UTF-16 BE) → caller-supplied Encoding → UTF-8 validation → FallbackEncoding.

public static LrcParseResult Parse(ReadOnlySpan<byte> input, LrcParseOptions? options = null)

Parameters

input ReadOnlySpan<byte>

Source bytes.

options LrcParseOptions

Parser options.

Returns

LrcParseResult

The parsed result.

Exceptions

LrcParseException

Encoding could not be detected (no BOM, invalid UTF-8, and FallbackEncoding is null), or strict-mode error.

Parse(ReadOnlySpan<char>, LrcParseOptions?)

Canonical static parse. All paths converge here.

public static LrcParseResult Parse(ReadOnlySpan<char> input, LrcParseOptions? options = null)

Parameters

input ReadOnlySpan<char>

Source text. Whitespace and line endings are preserved verbatim in Text.

options LrcParseOptions

Parser options. Defaults to Default (Tolerant strictness, 256-diagnostic cap).

Returns

LrcParseResult

The parsed result, including any collected diagnostics.

Exceptions

LrcParseException

Strict mode encountered an Error-severity diagnostic.

Parse(string, LrcParseOptions?)

Parse a string. Equivalent to Parse(input.AsSpan(), options).

public static LrcParseResult Parse(string input, LrcParseOptions? options = null)

Parameters

input string

Source text.

options LrcParseOptions

Parser options. Defaults to Default.

Returns

LrcParseResult

The parsed result.

Exceptions

ArgumentNullException

input is null.

LrcParseException

Strict mode encountered an Error-severity diagnostic.

ParseAsync(Stream, LrcParseOptions?, CancellationToken)

Async parse from a Stream. Reads all bytes into memory then applies the encoding pipeline (BOM → caller override → UTF-8 → fallback).

public static ValueTask<LrcParseResult> ParseAsync(Stream stream, LrcParseOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream

Source stream; must be readable.

options LrcParseOptions

Parser options.

cancellationToken CancellationToken

Honored at start and during stream copy.

Returns

ValueTask<LrcParseResult>

The parsed result.

Examples

using var fs = File.OpenRead("song.lrc");
var result = await LrcParser.ParseAsync(fs, cancellationToken: ct);

Exceptions

ArgumentNullException

stream is null.

ArgumentException

stream is not readable.

OperationCanceledException

Cancellation was requested.

LrcParseException

Encoding could not be detected, or strict-mode error.

ParseAsync(TextReader, LrcParseOptions?, CancellationToken)

Async parse from a TextReader.

public static ValueTask<LrcParseResult> ParseAsync(TextReader reader, LrcParseOptions? options = null, CancellationToken cancellationToken = default)

Parameters

reader TextReader

Source reader; consumed to end.

options LrcParseOptions

Parser options.

cancellationToken CancellationToken

Honored before reading and respected by ReadToEndAsync(CancellationToken).

Returns

ValueTask<LrcParseResult>

The parsed result.

Exceptions

ArgumentNullException

reader is null.

OperationCanceledException

Cancellation was requested.

LrcParseException

Strict mode encountered an Error-severity diagnostic.

ParseFile(string, LrcParseOptions?)

Parse a file at path synchronously. Annotates strict-mode failures with FilePath; IO exceptions propagate raw.

public static LrcParseResult ParseFile(string path, LrcParseOptions? options = null)

Parameters

path string

File path. Must be non-empty.

options LrcParseOptions

Parser options.

Returns

LrcParseResult

The parsed result.

Examples

var result = LrcParser.ParseFile("song.lrc");
if (result.HasErrors)
    foreach (var d in result.Diagnostics.Where(d => d.Severity == LrcDiagnosticSeverity.Error))
        Console.WriteLine(d.Message);

Exceptions

ArgumentException

path is null, empty, or whitespace.

FileNotFoundException

The file does not exist.

IOException

The file could not be read.

LrcParseException

Encoding could not be detected, or strict-mode error.

ParseFileAsync(string, LrcParseOptions?, CancellationToken)

Async parse from a file at path. Annotates strict-mode failures with FilePath; IO and cancellation exceptions propagate raw.

public static ValueTask<LrcParseResult> ParseFileAsync(string path, LrcParseOptions? options = null, CancellationToken cancellationToken = default)

Parameters

path string

File path. Must be non-empty.

options LrcParseOptions

Parser options.

cancellationToken CancellationToken

Honored before opening and during stream copy.

Returns

ValueTask<LrcParseResult>

The parsed result.

Exceptions

ArgumentException

path is null, empty, or whitespace.

FileNotFoundException

The file does not exist.

IOException

The file could not be read.

OperationCanceledException

Cancellation was requested.

LrcParseException

Encoding could not be detected, or strict-mode error.

TryParse(ReadOnlySpan<char>, out LrcDocument?)

BCL convention with span input.

public static bool TryParse(ReadOnlySpan<char> input, out LrcDocument? document)

Parameters

input ReadOnlySpan<char>

Source span.

document LrcDocument

Parsed document on success; null on failure.

Returns

bool

true when parsing produced a usable document with no Error diagnostics.

TryParse(ReadOnlySpan<char>, out LrcDocument?, out ImmutableArray<LrcDiagnostic>)

BCL convention with span input plus diagnostic capture.

public static bool TryParse(ReadOnlySpan<char> input, out LrcDocument? document, out ImmutableArray<LrcDiagnostic> diagnostics)

Parameters

input ReadOnlySpan<char>

Source span.

document LrcDocument

Parsed document on success; null on failure.

diagnostics ImmutableArray<LrcDiagnostic>

All diagnostics emitted during the attempt, regardless of outcome.

Returns

bool

true when parsing produced a usable document with no Error diagnostics.

TryParse(string, out LrcDocument?)

BCL TryParse convention. Returns false if any Error-severity diagnostic was emitted; diagnostics are otherwise discarded.

public static bool TryParse(string input, out LrcDocument? document)

Parameters

input string

Source text.

document LrcDocument

Parsed document on success; null on failure.

Returns

bool

true when parsing produced a usable document with no Error diagnostics.

Examples

if (LrcParser.TryParse("[00:01.00]hi", out var doc))
    Console.WriteLine(doc.Lines.Count);

Exceptions

ArgumentNullException

input is null.