v.4

Malta is ...

a super-simple & handy tool which allows to build on the fly big files editing its separated parts and assembling in one following a main template file. In every involved file you can use variables coming from a json file, or use a value obtained evaluating an expression that involves those variables. Once started every change will trigger the right fresh build.

... plugin based

Everytime malta builds the main file it is possible to start a chain of actions where each action is done by a plugin. The shipped plugins allows for example to transpil es6, coffeescript and typescript, to compile .less, .sass, .pug, .md, to get a .png from an .svg and a lot more.

---

Get started

• installation
• command line
• programmatic
• single mode
• multi mode
• multi destinations
• parameters
• complete example of usage
• microtemplating
• placeholders
• something more about placeholders
• plugins list
• something more about plugins
• write your plugin in 5 minutes
• changelog

---

Installation

If You do not have node installed yet, run:

$ curl https://npmjs.org/install.sh | sh 

then install malta running:

$ [sudo] npm install malta [-g]

---

Command line Usage

Malta can be started from the shell console just passing the right parameters to the malta executable:

$ malta templateFile outDirectory -plugins=... -vars=... -options=...

or

$ malta conf.json

---

Programmatic

To use malta within a javascript file just require it, get a instance, pass a suitable array of parameters to the check function and invoke start.

var Malta = require("malta");
Malta.get().check([
    "templateFile", "outDirectory",
    "-plugins=...", "-vars=...", "-options=..."
]).start(/**
    here You can specify a function which will be called at every build step, with the Malta instance as context and will receive an object containing the current file _name_ and _content_
    eg:
     function (o) {
        console.log('Instance : ', this);
        console.log('File name: ' + o.name);
        console.log('File content: ' + o.content);
     }
*/);

Since version 3.3.3 the start function returns a thenable, so is possible to pass a function through a then call; it will be executed as far as all involved plugins have terminated their job:

Malta_CheckedParams_Instance
.start(/*
    everybuild code, each plugin end, even first plain build
*/)
.then(function (){
    /*
    this code will be executed when ALL plugin terminated the job;
    even in this function the context is the Malta instance running
    */
});

---

Single mode

The purpose of single-mode is just to build one file and in this case there are two mandatory parameters: templateFile and outDirectory

$ malta templateFile outDirectory  [-plugins=...] [-vars=...] [-options=...]

in programmatic this correspond to pass a corresponding array to the check function :

var Malta = require("malta");
Malta.get().check(["templatefile", "outDirectory"]).start();

---

Multi mode

The multi-mode purpose is to launch Malta on more that one build in one command. In this case it takes just one parameter that is the path to a json file which contains for each file the same informations. It uses as key the templateFile path and as value all other parameters space separated. E.g.:

multifile.json:

{  
    "palette.less" : "../../public_html/css -vars=./vars/deploy.json",  
    "common.less" : "../../public_html/css -plugins=malta-less[compress:false] -options=skipPlain=true", 
    "controllers/*.js" : "app/controllers/  -plugins=malta-js-uglify",
    "nested.json" : true 
}  

nested.json is allowed ONLY since v 3.2.4 (malta will not take care about reference loops) where nested.json :

{
    "common.js" : "../../public_html/js -plugins=malta-js-uglify",  
    "lib.js" : "../../public_html/js -plugins=malta-js-uglify"
}

then run

$ malta multifile.json

multi-mode is not available within a script, then the following code will not work:

// ...
Malta.get().check(["multifile.json"]).start();

moreover since 3.0.16 a simple kind of wildcards can be used in the json keys :

{
    "src/controllers/*.js" : "../../public_html/js -plugins=malta-js-uglify"
}

once started, Malta will start/stop on new files that could be added/removed to/from the controllers folder.

---

More destinations for one file.

Since version 3.7.2.0 it is possible to write more files starting from the same template just specifying an array of destinations:

{
    "src/mybook.md" : [
        "dist/uk -plugins=malta-translate[input:\"en\",output:\"it\"]...malta-markdown-pdf -vars=vars_it.json",
        "dist/de -plugins=malta-translate[input:\"en\",output:\"de\"]...malta-markdown-pdf -vars=vars_de.json"
    ]
}

This will produce two different pdf files automatically translated (standing the right placeholder are used passing short English sentences) using the same template and allowing to use different variables on each of them.

---

Parameters

Starting it as command line tool or programmatically the arguments are the same

$ malta templateFile outDirectory [-vars=non_default_vars_path] [-options=options] [-require|plugins=name1(options)[...name2(options)[...]]]

• templateFile
  is the base template used as base file.

• outDirectory
  is the folder where the output files will be written in.

• -vars=non/default/myvars.json
  here is possible to tell Malta to consider a different file for variables (default would be searched as templateFolder/vars.json); if used the path specified must be relative to the execution folder.

• -options=key1:value1,...
  here the following key:values are considered:

  • showPath: boolean (default : true)
    Malta for certain files will prepend the file inclusion with a small comment which will be really helpful when looking in the resulting file one wants to know from which file a particular section comes from. Significant only in xml, svg, js, css, less, scss files.
  • watchInterval : integer (default 1000)
    This is the interval in milliseconds between every check for a modification in one of the involved files.
  • verbose : integer (default : 1)
    0 no console messages 1 default messages 2 verbose messages
  • notifyBuild: boolean (deafult : true)
    Only on MacOS. Use osascript to show a sticky message at each build (verbose has to be > 0).
  • justCopy: boolean (default : false) [from v.3.9.11]
    in case it is simply needed to skip the placeholders replacement, the file is simply copied (but still plugin processes if any)
  • placeholderMode: 'dolla' or 'func' (default 'dolla')
    'func' is used to allow to use the new placeholders [maltaV, maltaF, maltaE] introduced in version 4.0.0

• -plugins=
  Malta is shipped with a number of plugins to do as post-processing job every special task that was done before like compiling less files, packing js, etc... To use one plugin a -require or -plugins argument must be specified when invoking malta and if the plugin allows it, some parameters can be passed to it. On the same file more than one plugin can act serially: a 3dot separated list of elements, one for each plugin with the following structure: plugin-name(key:value,...) will ensure each plugin start only when the previous one has finished his job and it will receive the right filename and content. Whenever some parameters are needed to be passed to the plugin, in case of string value, then You need to pass the string just wrap it into escaped double quotes ".

Something more about plugins

The version 3 of malta aims to simplify any post-processing needed to be done on the composed file. In fact now malta just do the job of creating the big file from the template and all files and variables involved... nothing else, no packing for js, no less/sass compiling, only the clean plain big file. Whatever work is needed afterwards it needs to be done by a plugin. When a plugin myplugin is requested the first place malta will search for it is executionfolder/plugins/myplugin.js then in executionfolder/plugins/myplugin/index.js then plugins/myplugin.js into the local malta package path, otherwise will be searched as a local/global package.

no demon (only multi-mode)

In case the process must end after the first build just prefix with # the template (only in multi-mode). Can be used as well in the nested.json avoiding to watch all files committed to be built by the nested json content.

execute a terminal command (only multi-mode)

Is possible to execute one or more commands using the EXE key in the json file, containing an array of command or a single string for one command :

{
    "EXE" : [
        "mkdir -p app/config app/controllers app/views app/routes",
        "ls -la app"
    ],
    "all other" : "stuff"
} 

Before version 3.7.2 this feature is available only on the main called json, not in a nested one.
Since version 3.7.2 it is possible to specify a EXE section in any nested json.

For example:

{
    "EXE" : [
        "rm -rf dist",
        "mkdir dist"
    ],
    "dist/require.json" : true
}

then dist/require.json can contain something like:

{
    "EXE" : [
        "mkdir dist/js"
    ],
    "src/tpl/main.js" : "dist/js"
}

Another feature introduced since 3.7.2 is the possibility to specify more than one destination directory.

---

Microtemplating (experimental)

Starting from the version 3.5.3 a simple microtemplating functionality is builtin; within the template just use the `` placeholders to set your logic on the template composition (or any involved file):

... all your awesome code here

    ...
    $$fileA.js$$
    ...

    ...
    $$fileB.js$$
    ...

now the Malta rebuild will include the right file depending on the my.config.bool value found on the vars json.

---

Placeholders

Malta uses three kind of placeholders, to be used in the main template or in any file involved (but vars.json)

• $$filePath$$
  filepath is the path to the desired file relative to the templateFile directory; if starts with / then will be relative to the execution folder.

• *$varPath$*
  varPath is the key path for a variable that Malta will search in a vars.json file that should be found in the template folder (or wherever the -vars options indicates)

• $PACKAGE.varpath$
  Starting from v.3.9.0 it is possible to use another placeholder to use anywhere all values contained in the package.json found in the folder where malta has been lanuched. For example assume in the root folder we have a package.json and we would like to use the version and the repository.url within our source. Will be enough to add a special placeholder that contains the path of the value inside the package.json prepended with a PACKAGE. as follows:

  $PACKAGE.name$ 
  // or
  $PACKAGE.repository.url$
  

• !{expression}! expression can contain anything that must be evaluated (eval function is used)

Starting from version 4.0.0 also the following alternative placeholders are available (passing placeholderMode:'func' in the options):

• maltaF('filepath'[, {'passed':2, 'vars': 'hello'}]) // keys must be quoted
• maltaV('varPath'[, fallbackValue])
• maltaE(expression)
  hint about the maltaE: it should not contain ( and ) otherwise will fail, the only allowed parenthesis are those one from maltaV(...), which can still be part of the expression:

// OK
var foo = maltaE(maltaV('my.number.var.is.a.bit.deep') + 5),
    boo = maltaE(Math.pow(2,3) * maltaV(my.num) + 3)

// ERROR
var boo = maltaE(Math.pow(maltaV(my.num), 2) + 3)

---

Something more about placeholders

The $$filePath$$ placeholder can optionally accept simple parameters:

$$triangles.svg{cx:100,cy:100,s:30,rot:30}$$

now within the triangle.svg we can use those vars:

the complete example about triangles can be found here

---

Write Your plugin in 5 minutes

Writing a plugin is extremely easy, just get a look at the sample.js file in the plugins folder or read how to create a plugin

---

Hints

• absolutely use only spaces and/or tabs before and after file placeholders

• one line files (like already minified ones) really slow down the parsing, so the best thing is to avoid the inclusion of minified/packed files.

• to avoid loops Malta stops digging at the tenth nesting level.

Wired vars

There are some placeholders that can be used within any involved file:

• __TIME__ : the HH : MM : SS build time
• __DATE__ : the D / M / YYYY build date
• __YEAR__ : the YYYY format build year
• __FILES__ : the number of files glued together
• __VERSION__ : Malta version
• __BUILDNUMBER__ : build number
• __FILE__ : template name
• __LINE__ : line number

---