Namby Pamby Magicians

    kroked

    0.1.5 • Public • Published

    kroked

    Markdown with macros.

    It defines :

    • a meta-language parsed by marked lexer/parser
    • a proposition of language based on this meta-language

    See marked for config and basics usage.

    If you want to play with the meta language : see meta-language

    kroked macros language

    substitution macros

    The replace_macro simply looks in options if there is a 'context' property. It seeks in it after property pointed by path provided between macros boundaries (i.e. {{ my.path.from.context }}) and returns it.

    var kroked = require("kroked/index");
    kroked("{{ address.zip }}", { context:{ address:{ zip:"1190" }}})

    will return '1190'.

    Block macros

    With :

    kroked.directives.myDirective = function(args, content, options)
    {
        return args[0] + " : " + content.toUpperCase();
    };

    and this :

    {% myTag myDirective( hello world )
        My content...
    %}
    
    

    It will output : <myTag>hello world : MY CONTENT...</myTag>

    There is three things important to know :

    • either the directive name reflects a directive defined in kroked.directives, and it will be used to render the macros. (see below to defining such macros)
    • either the directive name is "unknown" (there is no associated directive in kroked.directives), and then kroked produce a tag with the name of the unknown directive. (i.e. <myDirective>content</myDirective>)
    • directives are composed together, from right to left.

    And obviously blocks could be embedded in other blocks, and blocks could contains any other macros rules.

    Difference between parsed and raw block-macros

    Remarque : It comes from meta language itself.

    {% myTag
    __this is strong__ @.myOtherTag( my content )
    %}
    

    output : <myTag><strong>this is strong</strong><myOtherTag>my content</myOtherTag></myTag>

    {! myTag
    __this is strong__ @.myOtherTag( my content )
    !}
    

    output : <myTag>__this is strong__ @.myOtherTag( my content )</myTag>

    Compilation and reusability

    Another addition to marked parser is that you could now compile markdown documents to reuse it several times.

    var kroked = require("kroked/index"); // load kroked : contains language definition
    var template = kroked.compile(" {{ name }} says : @.hello(world)");
    template({ name:"John" });
    // will output <p>John says : <hello>world</hello></p>

    Table parsing.

    You could combine raw macros and a small tab-delimitted-cells-lines-lexer to produce quickly any "table like" widgets.

    {! table ( Nodejs specifics deepjs libraries )
    autobahnjs		(restful thin server : middlewares (expressjs) + routing)
    
    deep-shell		(sh & ssh chains and cli)
    
    deep-nodejs		(nodejs related tools (restful fs, ...))
    deep-mongo		(restful mongodb client)
    deep-elastic  	(restful client : ok, index management : embryonnar, layered queries : to do)
    
    deep-mail		(mails sender utilities)
    !}
    
    kroked.directives.table = function(args, content, options){
        var lines = kroked.parseLinesCells(content, false);
        var output = "<table>\n";
        if(args && args[0]) // args[0] === table caption
            output += "<caption>"+args[0]+"</caption>\n";
        lines.forEach(function(cells){
            if(!cells.length)
            {
                output += "<tr></tr>\n";
                return;
            }
            output += "<tr>\n";
            cells.forEach(function(cell){
                output += "<td>"+cell+"</td>";
            });
            output += "\n</tr>\n";
        })
        output  += "</table>\n";
        return output;
    }

    Meta-language

    Remarque : "Block" and "inline" refer to concepts related to markdown. A "block" start line without any spaces (or tabulations), as heading (i.e. # this is title), and couldn't be mixed with other on the same line. For inline object, the line could start with spaces, could contains several lexems, and the line and its following (not blank) are wrapped by a paragraph (p tag).

    See marked for basics concepts.

    Block macros

    block macro (with parsed content)

    {% myDirective(arg1, ...) mySecondDirective(arg, ...) myThirdDirective ...
        any content that will be parsed before injection in block (so any markdown or macros will be parsed).
    %}
    

    raw macro (content are not parsed)

    {! myDirective(arg1, ...) mySecondDirective(arg, ...) ...
        any content that will be kept "as this" (raw) before injection in block
    !}
    

    direct macro.

    When use in front of line (i.e. should start line without spaces or tabulations), any following string until end of line will be used as content.

    @.myDirective(arg, ...) content...

    substitution macro

    {{ theVar.to.be.substitute }}

    Inline macros

    direct macro

    @.myDirective(arg, ..., content)

    substitution macro

    {{ theVar.to.be.substitute }}

    Directives format

    Any directive could have parenthesis with arguments. Parenthesis and args are optional.

    e.g: hello or hello() or hello(arg, ...) are valid.

    Any argument could be string (e.g. "something..."), float, integer or direct string (delimitter is '\n' or ')' or ',')

    e.g. : myDirectives("my string...", 12, 34.890, this is a direct string)

    Defining a language

    By using the custom marked parser directly (kroked/lib/marked.js), you could define a language, based on this macros meta-language.

    For this, you simply define 3 render methods that receive the directive(s), the eventual content and the options provided while parsing.

    examples with "kroked/lib/directives-parser":

    var marked = require("kroked/lib/marked"), // load custom marked parser (no macros language defined)
        renderer = new marked.Renderer();
     
    renderer.block_macro = function(directives, content, options) {
        // directives is array : [{ name:"myDirective", args:[...] }, ...]
        // content is the one provided between macros boundaries (or after block direct macros)
        // options is an object that you provide when parsing
     
        return "<div>"+JSON.stringify(directives)+" - "+content+"<div>";
    };
    //________________________________________________________________________ DIRECT MACRO
    renderer.inline_macro = function(directive, options) {
        // directive is a single directive : { name:"myDirective", args:[...] }
        // options is an object that you provide when parsing
        
        return "<div>"+JSON.stringify(directives)+"<div>";
    };
    //_________________________________________________________________________ REPLACE MACRO 
    renderer.replace_macro = function(content, options) {
        // content is the one provided between macros boundaries
        // options is an object that you provide when parsing
     
        return "<div>"+content+"<div>";
    };
     
    var opt = {
        renderer: renderer,
        gfm: true,
        tables: true,
        breaks: false,
        pedantic: false,
        sanitize: false,
        smartLists: true,
        smartypants: false,
     
        codespaces:false // disable markdown rules : every line starting with 4 spaces (or more) or tab(s) are code
    };
     
    kroked("# hello\n\n{{ to.replace }}", opt);
     

    Remarque

    The language and the meta-language proposed there is a base for future reflexions. It is already fully usable, but as it wants to be opened, lot of things are possible... If you want to contribute, you're welcome...;)

    Licence

    LGPL 3.0

    Keywords

    none

    Install

    npm i kroked

    DownloadsWeekly Downloads

    6

    Version

    0.1.5

    License

    none

    Last publish

    Collaborators

    • nomocas