Table of Contents

Parser policies

Real-world CSV, .env, and INI files break their specs constantly. Each reader therefore couples a strict default with explicit, opt-in leniency knobs on its options struct.

Common diagnostic surface

Every reader throws its format's *FormatException (DelimitedFormatException, DotEnvFormatException, IniFormatException) carrying the 1-based line number and byte offset at which the problem was detected. A Delimited error about a whole record, a field count that differs from the header's or a header that repeats a name, carries the line and offset at which that record starts, and DelimitedSerializer.DeserializeAsyncEnumerableAsync counts both from the start of the stream, whichever read held the error. Serializer binding failures throw the format's *SerializationException instead.

Delimited

DelimitedReaderOptions carries the RFC 4180 dialect knobs:

Knob Values Default
FieldCountBehavior Strict (every record matches the header's field count) / Ragged Strict
MalformedRecordBehavior Throw / SkipRecord (skip the whole malformed record and continue with the next line) Throw
DuplicateHeaderBehavior Throw / TakeFirst / TakeLast (the first or last column with a repeated name keeps it, and the others are read under an empty name) Throw
Delimiter, Quote an ASCII character other than CR and LF; the two must differ , / "
NoHeader treat the first record as data (records become positional arrays) header mode
TrimFields trim spaces and tabs around each field: an unquoted field's value is trimmed, and the spaces and tabs around a quoted field's quotes are skipped, so the field is still read as quoted and its quoted text is kept whole; other white space, such as U+00A0 or U+3000, is kept off
AllowComments, CommentChar skip comment lines; the character follows the Delimiter rule and must differ from Delimiter and Quote, even with comments off off / #

The reader matches the delimiter, quote, and comment characters as single bytes of the UTF-8 input, and the writer emits its delimiter and quote the same way. Each must therefore be an ASCII character other than a carriage return or a line feed, and no two may be the same character; a character outside ASCII would otherwise be cut to one byte and matched inside other characters. The Utf8DelimitedReader and Utf8DelimitedWriter constructors, and the DelimitedSerializer methods that create them, throw ArgumentException for options, naming the offending option, when the characters break these rules.

Strict field counts are measured against the header row, so they apply in header mode; positional mode accepts any shape unless you enforce one yourself.

Under Ragged, each field beyond the header's is named by its zero-based column index, so the fourth field under a three-column header is named 3; such a name can coincide with a header's own name.

Where the reader is always strict: an unterminated quoted field throws, and characters after a closing quote are a structural error (subject to MalformedRecordBehavior). After a closing quote only the delimiter, a line break or the end of the input may follow, after spaces and tabs under TrimFields; anything else makes the record malformed. Throw reports the line and offset of the first offending byte, and SkipRecord skips the record, the rest of that line included, and continues with the next line. A record whose field count breaks the Strict policy is malformed too: Throw reports where it starts, and SkipRecord skips it.

LF, CRLF and a lone CR each end a line. A blank line is skipped rather than read as a record of one empty field, which RFC 4180's grammar would make it, so the writer writes such a record as "".

The reader skips a UTF-8 byte-order mark at the start of its input, and DelimitedSerializer.DeserializeAsyncEnumerableAsync skips one only at the start of the stream, however its reads fall; a U+FEFF anywhere else is field content.

DotEnv

The DotEnv dialect follows the mainstream dotenv implementations:

  • export KEY=value binds as KEY; the prefix is shell syntax (preserved by the mutable DOM, surfaced via Utf8DotEnvReader.CurrentIsExport).
  • Double-quoted values resolve escape sequences and may span lines; single-quoted values are literal; unquoted values end at an inline # comment.
  • In a double-quoted value, \\, \', \", \a, \b, \f, \n, \r, \t, \v and \$ are resolved, and a backslash before a line break continues the value; any other escape keeps its backslash, and octal escapes are not supported.
  • Whitespace is any Unicode whitespace character other than CR and LF: it may precede a key or a comment, follow export, and surround =, and it is trimmed from both ends of an unquoted value.
  • After a closing quote, only whitespace and a # comment may follow on the line; any other text is malformed input.
  • An empty value is a real value, distinct from an absent key.
  • DotEnvReaderOptions can disable the export prefix, inline comments, or comment tokens (DisallowExportPrefix, DisallowInlineComments, SkipComments).

INI

The Utf8IniReader dialect is deliberately conservative (the configparser-compatible reading):

  • = is the only key/value delimiter; a : line is malformed.
  • The spaces and tabs around a key and around a value are trimmed; everything else in a value is literal to the end of the line - quotes are preserved and an inline ; or # is content, not a comment. Because the reader trims it, Utf8IniWriter refuses a key or value that begins or ends with a space or tab rather than write one that reads back without it.
  • Both ; and # start full-line comments (IniReaderOptions.DisallowHashComments restricts to ;).
  • A section name runs to the first ] that only whitespace or a comment follows, so [foo]bar] names foo]bar, and the spaces and tabs around the name are trimmed. A comment after a header is skipped rather than reported as a comment token; any other text after the header is malformed. Utf8IniWriter therefore refuses a section name that holds a ] followed by a comment marker, or that begins or ends with a space or tab.
  • A leading UTF-8 BOM is skipped; LF, CRLF, and lone-CR line endings are equivalent.

Duplicate handling is a document-model policy (IniDocumentOptions, also surfaced on IniSerializerOptions), because the source-order reader reports the file verbatim:

Knob Values Default
DuplicateSectionBehavior Merge (later [section] blocks append to the first) / Disallowed Merge
DuplicateKeyBehavior LastWins / FirstWins / Disallowed LastWins

A global key that collides with a section of the same name is always rejected (IniFormatException), because both would claim the same root property; IniSerializerOptions.GlobalSectionName maps the global entries to a reserved root key instead of hoisting them, which removes the ambiguity. IniSerializerDefaults.Strict selects Disallowed for both duplicate policies - Python configparser strict mode.

Where to go next