asko/flatmatter

A flat data serialization language, and library.

v1.0.2 2024-12-08 19:40 UTC

Requires

• php: ^8.4
• crell/fp: ^1.0

Requires (Dev)

• phpunit/phpunit: ^11

MIT

• Asko Nõmm

README

A flat data serialization language, and library. The language aims to be YAML-like, but instead of nesting with indentation, it nests data with punctuation. Additionally, it supports boolean functions to manipulate data which can also be piped.

Install

composer require asko/flatmatter

Usage

The most basic example looks like this:

use Asko\FlatMatter\FlatMatter;

$config = file_get_contents('config.flatmatter');
$parsed = (new FlatMatter($config))->toArray();

But, in order to add functions to FlatMatter, you need to add classes that implement the Asko\FlatMatter\FlatMatterFunction interface to the functions property, like so:

use Asko\FlatMatter\FlatMatter;

$config = file_get_contents('config.flatmatter');
$fm = new FlatMatter($config);
$fm->functions = [new MyFunction];
$parsed = $fm->toArray();

Creating functions

Like mentioned above, functions in FlatMatter have to extend the Asko\FlatMatter\FlatMatterFunction interface, like so:

use Asko\FlatMatter\FlatMatterFunction;
use Asko\FlatMatter\Name;

#[Name('test')]
class TestFn implements FlatMatterFunction
{
    public function compute(...$args): mixed
    {
        if (!empty($args)) {
            return $args[0];
        }

        return null;
    }
}

And, like you can see from the example, you need to also attribute the class with the Name attribute so that the parser would know what class the function name used in the language corresponds to.

Specification

This is just the PHP port of FlatMatter, but I do encourage anyone who wants to port it to whatever language they want.

Example FlatMatter file:

some-var: "some value"
some-int: 12345
some.nested.value: "...."
some-var-using-boolean-fn: (boolean-fn "some-value")
some-var-using-threaded-boolean-fns: "some-value" / boolean-fn / (another-fn "some-arg")

This should create a data structure that looks like this in JSON:

{
  "some-var": "some value",
  "some-int": 12345,
  "some": {
    "nested": {
      "value": "...."
    }
  },
  "some-var-using-boolean-fn": "[result of boolean-fn function]",
  "some-var-using-threaded-boolean-fns": "[result of \"some-value\" piped into boolean-fn, piped into another-fn function]"
}

Built-in functions are up to the library implementor to make, and I don't think there should be any spec on mandatory functions. Ultimately the goal is for the user to define their own functions that they then pass to the library.

Threading is done using the / separator so that we could use YAML syntax highlighting and / passes as a valid value. Threading is always done with the value going as the first argument of a function, so if you pass any additional arguments in the threading, the computed result of the previous threading goes first, so in the above case it would work like this:

1. "some-value" is the initial value
2. It gets passed to the boolean-fn as the first (in this case only) argument
3. The result of boolean-fn gets then passed as the first argument to another-fn
4. another-fn also takes in a second argument "some-arg"
5. The result of all this compute becomes the value of the var.