[Mod] Formspec AST [formspec_ast]

Post Reply
User avatar
luk3yx
Member
Posts: 68
Joined: Sun Oct 21, 2012 18:14
GitHub: luk3yx
IRC: luk3yx
In-game: luk3yx
Location: Earth
Contact:

[Mod] Formspec AST [formspec_ast]

by luk3yx » Post

formspec_ast

A Minetest mod library to make modifying formspecs easier.

API
  • formspec_ast.parse(formspec_string): Parses formspec_string and returns an AST.
  • formspec_ast.unparse(tree): Unparses the abstract syntax tree provided and returns a formspec string.
  • formspec_ast.register_element('modname:element', function()): Registers a custom element. See [​registering elements] for more information.
  • formspec_ast.interpret(string_or_tree): Returns a formspec string after (optionally parsing) and unparsing the formspec provided.
  • formspec_ast.walk(tree): Returns an iterator (use this directly in a for loop) that will return all nodes in a tree, including ones in side containers.
  • formspec_ast.find(tree, node_type): Similar to walk(tree), however only returns node_type nodes.
  • formspec_ast.get_element_by_name(tree, name): Returns the first element in the tree with the name name.
  • formspec_ast.get_elements_by_name(tree, name): Returns a list of all the elements with the name name.
  • formspec_ast.apply_offset(tree, x, y): Shifts all elements in tree. Similar to container.
  • formspec_ast.flatten(tree): Removes all containers and offsets elements that were in containers accordingly.
  • formspec_ast.show_formspec(player_or_name, formname, formspec): Similar to minetest.show_formspec, however also accepts player objects and will pass formspec through formspec_ast.interpret first.
  • formspec_ast.safe_parse(string_or_tree): Similar to formspec_ast.parse, however will delete any elements that may crash the client (or any I haven't added to the whitelist).
AST

The AST is similar (and generated from) the formspec element list, however all attributes are lowercase.

Special cases
  • formspec_version (provided it is the first element) is moved to tree.formspec_version (1 by default).
formspec_ast.parse example

Note that the whitespace in the formspec is optional and exists for readability. Non-numeric table items in the dump() output are re-ordered for readability.

Code: Select all

> tree = formspec_ast.parse('size[​5,2] '
>>     .. 'style[​name;bgcolor=blue;textcolor=yellow]'
>>     .. 'container[​1,1]'
>>     .. '    label[​0,0;Containers are fun]'
>>     .. '    container[​-1,-1]'
>>     .. '        button[​0.5,0;4,1;name;Label]'
>>     .. '    container_end[​]'
>>     .. '    label[​0,1;Nested containers work too.]'
>>     .. 'container_end[​]'
>>     .. ' image[​0,1;1,1;air.png]')
> print(dump(tree))
{
    formspec_version = 1,
    {
        type = "size",
        w = 5,
        h = 2,
    },
    {
        type = "style",
        name = "name",
        props = {
            bgcolor = "blue",
            textcolor = "yellow",
        },
    },
    {
        type = "container",
        x = 1,
        y = 1,
        {
            type = "label",
            x = 0,
            y = 0,
            label = "Containers are fun",
        },
        {
            type = "container",
            x = -1,
            y = -1,
            {
                type = "button",
                x = 0.5,
                y = 0,
                w = 4,
                h = 1,
                name = "name",
                label = "Label",
            },
        },
        {
            type = "label",
            x = 0,
            y = 1,
            label = "Nested containers work too.",
        },
    },
    {
        type = "image",
        x = 0,
        y = 1,
        w = 1,
        h = 1,
        texture_name = "air.png",
    },
}

formspec_ast.flatten example

Code: Select all

> print(dump(formspec_ast.flatten(tree)))
{
    formspec_version = 1,
    {
        type = "size",
        w = 5,
        h = 2,
    },
    {
        type = "style",
        name = "name",
        props = {
            bgcolor = "blue",
            textcolor = "yellow",
        },
    },
    {
        type = "label",
        x = 1,
        y = 1,
        label = "Containers are fun",
    },
    {
        type = "button",
        x = 0.5,
        y = 0,
        w = 4
        h = 1,
        name = "name",
        label = "Label",
    },
    {
        type = "label",
        x = 1,
        y = 2,
        label = "Nested containers work too.",
    },
    {
        type = "image",
        x = 0,
        y = 1,
        w = 1,
        h = 1,
        texture_name = "air.png",
    },
}
formspec_ast.unparse example

Code: Select all

> print(formspec_ast.unparse(tree))
size[​5,2,]style[​name;textcolor=yellow;bgcolor=blue]container[​1,1]label[​0,0;Containers are fun]container[​-1,-1]button[​0.5,0;4,1;name;Label]container_end[​]label[​0,1;Nested containers work too.]container_end[​]image[​0,1;1,1;air.png]

> print(formspec_ast.unparse(formspec_ast.flatten(tree)))
size[​5,2,]style[​name;textcolor=yellow;bgcolor=blue]label[​1,1;Containers are fun]button[​0.5,0;4,1;name;Label]label[​1,2;Nested containers work too.]image[​0,1;1,1;air.png]
Download

The source code for formspec_ast can be viewed on https://git.minetest.land/luk3yx/formspec_ast (alternate links: GitHub, GitLab), and a direct download is available here.

License

formspec_ast is licensed under the MIT license. You can see the full license here.

Dependencies

This mod has no dependencies.
git_undo() { [ -e .git ] || return 1; local r=$(git remote get-url origin); cd ..; rm -rf "$OLDPWD"; git clone "$r" "$OLDPWD"; cd "$OLDPWD"; }

Post Reply

Who is online

Users browsing this forum: Steamed_Punk and 3 guests