Table of Contents

Utf8DotEnvReader Struct

Definition

Namespace
Bodu.Text.DotEnv.Reader
Assembly
Bodu.Text.DotEnv.dll
Package
Bodu.Text.DotEnv 1.0.0
Source
Utf8DotEnvReader.cs

Provides a high-performance, forward-only, allocation-light reader for DotEnv bytes. The reader is a ref struct, so it lives on the stack and cannot be boxed or captured; pass it by ref to thread it through a converter.

public ref struct Utf8DotEnvReader
Inherited Members

Remarks

A DotEnv document is a flat, ordered object of string-valued keys. A call to Read() advances to the next token and reports it through TokenType: a synthetic StartObject frames the document, each entry surfaces a PropertyName followed by a String, comment lines appear as Comment tokens, and a closing EndObject ends the document.

Key and comment text is exposed verbatim; a string value's quotes are stripped and its escape sequences resolved, so GetString() returns the logical value while ValueSpan exposes the raw source bytes. 

ReadOnlySpan<byte> bytes = "export HOST=localhost\nPORT=5432\n"u8;
var reader = new Utf8DotEnvReader(bytes);

while (reader.Read())
{
    if (reader.TokenType == DotEnvTokenType.PropertyName)
        Console.Write($"{reader.GetString()} = ");
    else if (reader.TokenType == DotEnvTokenType.String)
        Console.WriteLine(reader.GetString());
}

Constructors

Utf8DotEnvReader(ReadOnlySpan<byte>)

Initializes a new instance of the Utf8DotEnvReader struct over the supplied bytes.

public Utf8DotEnvReader(ReadOnlySpan<byte> data)

Parameters

data ReadOnlySpan<byte>

The DotEnv source bytes.

Utf8DotEnvReader(ReadOnlySpan<byte>, DotEnvReaderOptions)

Initializes a new instance of the Utf8DotEnvReader struct over the supplied bytes using the supplied options.

public Utf8DotEnvReader(ReadOnlySpan<byte> data, DotEnvReaderOptions options)

Parameters

data ReadOnlySpan<byte>

The DotEnv source bytes.

options DotEnvReaderOptions

The reader options controlling optional DotEnv syntax.

Properties

BytesConsumed

Gets the number of bytes consumed so far.

public readonly int BytesConsumed { get; }

Property Value

int

The read position.

CurrentDepth

Gets the current object nesting depth.

public readonly int CurrentDepth { get; }

Property Value

int

Zero before the document object opens and after it closes; one while inside it.

CurrentIsExport

Gets a value indicating whether the current property carried an export prefix.

public readonly bool CurrentIsExport { get; }

Property Value

bool

true when the current PropertyName or its String value was declared with a leading export keyword.

LineNumber

Gets the 1-based line number at which the current token begins.

public readonly int LineNumber { get; }

Property Value

int

The current line number.

TokenType

Gets the kind of the current token.

public readonly DotEnvTokenType TokenType { get; }

Property Value

DotEnvTokenType

The current token kind.

ValueSpan

Gets the raw source content bytes of the current property name, string value, or comment token. For a string value with escape sequences the span is the unprocessed source between the value delimiters.

public readonly ReadOnlySpan<byte> ValueSpan { get; }

Property Value

ReadOnlySpan<byte>

The raw content bytes, or an empty span for structural tokens.

Methods

GetString()

Decodes the current property name, string value, or comment token as text, stripping quotes and resolving escape sequences for a string value.

public readonly string GetString()

Returns

string

The decoded text.

Exceptions

InvalidOperationException

Thrown when the current token is not a property name, string value, or comment.

Read()

Advances the reader to the next token.

public bool Read()

Returns

bool

true when a token was read; false at the end of the document.

Exceptions

DotEnvFormatException

Thrown when the bytes are not valid DotEnv.

Skip()

Skips the current value. For a property name the reader first advances to the value and then leaves it consumed; for structural or scalar tokens the reader simply advances once.

public void Skip()

Exceptions

DotEnvFormatException

Thrown when the skipped bytes are not valid DotEnv.

TrySkip()

Attempts to skip the current value.

public bool TrySkip()

Returns

bool

true always, because the reader operates over a complete buffer.

Exceptions

DotEnvFormatException

Thrown when the skipped bytes are not valid DotEnv.

ValueTextEquals(ReadOnlySpan<byte>)

Compares the current token's raw content to the supplied UTF-8 bytes without allocating.

public readonly bool ValueTextEquals(ReadOnlySpan<byte> utf8Text)

Parameters

utf8Text ReadOnlySpan<byte>

The UTF-8 bytes to compare against.

Returns

bool

true when the token's raw content equals utf8Text byte for byte; otherwise false.

Remarks

The comparison is against the raw source span. For a string value that carried escape sequences, compare against GetString() instead.

Exceptions

InvalidOperationException

Thrown when the current token is not a property name, string value, or comment.

ValueTextEquals(ReadOnlySpan<char>)

Compares the current token's raw content to the UTF-8 encoding of the supplied characters without allocating.

public readonly bool ValueTextEquals(ReadOnlySpan<char> text)

Parameters

text ReadOnlySpan<char>

The characters to compare against.

Returns

bool

true when the token's raw content equals the UTF-8 encoding of text; otherwise false.

Exceptions

InvalidOperationException

Thrown when the current token is not a property name, string value, or comment.

ValueTextEquals(string?)

Compares the current token's raw content to the UTF-8 encoding of the supplied string.

public readonly bool ValueTextEquals(string? text)

Parameters

text string

The string to compare against, which may be null.

Returns

bool

true when the token's raw content equals the UTF-8 encoding of text; otherwise false.

Exceptions

InvalidOperationException

Thrown when the current token is not a property name, string value, or comment.

Applies to

ProductVersions
.NET8, 10