Skip to content

The Clarive JavaScript DSL

Accessing the powerful Clarive functionality from the JS DSL starts with the cla singleton object:

These are the top-level namespaces available:

  • cla - top level namespace and shortcuts to other often used utilities
  • cla/ci - CI Resource manipulation
  • cla/console - JavaScript console object
  • cla/db - MongoDB database manipulation
  • cla/log - Logging
  • cla/fs - Filesystem manipulation
  • cla/path - File path manipulation
  • cla/rule - Rule manipulation
  • cla/sem - Semaphores
  • cla/t - Testing
  • cla/util - Generic utilities
  • cla/web - Web tools
  • cla/ws - Webservice rule Request/Response

More namespaces may be available to the developer as they can be added by require() modules.

Cla functions

The Cla namespace encapsulates all classes, singletons and functions provided by Clarive's JS API.

Most useful functions are at a lower level of nesting in the namespace, but many common utility functions are provided as direct properties of the Cla namespace.

Many applications are initiated with Ext.application which is called once the DOM is ready. This ensures all scripts have been loaded, preventing dependency issues. For example:

cla.stash()

Gets and sets data in and out of the current stash.

cla.stash("filename", "/tmp/file.txt");
print( cla.stash("filename") );

// it also supports nested data structures with JSON pointers
cla.stash("/domain/filename", "/tmp/file.txt");
print( cla.stash("domain.filename") );

To read or set data in nested levels, Clarive implements a subset of the standard ISO JSON pointers:

  • /foo/bar - get/sets the key stash.foo.bar
  • //foo/bar - turns off pointers, get/sets the key stash["/foo/bar"]
  • foo/bar - not a pointer if it doesn't start with a forward slash /, so it get/sets the key stash["foo/bar"]
  • /foo/0 - get/sets the key stash["foo"][0] from an array
  • /foo/0/bar - get/sets the key stash["foo"][0]["bar"] from an object within an array

cla.config()

Gets and sets configuration data into the Clarive config system.

The config system in Clarive is built through the combination of 3 layers of values:

  • From the current and global environment files (clarive.yml, env.yml)
  • Command-line parameters when starting the server
// gets the value from workers in the clarive.yml file
var wks = cla.config("workers");

// our current database name
var dbname = cla.config("/mongo/dbname");

This is useful for creating site specific .yml files and putting your automation configuration in there.

cla.configTable()

Gets and sets configuration data from/to the config table.

The config system in Clarive is built through the combination of 3 layers of values:

// gets the value from workers in the clarive.yml file
var gitHome = cla.configTable('config.git.home');

The config table is a flat table with values separated with dots ., such as config.git.home.

This is also useful for creating administrator modifiable global configuration values that can be easily changed without editing the rule, although in general, it's better to use variables (CI) for that.

cla.parseVars(target,data)

This function replaces Clarive variables (${varname}) in strings or any nested data structure, such as arrays and objects. The values for the variables will come either from the data argument or the stash.

cla.stash("foo", 99);
var txt = cla.parseVars("This is feet"); // This is 99 feet

cla.stash("name", "Haley");
var txt = cla.parseVars("Hello ${name}", { name: "Joe" });  // Hello Joe

cla.printf(fmt,args)

Prints a string formatted by the usual printf conventions of the C library function sprintf.

var fs = require('cla/fs');
cla.printf("This file is %d bytes long", fs.stat("/tmp/myfile").size );

cla.sprintf(fmt,args)

Returns a string formatted by the usual printf conventions of the C library function sprintf.

var fs = require('cla/fs');
var msg = cla.sprintf("This file is %d bytes long", fs.stat("/tmp/myfile").size );
print( msg );

cla.dump(data)

Prints the data in a data structure using the YAML format.

cla.loc(lang,str,args)

Locate the text string using the I18N format for the language specified in the lang string. This function uses the Clarive I18N translation files.

var jobNum = 1234;
var msg = cla.loc("es","Job %1 started", jobNum );
print( msg );

cla.lastError()

Returns the last error in a string.

print( cla.lastError() );

cla.fork( (resolve, reject) => { ... })

Runs a function in the background. This is experimental and may fail for some edge cases.

ClaJS does not have an event loop. The forked function will run in the background undefinitely until it calls either resolve or reject.

    const prom = cla.fork( function(resolve,reject) {
        resolve("we are done here");
    });

The forked function will start immediately upon calling cla.fork() while asynchronously returning an object, analogous to a JS Promise, which has the following methods:

  • prom.result() - returns undefined if the child process is still running, or an object containing { resolve: VALUE } if successful or { reject: VALUE } if rejected.

  • prom.await() - returns the same values as result() but blocks until the child is completed.

  • prom.pid() - returns the numeric PID, or process id, of the underlying OS process.

  • prom.id() - returns the message id that uniquely identified this child.

"use transpiler(typescript)";
const util = require('cla/util');
const proms=[];

for( let i=0; i<4; i++ ) {
    var prom = cla.fork( (resolve,reject) => {
       if( i % 2 ) {
           res(["job-" + i]);
       }
       else {
           rej('fail-' + i);
       }
    });
    proms.push(prom);
}

console.log("....working normally while the children run...");

for( const prom of proms ) {
    const res = prom.await();  // blocks until done
    if( res.reject ) {
        throw res.reject;
    }
    else {
        console.log("Child is done=" + prom.resolve );
    }
}

console.log(proms.map( it => it.result() ));