Examples

Usage

using Promptuarium;

Creating trees

Creating single node (or tree root):

Element node = new Element();

Creating single tree:

Element tree = new Element();
Element child1 = new Element();
Element child2 = new Element();
Element child3 = new Element();

tree += child1;
child1 += child2;
tree.Add(child3);

child1.Remove(child2);
tree -= child1;

Adding childs with the constructor:

Element tree = new Element(null, null, 
    new Element(),
    new Element(),
    new Element()
);

Adding nodes with LINQ:

Element tree = new Element();

tree.Add(
    new byte[] {5, 9, 3, 6, 7}.Select(n => new Element(Data.FromByte(n)))
);

Adding data and/or metadata

Adding data and/or metadata to a node:

Element tree = new Element();
Element decimalGuidNode = new Element();

decimalGuidNode.Data = Data.FromGuid(Guid.NewGuid());
decimalGuidNode.MetaData = Data.FromDecimal(1.978M);

tree.Add(decimalGuidNode);

Add data/metadata through properties:

Element tree = new Element();

Element decimalGuidNode = new Element()
{
    Data = Data.FromGuid(Guid.NewGuid()),
    MetaData = Data.FromDecimal(1.978M)
};

tree.Add(decimalGuidNode);

Adding data and/or metadata to a node with the constructor:

Element child1 = new Element(AData.FromGuid(testGuid));
Element child2 = new Element(null, AData.FromDecimal(1.978M));
Element child3 = new Element(new MemoryStream(new byte[] { 3 }), Data.FromDecimal(1.978M));

Element tree = new Element();

tree += child1;
tree.Add(child2, child3);

Accessing data and/or metadata

Accessing the data or metadata of a node:

bool boolValue = node.Data.AsBool();
DateTime dateTimeValue = node.MetaData.AsDateTime();

Addressing child nodes

Accessing children (IEnumerable):

foreach (var child in node.Children)
{
    child.Data = Data.FromVarInt(z++);
}

Element child = (from child in node.Children where child.MetaData.AsInt() > 100 select child).FirstOrDefault();

Accessing the data of child node #2 (addressing child nodes with the indexer):

long longValue = tree[2].Data.AsLong();
long varIntValue = tree[2].Data.AsVarInt();

Accessing the metadata of child node #2 of child node #5:

string stringValue = tree[5][2].MetaData.AsUtf16String();

Save and load the tree

Save tree into a file or stream:

await tree.SaveAsync(@"file1.p", cancellationToken);
await tree.SaveAsync(someNetworkStream);

Load tree from a file or stream:

Element tree = await Element.LoadAsync(@"file1.p");
Element treeFromMemoryStream = await Element.LoadAsync(someMemoryStream, cancellationToken);

Conversion to string

Creating string from a node (i.e. to display it's metadata and data):

Element node = tree[1][3][7];
string nodeString = node.ToString();

Creating string from a tree (i.e. for debug purposes):

string treeString = tree.TreeToString();

Stream compatibility

More Promptuarium tree can be saved into the same stream/file:

using (MemoryStream stream = new MemoryStream())
{
    Element treeA = new Element() { Data = AData.FromAsciiString("A") };

    treeA.Add(
        new Element { Data = Data.FromAsciiString("A1") },
        new Element { Data = Data.FromAsciiString("A2") }
    );

    Element treeB = new Element() { Data = Data.FromAsciiString("B") };

    treeB.Add(
        new Element { Data = Data.FromAsciiString("B1") },
        new Element { Data = Data.FromAsciiString("B2") }
    );

    await treeA.SaveAsync(stream);
    await treeB.SaveAsync(stream);

    stream.Position = 0;

    Element tree2A = Element.LoadAsync(stream);
    Element tree2B = Element.LoadAsync(stream);

    string sTreeA = treeA.TreeToString();
    string sTreeB = treeB.TreeToString(); 

    string sTree2A = tree2A.TreeToString();
    string sTree2B = tree2B.TreeToString(); 

    Assert.AreEqual(sTreeA, sTree2A);
    Assert.AreEqual(sTreeB, sTree2B);
}

Events

Adding save (saving/saved) and load (loading/loaded) events:

var tree = new Element(Data.FromUtf8String("ROOT"), null, 
    new Element(Data.FromUtf8String("NODE1"), null, null, null),
    new Element(Data.FromUtf8String("NODE2"), null, null),
    new Element(Data.FromUtf8String("NODE3"), null)
);

int savingEventFired = 0;
int savedEventFired = 0;

int loadingEventFired = 0;
int loadedEventFired = 0;

tree.OnDataSaving += (s, a) =>
{
    savingEventFired++;
};

tree.OnDataSaved += (s, a) =>
{
    savedEventFired++;
};

await tree.SaveAsync(@"..\temp\ut10.p");

List<string> loadingNodes = new List<string>();
List<string> loadedNodes = new List<string>();

Element.OnDataLoading += (s, a) =>
{
    loadingNodes.Add(s.Data.AsUtf8String());
};

Element.OnDataLoaded += (s, a) =>
{
    loadedNodes.Add(s.Data.AsUtf8String());
};

var tree2 = await Element.LoadAsync(@"..\temp\ut10.p");

F# example

open Promptuarium

let longValue = 100L

let tree = Element()
tree.Add(Element(Data.FromDateTime(System.DateTime.Now), null))
tree.MetaData <- Data.FromUtf8String("Hello Promptuarium Demo")
tree.[0].MetaData <- Data.FromLong(longValue)

let base64EncodedTree = tree.ToBase64StringAsync() |> Async.AwaitTask
let longValueBack = tree.[0].MetaData.AsLong()

tree.SaveAsync("c:\\windows\\temp\\FromFSharp.p") |> Async.AwaitTaskVoid