abstract / core

v0.0.3 2023-07-03 08:06 UTC

Requires

• symfony/polyfill: ^1.27

proprietary

• Abstract

Published on Packagist.org on 2023-07-03 08:07 UTC

README

ARMES — Abstract Representation, Mapping & Expression Syntax — is a language for describing structures independently of a particular framework or platform. A mapper interprets those structures for the environment where they will be used.

For example, one UI structure can become HTML, React components, or native application controls through the appropriate mappings. You maintain the shared structure while each environment provides its own representation.

JSON, YAML, and TOML are ways to write ARMES documents. ARMES’s foundation is the structure they describe. UI is one application; ARMES can also describe content, configuration, and other structured models.

Use ARMES to:

• Share structure across applications and platforms.
• Configure content and behavior using capabilities your application provides.
• Update centrally stored structures that compatible applications can load.

An application can load its ARMES structure from a server. Updating that structure can change what the application presents or how it behaves without rebuilding it, provided its installed runtime, mappings, and components already support the change.

Contents

• Architecture
• Language
• Installation
• Extend ARMES

Architecture

• Core: connects the parts and provides the library API.
• Parser: reads a document and builds its tree.
• Tree: stores nodes, properties, and children.
• Runtime: evaluates conditions, calculations, imports, and enabled references.
• Mapper: interprets the structure for a destination.
• Emitter: writes a representation as output when needed.

flowchart TD
    Source["JSON / YAML / TOML / ARMES (markup)"] -->|Parse| Tree["ARMES tree"]
    Tree -->|Resolve| Resolved["Resolved structure"]
    Resolved --> Mapper["Configured mapper"]
    Mapper --> Target["Target representation"]
    Target --> App["Application uses it"]
    Target --> Emitter["Emitter writes it"]

Loading

An HTML mapping can lead to HTML text; a React or NativeScript integration can produce components or native views. Those integrations supply their own mappings. The default core does not install platform components.

This is ARMES’s isomorphic approach: one authored structure interpreted for multiple environments. Each environment can present it differently.

Architecture details →

Language

This complete document describes a Save button. JSON is used here to make its keys visible:

{
  "button": {
    "@": { "class": "primary" },
    "#": ["Save"]
  }
}

• button names the node. Its representation depends on the mapper.
• @ defines its properties: class has the value primary.
• # defines its children, in order.
• "Save" is a text child.

With the default HTML target:

<button class="primary">Save</button>

In node positions, normal keys name nodes; colon-prefixed keys such as :if are ARMES commands. Inside @, keys name properties.

• @ defines this node’s properties. Start here.
• :props patches its direct parent’s properties.
• :attributes performs the same patch as :props.

Dynamic expressions can go directly in @; they do not require a patch command.

Language reference →

Every supported key, with examples and rules. Browse Keys, Properties, Logic, Types, Imports, References, and Formats.

Formats shows this same button in YAML, TOML, and ARMES (markup).

Installation

Requirements: PHP 8.2 or later, Composer, and DOM/libxml for markup parsing.

From this package checkout:

composer install

The package is armes-lang/core. For another project, configure its Composer repository before requiring it.

Save as example.php beside vendor/ and run php example.php:

<?php
require __DIR__ . '/vendor/autoload.php';

use Armes\Armes;

$core = Armes::default();
$tree = $core->parseJson(<<<'JSON'
{"button":{"@":{"class":"primary"},"#":["Save"]}}
JSON);
echo $core->renderHtml($tree);
// <button class="primary">Save</button>

• Save source: $core->sourceJson($tree) preserves editable structure and commands.
• Render output: $core->renderHtml($tree) evaluates commands, maps the result, and writes HTML.

Continue to the API guide for application data, loading documents, mapping, and references.

Compact reference reads

$tree = $core->parseJson(
    '{"Widget":{"@":{"value":{":ref":"./data.yaml::$[value]"}}}}',
    '/workspace/main.armes.json',
);
$session = $core->referenceSession($tree, [
    'loader' => new \Armes\Loader\MemorySourceLoader([
        '/workspace/data.yaml' => 'value: 7',
    ]),
]);
$snapshot = $session->resolve();

PHP shares the compact/legacy syntax and inline source contract, typed data/document loading, semantic IDs, keyed/named outputs and demand-driven dependencies. Filesystem loaders require allowed roots. PHP remains synchronous; read data objects are detached from parsed-resource caches. See qs boundaries and migration/host differences. No new directive variants or executable source engines are introduced.