SergeiM.Xembly 0.2.0

SergeiM.Xembly - XML Modifying Imperative Language for .NET

Xembly is an Assembly-like imperative programming language for data manipulation in XML documents. It is a much simpler alternative to DOM, XSLT, and XQuery.

This is a .NET (C#) implementation of the original Java library by Yegor Bugayenko.

Quick Start

Installation

dotnet add package SergeiM.Xembly

Basic Usage

using SergeiM.Xembly;

// Create directives
var directives = new Directives()
    .Add("root")
    .Add("order")
    .Attr("id", "553")
    .Set("$140.00");

// Generate XML
var xembler = new Xembler(directives);
string xml = xembler.Xml();

// Output: <root><order id="553">$140.00</order></root>

Why Xembly?

Suppose you have an XML document:

<orders>
  <order id="553">
    <amount>$45.00</amount>
  </order>
</orders>

You want to change the amount of order #553 from $45.00 to $140.00. With Xembly, you write:

var directives = new Directives()
    .Add("orders")
    .Add("order")
    .Attr("id", "553")
    .Add("amount")
    .Set("$140.00");

Much simpler than DOM manipulation or XSLT transformations!

Supported Directives

More Examples

Using Script Syntax

var directives = new Directives("""
    ADD 'orders';
    ADD 'order';
    ATTR 'id', '553';
    ADD 'amount';
    SET '$140.00';
    """);

var xml = new Xembler(directives).Xml();
// Output: <orders><order id="553"><amount>$140.00</amount></order></orders>

XPath Navigation

var directives = new Directives()
    .Add("root")
    .Add("order").Attr("id", "1").Set("100").Up()
    .Add("order").Attr("id", "2").Set("200").Up()
    .XPath("//order[@id='2']")
    .Set("250");

var xml = new Xembler(directives).Xml();
// Changes the value of order with id='2' to 250

Multiple Nodes

var directives = new Directives()
    .Add("root")
    .Add("item")
    .Set("First")
    .Up()
    .Add("item")
    .Set("Second");

var xml = new Xembler(directives).Xml();
// Output: <root><item>First</item><item>Second</item></root>

Stack Operations (PUSH/POP)

Save and restore cursor position using stack operations:

var directives = new Directives()
    .Add("catalog")
    .Add("books")
    .Push()                      // Save position at <books>
    .Add("book").Attr("id", "1")
    .Add("title").Set("First Book").Up().Up()
    .Pop()                       // Return to <books>
    .Add("book").Attr("id", "2")
    .Add("title").Set("Second Book");

var xml = new Xembler(directives).Xml();
// Both books are added under <books>, even though we navigated deep into the first book

Error Handling

try
{
    var directives = new Directives("INVALID 'test';");
    new Xembler(directives).Xml();
}
catch (ParsingException ex)
{
    Console.WriteLine($"Parse error at line {ex.Line}, column {ex.Column}: {ex.Message}");
}

try
{
    var directives = new Directives()
        .Add("root")
        .Strict(2); // Expecting 2 nodes, but only have 1
    new Xembler(directives).Xml();
}
catch (StrictException ex)
{
    Console.WriteLine($"Validation error: {ex.Message}");
}

Exception Types

Modifying Existing Documents

var document = new XmlDocument();
document.LoadXml("<root><existing>node</existing></root>");

var directives = new Directives()
    .Add("new")
    .Set("value");

new Xembler(directives).Apply(document);
// Document now has: <root><existing>node</existing><new>value</new></root>

Building from Source

dotnet build

Running Tests

dotnet test

References

• Original Java implementation: xembly
• Blog post: Xembly, an Assembly for XML

License

MIT License - see LICENSE.txt for details.