Class ModuleFileText
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
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
HasByteOrderMark
public bool HasByteOrderMark { get; }
Property Value
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
Text
The text, with the line endings the file has.
public string Text { get; }
Property Value
Methods
Decode(byte[], int)
Decodes the bytes of a module file.
public static ModuleFileText Decode(byte[] bytes, int ansiCodePage)
Parameters
bytesbyte[]The bytes of the file.
ansiCodePageintThe 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
ansiCodePageis 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
editsIReadOnlyList<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
fileSystemIFileSystemThe file system the file is on.
pathstringThe file's path.
ansiCodePageintThe code page a file without a byte order mark that is not valid UTF-8 is in (Decode(byte[], int)).
tokenCancellationTokenA 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
ansiCodePageis 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
fileSystemIFileSystemThe file system the file is on.
pathstringThe file's path.
tokenCancellationTokenA token that cancels the write.
Returns
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.