Announcement: User-Defined Nodes

[pml-lang]

PML 2.2 is out - with a new exciting feature called User-Defined Nodes. They allow you to create your own, customized PML nodes (in addition to PML's standard nodes) and use them in your documents. The Changelog lists other minor enhancements.

There is also a new manual titled Advanced PML Features with a chapter dedicated to User-Defined Nodes. In the future, other advanced features will be described in this manual.

Please have a look at it, try it out, and let me know if anything needs to be improved.

[coemgenuslcp]

I am liking it so far. Any plans to have it support (1) nested child nodes in its call, (2) embedded PML in its script definition, (3) persistent state (variables) between instances of it?

[pml-lang]

I am liking it so far.

Thank you. Glad you like it!

support (1) nested child nodes in its call

Yes, this is supported. But you need to explicitly call context.writeChildNodes(), as explained in chapter Scripts (look for list item context/writeChildNodes).

An example of how to call this function can be found in chapter How Does it Work?.

(2) embedded PML in its script definition

Sorry, I don't understand what is meant by "embedded PML in its script definition". Could you explain please, and maybe give an example?

(3) persistent state (variables) between instances of it?

Not supported yet, but soon, when "embedded scripting (ES)" will be available. ES will enable you to read/write text files, persist and extract data from JSON files, PDML files, and even from databases (by calling external programs). ES will make PML much more powerful, and it can be used in the context of user-defined-nodes as well. Implementation of ES is done already, I'm currently working on the docs. Will be available in the next version of PML.

[coemgenuslcp]

Thank you for clarity. I should read thoroughly the chapters, not skim them!

By "embedded PML in the script definition" I mean encapsulating other PML nodes inside the custom node's definition, rather than passing them into the node call. In other words, something like a combination of user-defined node and ins-file:

[- Definition -]
[node
    [name mycustomnode]
    [attributes
        [attribute [name attr]]
    ]
    [writer
        [script
            """
            context.writeInnerPML("
                [othernode (attr = ${attributes.get("attr")})
                    ....
                ]
            ")
            """
        ]
    ]
]

[- Use -]
[doc
    [mycustomnode (attr = "hail")]
]

[- Result is equivalent to -]
[doc
    [othernode (attr = "hail")
        ....
    ]
]

[pml-lang]

embedded PML in the script definition

No, this can't be done with a user-defined node (UDN). The reason is that a UDN's script is executed when the HTML code is generated. That is, after the whole PML code has been parsed already, and its AST verified. Hence a UDN script can only be used to generate target HTML code (or any other target code that might be supported in the future).

However, what you want to achieve will be possible to do with "embedded scripting (ES)" (published soon).

ES will allow you to programmatically write PML code into the document.

Here is an example that will be included in the ES docs:

Suppose you want to insert many icons that all must have the same dimensions, and a border. Using standard PML, the non-DRY code would look like this:

[image source="icon_1.png" width=64 height=64 border=yes]
...
[image source="icon_2.png" width=64 height=64 border=yes]

With ES, you will be able to do this:

[!def
    ~~~
    function icon ( path ) {
        doc.insert ( `[image source="${path}" width=64 height=64 border=yes]` );
    }
    ~~~
]

[!exp icon("icon_1.png")]
...
[!exp icon("icon_2.png")]

Now the code is DRY, and easy to maintain.

The above code expands to:

[image source="icon_1.png" width=64 height=64 border=yes]
...
[image source="icon_2.png" width=64 height=64 border=yes]

You could add more arguments to function icon and do whatever you need to do with them, using the power of a scripting language. For example, you could add argument border_color to dynamically insert inline CSS that defines the color of the icon's border.

[coemgenuslcp]

I hope there is plan for custom nodes that both take input nodes and write their own internal nodes.

I don't understand why we would want to support two disparate features with the same purpose, when there could be only one. From a UX viewpoint, the choice between UDN and ES is confusing to a user, because both sell the same outcome while each is arbitrarily (from the user's viewpoint) missing what the other has. With a UDN you cannot compile code after the compilation phase; with an ES you cannot pass child nodes into a function. Both are technical limitations that shouldn't concern the user of the language.

It also couples the language's required knowledge acquisition by the user to the HTML (or whatever target medium) that the PML compiles to. In my impression, that defeats the purpose of PML, which is to abstract away the target medium so that the user need only think about the source code.

[pml-lang]

I don't understand why we would want to support two disparate features with the same purpose, when there could be only one.

Yes! You're right! There should be only one feature.

I initially planned to add two separate features (one for PDML, and one for PML):

• embedded scripting (ES), which is a PDML feature that can be used in PML too
• user-defined-nodes (UDNs), which is a PML-specific feature

However, now that I've implemented ES and experienced myself how powerful ES is (when I wrote an 'Examples' article that will soon be published), I am confident that ES could also be used to define UDNs.

The following untested-preview-code demonstrates how the example in chapter User-Defined Nodes (Experimental) could possibly be written using ES:

[!script
    ~~~
    PMLNodes.add (
        "ctext",              // node name
        [
            {"name": "fc"},   // attribute fc, no default value
            {"name": "bc"}    // attribute bc, no default value
        ],
        true,                 // it's an inline node
        `                     // script to define HTML output
        const foregroundColor = attributes.get ( "fc" );
        const backgroundColor = attributes.get ( "bc" );

        writer.write ( '<span style="color: ' + foregroundColor + '; background-color: ' + backgroundColor + '; border: 1px solid ' + foregroundColor + '; padding:5px; border-radius: 3px;">' );

        writer.writeChildNodes();

        writer.write ( '</span>' )
        `);
    ~~~
]

...

Some text is [ctext (fc=red bc=yellow) red on yellow]

Some text is [ctext (fc=blue bc=orange) blue on orange]

To make the above code work, the current code implementing UDNs needs to be refactored, and the PML-converter needs to add a script binding (PMLNodes.add) to PDML's ES configuration.

We could also add binding PMLNodes.overwrite to re-define the HTML code generated for a standard PML node, and even PMLNodes.remove to remove/disable standard PML nodes, e.g.:

[!script
    ~~~
    // Overwrite the HTML code generated for 'p' nodes
    PMLNodes.overwrite (
        "p",
        `writer.write ( "<p>" )
            .writeChildNodes()
            .write ( "</p>" );
        `);

    // Remove node 'video'
    PMLNodes.remove ( "video" );
    ~~~
]

However, this still doesn't allow you to define a UDN by generating PML code (as in your example above that uses context.writeInnerPML). When ES is available you can define a function that writes PML code and call this function with an exp (expression) node, e.g.:

[!def
    // write text in bold and italic
    function bi ( text ) {
        doc.write ( `[b [i ${text}]]` );
    }
]

...

Following word is written in bold and italic: [!exp bi ( "foo" )].

Supporting UDNs that generate PML code (instead of target HTML code) should be added too by providing an additional binding to create UDNs that generate PML code. Then we would be able to define UDN bi by generating HTML code or else PML code:

HTML:

[!script
    ~~~
    // define UDN by providing target code
    PMLNodes.addWithTargetCode (
        "bi",                 // node name
        [
            {"name": "text"}  // attribute text
        ],
        true,                 // it's an inline node
        `                     // script to define HTML output
        const text = attributes.get ( "text" );
        writer.write ( "<b><i>" + text + "</i></b>" );
        `);
    ~~~
]

...

Following word is written in bold and italic: [bi foo].

PML:

[!script
    ~~~
    // define UDN by providing PML code
    PMLNodes.addWithPMLCode (
        "bi",                 // node name
        [
            {"name": "text"}  // attribute text
        ],
        true,                 // it's an inline node
        `                     // script to define PML output
        const text = attributes.get ( "text" );
        writer.write ( "[b [i " + text + "]]" );
        `);
    ~~~
]

...

Following word is written in bold and italic: [bi foo].

I will now first publish ES (this week or next week). Then I'll implement and publish PMLNodes.add, so that we can test it out. If we decide that ES is suitable to define UDNs I will mark the current UDN feature as "deprecated - will be removed in a future version".

Note: All code examples above are untested and only used to demonstrate possible future features.

[coemgenuslcp]

Yes, this is supported. But you need to explicitly call context.writeChildNodes(), as explained in chapter Scripts (look for list item context/writeChildNodes).

It appears to not support block nodes. For example,

[mycustomnode [quote Insert proverb here.]]

yields this error:

Node 'mycustomnode' defined at ... cannot contain block nodes. It can only contain inline nodes. But 'quote' is not an inline node (it is a block node).

[pml-lang]

It appears to not support block nodes.

True. The current experimental implementation of UDNs only supports inline nodes (but I forgot to mention this in the docs).

Block nodes will be added later.

See also: #68 (reply in thread)