Meziantou.FrameworkIniDocumentSyntax Class
A whole INI document.
public sealed class IniDocumentSyntax : IniSyntaxNodeRemarks
The entries are flat, as they are in the text: a section header is followed by the properties under it, not their parent. IniDocumentSyntax.GlobalProperties and IniSectionSyntax.Properties group them, IniDocumentSyntax.GetValue looks one up, and IniDocumentSyntax.SetValue, IniDocumentSyntax.RemoveProperties, and IniDocumentSyntax.RemoveSections edit them.
Every entry ends its line. However a document is edited, an entry that another one follows is given a line break when it has none, so two entries never run into each other.
- Inheritance
IniSyntaxNodeIniDocumentSyntax
Properties
| Name | Description |
|---|---|
| EndOfFileToken | |
| Entries | Gets the section, property, and skipped-text entries in source order. |
| GlobalProperties | Gets the properties that come before the first section header. |
| Options | Gets the options this document is read with. |
| Sections | Gets the section headers, in source order. |
EndOfFileToken
IniDocumentSyntax.csEntries
IniDocumentSyntax.csGets the section, property, and skipped-text entries in source order.
public SyntaxList<IniEntrySyntax> Entries { get; }Property value
GlobalProperties
IniDocumentSyntax.csGets the properties that come before the first section header.
public IReadOnlyList<IniPropertySyntax> GlobalProperties { get; }Property value
Options
IniDocumentSyntax.csGets the options this document is read with.
public IniParseOptions Options { get; }Property value
Remarks
They are the options it was parsed with, or the ones given to IniSyntaxTree.Create, and every document an edit makes from this one keeps them. A document built with SyntaxFactory has IniParseOptions.Default. They decide how IniPropertySyntax.WithValue writes a value, and how names are compared when no comparer is given.
Sections
IniDocumentSyntax.csGets the section headers, in source order.
public IEnumerable<IniSectionSyntax> Sections { get; }Property value
Methods
| Name | Description |
|---|---|
| Accept(IniSyntaxVisitor) | |
| Accept<TResult>(IniSyntaxVisitor<TResult>) | |
| AddEntries(IniEntrySyntax[]) | Returns this document with items added at the end. |
| GetProperties(string?, string, StringComparer?) | Gets the properties with key key in every section named section, in source order. |
| GetSections(string, StringComparer?) | Gets the section headers named name, in source order. |
| GetValue(string?, string, StringComparer?) | Gets the value of the property with key key in the section named section. |
| RemoveProperties(string?, string, StringComparer?) | Returns this document without the properties with key key in the sections named section. |
| RemoveSections(string, StringComparer?) | Returns this document without the sections named name and the entries under them. |
| SetValue(string?, string, string, StringComparer?) | Returns this document with the property key of section set to value. |
| SetValues(IEnumerable<(string? Section, string Key, string Value)>, StringComparer?) | Returns this document with each property of values set, as IniDocumentSyntax.SetValue sets them one after the other. |
| Update(SyntaxList<IniEntrySyntax>, SyntaxToken) | Returns this document with the given parts, or itself when nothing changed. |
| WithEndOfFileToken(SyntaxToken) | |
| WithEntries(SyntaxList<IniEntrySyntax>) |
Accept overloads
Accept(IniSyntaxVisitor)
IniDocumentSyntax.cspublic override void Accept(IniSyntaxVisitor visitor)Parameters
visitorIniSyntaxVisitor
No documentation is available.
Accept<TResult>(IniSyntaxVisitor<TResult>)
IniDocumentSyntax.cspublic override TResult? Accept<TResult>(IniSyntaxVisitor<TResult> visitor)No documentation is available.
AddEntries(IniEntrySyntax[])
IniDocumentSyntax.csReturns this document with items added at the end.
public IniDocumentSyntax AddEntries(params IniEntrySyntax[] items)Parameters
itemsIniEntrySyntax[]
Returns
Exceptions
ArgumentNullExceptionitemsisnull.
Remarks
Every entry has to end its line, so a line break is added after the last entry and after each of items that does not already end with one. The line breaks of items are those of the document: its first line break, or a line feed when it has none. In a document holding nothing but trivia, such as a header comment, items come after it.
GetProperties(string?, string, StringComparer?)
IniDocumentSyntax.csGets the properties with key key in every section named section, in source order.
public IEnumerable<IniPropertySyntax> GetProperties(string? section, string key, StringComparer? comparer = null)Parameters
sectionstring?- The name of the section, or
nullfor the properties before the first section header. keystring- The key of the properties.
comparerStringComparer?- How section names and keys are compared, or
nullfor theIniParseOptions.NameComparerofIniDocumentSyntax.Options.
Returns
IEnumerable<IniPropertySyntax>
Exceptions
ArgumentNullExceptionkeyisnull.
GetSections(string, StringComparer?)
IniDocumentSyntax.csGets the section headers named name, in source order.
public IEnumerable<IniSectionSyntax> GetSections(string name, StringComparer? comparer = null)Parameters
namestring- The name of the sections.
comparerStringComparer?- How names are compared, or
nullfor theIniParseOptions.NameComparerofIniDocumentSyntax.Options.
Returns
Exceptions
ArgumentNullExceptionnameisnull.
GetValue(string?, string, StringComparer?)
IniDocumentSyntax.csGets the value of the property with key key in the section named section.
public string? GetValue(string? section, string key, StringComparer? comparer = null)Parameters
sectionstring?- The name of the section, or
nullfor the properties before the first section header. keystring- The key of the property.
comparerStringComparer?- How section names and keys are compared, or
nullfor theIniParseOptions.NameComparerofIniDocumentSyntax.Options.
Returns
string? The value, or null when there is no such property.
Exceptions
ArgumentNullExceptionkeyisnull.
Remarks
Sections that share a name are read as one section. When the key is there more than once, the last one wins, as it does in most readers of INI files.
RemoveProperties(string?, string, StringComparer?)
IniDocumentSyntax.csReturns this document without the properties with key key in the sections named section.
public IniDocumentSyntax RemoveProperties(string? section, string key, StringComparer? comparer = null)Parameters
sectionstring?- The name of the section, or
nullfor the properties before the first section header. keystring- The key of the properties.
comparerStringComparer?- How section names and keys are compared, or
nullfor theIniParseOptions.NameComparerofIniDocumentSyntax.Options.
Returns
IniDocumentSyntax The document without the properties, or this document when there are none.
Exceptions
ArgumentNullExceptionkeyisnull.
Remarks
Every one of them is removed, with the comment lines in front of it and the comment after it, so that IniDocumentSyntax.GetValue finds none. Comment lines that a blank line separates from it head a group of entries, or the document, and stay.
RemoveSections(string, StringComparer?)
IniDocumentSyntax.csReturns this document without the sections named name and the entries under them.
public IniDocumentSyntax RemoveSections(string name, StringComparer? comparer = null)Parameters
namestring- The name of the sections.
comparerStringComparer?- How names are compared, or
nullfor theIniParseOptions.NameComparerofIniDocumentSyntax.Options.
Returns
IniDocumentSyntax The document without the sections, or this document when there are none.
Exceptions
ArgumentNullExceptionnameisnull.
Remarks
Each header is removed with the comment lines in front of it and every entry up to the next header. Comment lines that a blank line separates from the header head the document, or a group of sections, and stay.
SetValue(string?, string, string, StringComparer?)
IniDocumentSyntax.csReturns this document with the property key of section set to value.
public IniDocumentSyntax SetValue(string? section, string key, string value, StringComparer? comparer = null)Parameters
sectionstring?- The name of the section, or
nullfor the properties before the first section header. keystring- The key of the property.
valuestring- The value.
comparerStringComparer?- How section names and keys are compared, or
nullfor theIniParseOptions.NameComparerofIniDocumentSyntax.Options.
Returns
Exceptions
ArgumentNullExceptionkeyorvalueisnull.ArgumentExceptionkey,section, orvaluecannot be written the wayIniDocumentSyntax.Optionsread them; seeSyntaxFactory.Key,SyntaxFactory.SectionName, andIniPropertySyntax.WithValue. A key or section the document already has is not checked, as it is not written.
Remarks
When the property exists, the one IniDocumentSyntax.GetValue reads gets the new value, as IniPropertySyntax.WithValue writes it. Otherwise it is added after the last entry of the last section named section, or of the properties before the first section header, written like the property before it: same indentation, same separator, same spacing. When there is no such section, it is added at the end of the document under a new header, after a blank line and after the comments that end the document.
The value is written the way IniDocumentSyntax.Options read it. The lines of a value with line breaks are read back joined with \n, whichever of \r\n, \r, or \n separated them.
SetValues(IEnumerable<(string? Section, string Key, string Value)>, StringComparer?)
IniDocumentSyntax.csReturns this document with each property of values set, as IniDocumentSyntax.SetValue sets them one after the other.
public IniDocumentSyntax SetValues(IEnumerable<(string? Section, string Key, string Value)> values, StringComparer? comparer = null)Parameters
valuesIEnumerable<(string? Section, string Key, string Value)>- The section, key, and value of each property, as
IniDocumentSyntax.SetValuetakes them. comparerStringComparer?- How section names and keys are compared, or
nullfor theIniParseOptions.NameComparerofIniDocumentSyntax.Options.
Returns
Exceptions
ArgumentNullExceptionvalues, or a key or value in it, isnull.ArgumentException- A section, key, or value cannot be written; see
IniDocumentSyntax.SetValue.
Remarks
Every edit of an immutable document rebuilds it, so setting properties one at a time costs as much as the document for each of them. This sets every property the document already has in one edit, and only the new ones one at a time. When a property is set more than once, the last value wins.
Update(SyntaxList<IniEntrySyntax>, SyntaxToken)
IniDocumentSyntax.csReturns this document with the given parts, or itself when nothing changed.
public IniDocumentSyntax Update(SyntaxList<IniEntrySyntax> entries, SyntaxToken endOfFileToken)Parameters
entriesSyntaxList<IniEntrySyntax>endOfFileTokenSyntaxToken
Returns
Remarks
The new document keeps IniDocumentSyntax.Options.
WithEndOfFileToken(SyntaxToken)
IniDocumentSyntax.cspublic IniDocumentSyntax WithEndOfFileToken(SyntaxToken endOfFileToken)No documentation is available.
WithEntries(SyntaxList<IniEntrySyntax>)
IniDocumentSyntax.cspublic IniDocumentSyntax WithEntries(SyntaxList<IniEntrySyntax> entries)No documentation is available.