Structured Document API

var doc = new StructuredText("the entire text of the document");

The document will parse, and populate all its properties.

Section Collections

The primary feature of the document are lists of Section objects, in several collections:

• Sections: The raw list of all Section objects
• FilteredSections: A list of Section objects which are not hidden (the name does not start with an underscore)
• NarrativeSections: A list of Section objects which are not explicitly closed (see Structured Document Format)
• DefaultSections: A list of Section objects with a name matching the default section name

There are methods for working with sections:

• Section GetSection(string name): Returns the first section with the provided name
• string GetSectionContent(string name, string defaultValue): Returns the content of the first section with the provided name, or the default value if no such section is found
• List<Section> GetSections(params string[] name): Returns a list of all sections with any of the provided names
• bool HasSection: Returns true if the document has at least one section with the provided name
• void Apply(Func<Section, StructuredTextBase, Section> function): Takes a delegate that will be applied to all sections. The delegate will be called once for each section, and be passed (1) that section and (2) the entire document. It can do whatever it likes to the section, then return the transformed version, which will replace the original in the document.

Content

Each section has a Content property that contains whatever is separated from the meta by a blank line.

Each section also exposes a Lines property which is a list of strings representing each line in the section. TrimmedLines removes the blank lines from the beginning and end of the content (but retains any blank lines in the middle).

Metadata Collections

Each section – and the document as a whole – has a MetaCollection object exposed at the Meta property. It exposes the following methods:

• string Get(string key): Returns the string representation of the first instance of the provided key. Returns null if no such meta is found.
• T Get<T>(string key): Returns the value of first instance of metadata with the provided key. Returns default(T) if no such meta is found.
• bool HasMeta(string key): Returns true if the collection has any meta with the provided key.
• List<T> GetAllValues<T>(string key): Will provide a list of all values for the provided key.

Document Meta

The document as a whole – like each of its sections – exposes a Meta property which functions as above. This meta collection is simply the same meta collection of the first section.

However, the document also exposes an AllMeta property which is a consolidated list of all the meta items from all the sections in the document.

Many of the meta-related methods return the first meta value found for the key, which means AllMeta can be used to search down through multiple sections for a specific meta key.

Meta also has a few convenience properties for common meta.

• string Title: The value for the meta with the key title
• string Description: The value for the meta with the key description or desc (I kept forgetting the key I used, so I just look for both)
• string Status: The value for the meta with the key status
• DateTime Date: The value for the meta with the key date

Example

Consider this document:

title: The Barker Family
established: 1999-06-05

\[[ person ]]
first: Deane
last: Barker

The husband

\[[ person ]]
first: Annie
last: Barker

The wife

We can work with it like this:

var doc = new StructuredText(documentText);

Console.WriteLine(doc.Title);
Console.WriteLine($"Est. {doc.Get<DateTime>("established"):MMMM, d yyyy}");

foreach(var section in doc.GetSections("person"))
{
    var lastName = section.Meta.Get("last");
    var firstName = section.Meta.Get("first")
    Console.WriteLine($"{last}, {first}: {section.Content}");
}

Resulting in:

The Barker Family
Est. June 5, 1999
Barker, Deane: The husband
Barker, Annie: The wife

SectionMap

Each section has a Map property which exposes numerous properties regarding where that section lies in context of the entire document.

• bool IsFirst: Returns true if this is the first section in the document
• bool IsLast: Returns true if this is the last section in the document
• int Total: Returns the total number of sections in the document
• int Index: Returns the 0-based position of this section in the document
• int Ordinal: Returns the 1-based position of this section in the document
• Section Prev: Returns the prior section in the document, or null if this is the first section
• Section Next: Returns the next section in the document, or null if this is the last section
• int TotalOfType: Returns the number of sections with the same name as this section (including this section)
• int IndexOfType: Returns the 0-based position of this section among sections with the same name
• int OrdinalOfType: Returns the 1-based position of this section among sections with the same name
• bool IsFirstOfType: Returns true if this is the first section with its name in the document
• bool IsLastOfType: Returns true if this is the last section with its name in the document
• bool IsNextSameType: Returns true if the next section has the same name as this section
• bool IsPrevSameType: Returns true if the previous section has the same name as this section