Table of Contents

Class ModuleFileText

Namespace
RDCore.SDK.Workspace
Assembly
RDCore.SDK.dll

The text of a module file as it is on disk: decoded in the encoding the file is written in, and written back in it, byte for byte where the text is not edited.

public sealed class ModuleFileText
Inheritance
ModuleFileText
Inherited Members

Remarks

A file's encoding is read from its byte order mark: UTF-8, UTF-16 (little or big endian), or UTF-32 (little endian). A file without one is UTF-8 when its bytes are valid UTF-8, and is otherwise in the ANSI code page the caller names (DefaultAnsiCodePage when it has no setting to take it from). The code page of the operating system is never used: Linux and macOS have none, and a file would read differently on each machine.

The text keeps everything the file has: its byte order mark or its absence, each line's ending (a carriage return and a line feed, a line feed, or a carriage return, mixed as they are), and a newline at the end or its absence. An edit is written with the line endings of the line it is made on (Edit(IReadOnlyList<RefactorTextEdit>)), and a text the file's encoding cannot write is refused, never written with a replacement character.

Fields

DefaultAnsiCodePage

The ANSI code page a file without a byte order mark that is not UTF-8 is read in when no setting names one: Windows-1252, the code page Office for Windows writes Western European module files in.

public const int DefaultAnsiCodePage = 1252

Field Value

int

Properties

Encoding

The encoding the file is written in. It refuses a character it cannot write, and a byte it has no character for.

public Encoding Encoding { get; }

Property Value

Encoding

HasByteOrderMark

true when the file starts with a byte order mark, which Encode() writes again.

public bool HasByteOrderMark { get; }

Property Value

bool

IsLossless

true when every byte of the file decodes in its encoding. A file that is not (bytes not valid in the encoding its byte order mark names, or a byte the ANSI code page has no character for) is read with a replacement character for each such byte, and is not edited (Edit(IReadOnlyList<RefactorTextEdit>)).

public bool IsLossless { get; }

Property Value

bool

Text

The text, with the line endings the file has.

public string Text { get; }

Property Value

string

Methods

Decode(byte[], int)

Decodes the bytes of a module file.

public static ModuleFileText Decode(byte[] bytes, int ansiCodePage)

Parameters

bytes byte[]

The bytes of the file.

ansiCodePage int

The code page a file without a byte order mark that is not valid UTF-8 is in: the environment's (Environment.AnsiCodePage), or DefaultAnsiCodePage.

Returns

ModuleFileText

The text, and the encoding it is written back in.

Exceptions

ArgumentOutOfRangeException

ansiCodePage is not the code page of an encoding .NET has.

Edit(IReadOnlyList<RefactorTextEdit>)

The text with edits made, in the same encoding.

public ModuleFileText Edit(IReadOnlyList<RefactorTextEdit> edits)

Parameters

edits IReadOnlyList<RefactorTextEdit>

The edits, in any order, each of the text before any of them; they do not overlap (LSP 3.17 §TextEdit).

Returns

ModuleFileText

The edited text.

Remarks

The line breaks an edit writes are written with the ending of the line it starts on; on the last line, which has none, with the ending of the line before it; and in a text of one line, with a carriage return and a line feed. The rest of the text is not touched.

Exceptions

ModuleFileTextException

The file is not lossless, or the edited text has a character its encoding cannot write.

ArgumentException

Two of the edits overlap.

ArgumentOutOfRangeException

An edit is of a line the text does not have.

Encode()

The bytes of the file: the byte order mark it was read with, if any, then the text in its encoding. Unedited, they are the bytes it was read from.

public byte[] Encode()

Returns

byte[]

The bytes to write.

Exceptions

ModuleFileTextException

The text has a character its encoding cannot write.

ReadAsync(IFileSystem, string, int, CancellationToken)

Reads a module file.

public static Task<ModuleFileText> ReadAsync(IFileSystem fileSystem, string path, int ansiCodePage, CancellationToken token)

Parameters

fileSystem IFileSystem

The file system the file is on.

path string

The file's path.

ansiCodePage int

The code page a file without a byte order mark that is not valid UTF-8 is in (Decode(byte[], int)).

token CancellationToken

A token that cancels the read.

Returns

Task<ModuleFileText>

The file's text, and the encoding it is written back in.

Exceptions

IOException

The file could not be read.

ArgumentOutOfRangeException

ansiCodePage is not the code page of an encoding .NET has.

WriteAsync(IFileSystem, string, CancellationToken)

Writes the file: its bytes (Encode()) go to a file beside it, which then replaces it, so that the file is never seen half written.

public Task WriteAsync(IFileSystem fileSystem, string path, CancellationToken token)

Parameters

fileSystem IFileSystem

The file system the file is on.

path string

The file's path.

token CancellationToken

A token that cancels the write.

Returns

Task

Exceptions

ModuleFileTextException

The text has a character its encoding cannot write; nothing is written.

IOException

The file could not be written; it is as it was.