TLio.FormatConverter 0.9.0

TLio.FormatConverter

The convert and convertValue commands for TLio, plus MultiFormatScriptRunner — the piece that lets one script change the document's format partway through — and the JSON, XML and YAML converters they work through. One assembly, one package.

dotnet add package TLio.FormatConverter

Two commands, and what changes format

• convert changes the whole document. That means a different TNode, which no ICommand<TNode> can return — so the engine cannot run it. MultiFormatScriptRunner splits the script at each boundary and re-hosts each section on the engine for that format. Run on a bare engine it converts nothing and says so.
• convertValue changes one value at a path. The document's format never changes, so it is an ordinary command on the ordinary engine — the embedded-payload case, an XML string inside a JSON envelope.

Paths after a convert speak the new format's path language. That is inherent: the paths address the document, and the document has changed format.

Quick start

using TLio.FormatConverter;         // the commands and the runner
using TLio.FormatConverter.Core;    // the converter itself
using TLio.FormatConverter.Json;    // the three adapters
using TLio.FormatConverter.Xml;
using TLio.FormatConverter.Yaml;

// Fully qualified: the type's name repeats a namespace segment, so a bare
// `new FormatConverter()` is only unambiguous where `using TLio;` is absent.
var converter = new TLio.FormatConverter.Core.FormatConverter();
converter.Register(new JsonFormatAdapter());
converter.Register(new XmlFormatAdapter());
converter.Register(new YamlFormatAdapter());

var runner = new MultiFormatScriptRunner(converter);
runner.RegisterExecutor(new ScriptEngineSectionExecutor<JToken>(
    "json", jsonEngine, JsonExecutionContext.CreateDefault));
runner.RegisterExecutor(new ScriptEngineSectionExecutor<XElement>(
    "xml", xmlEngine, XmlExecutionContext.CreateWithNativeXPath));
runner.RegisterExecutor(new ScriptEngineSectionExecutor<YamlNode>(
    "yaml", yamlEngine, YamlExecutionContext.CreateDefault));

var result = runner.Run("json", document, script);
// result.Document, result.FormatId, result.Success, result.Logs

The script:

[
  { "command": "add",     "path": "$.order.status", "value": "new"    },
  { "command": "convert", "to": "yaml" },
  { "command": "add",     "path": "order.source",   "value": "portal" },
  { "command": "convert", "to": "xml"  },
  { "command": "rename",  "path": "/order",         "name":  "opdracht" }
]

MultiFormatScriptRunner.CrossesAFormatBoundary(script) is how a host decides whether a script needs the runner or a plain ScriptEngine.

Registering the commands on an engine

convertValue works on any engine; convert still needs the runner, but registering it means a script that uses it inline gets an explanation rather than "unknown command".

var options = ParseOptions<JToken>.CreateDefault();
options.CommandsProvider.RegisterFormatConversion<JToken>(converter, "json");

Settings

Per-boundary, and they do not carry to the next convert: attributePrefix, textProperty, namespacePrefix, arrayItemName, arrayHandling, nullRepresentation, nameSanitization, inferTypes, cdataAsText, flattenAnchors. Each exists where the formats genuinely disagree.

Conversion output is the canonical document shape TLio's own adapters address, so the commands after a boundary land where the paths say they do.

License

MIT — see the repository.