cla repl - Command-line REPL

This is the command-line equivalent of the Clarive REPL. It allows (an administrator) user to gain direct access to the Clarive Core runtime and run ad-hoc instructions in ClaJS or Perl.

To start the REPL you have to connect to a config, as in:

cla repl -c myconfig

This is necessary, as the REPL will connect to a database and start the Clarive runtime.

The prompt

Once the REPL starts, a prompt is shown indicating the current language and config file used to connect to the database:

js:myconfig> (enter a command here)

Running commands interactively

The command-line REPL keeps full state between calls.

However, when using Perl, variables cannot be declared as my otherwise they will not be available for the next call. They can be just be assigned without declaration ($foo = 123;), since strictures are off. Or they can be declared as our (our $foo = 123;). This is not necessary with JavaScript.

That means declaring a variable in one line will enable it to be used on the next:

# Perl
#   Don't use "my" as in my $doc
#   otherwise state is not kept
$doc = mdb->topic->find_one;  # hit enter here
$doc->{ mid };  # hit enter again

# JS
var doc = db.getCollection('topic').findOne();
doc.mid;

The state will be lost once the REPL is restarted.

You can force reset also by running the command .reset;

Sharing values between languages

To share values between language VMs, use the stash. For instance, set a value in Perl:

# Perl
$stash->{ foo } = mdb->topic->find_one;

Then set the language to JS with .lang js and retrieve the value:

# JS
cla.stash('foo').mid;

The same can be accomplished the other way around, from JS to Perl.

Piping REPL output

All data results from the REPL command go to STDOUT. All internal REPL messages will go to STDERR. This means that you can pipe the output straight into another program using Unix pipes:

cla repl -c myconfig -e 'ci->new(1234)' | grep 'somedata'

Dot-commands

Internal REPL commands start with a dot and can be run in the prompt by entering .COMMAND-NAME:

For example, to set the output format, the correct way to enter the command would be:

js:myconfig> .format json

Also, once in a REPL session, type .help to get help on the available internal commands.

.help

Preloaded JS packages

The JS REPL has some of the key require("cla/*") libraries preloaded. These are available as a global var:

ci = require('cla/ci')
db = require('cla/db')
util = require('cla/util')
config = require('cla/config')

So, there's no need to require() any of these packages as they are available directly with their var name:

ci.load("user-1");
db.getCollection('role');

For modules not loaded by default, just load them as always into a variable:

var web = require('cla/web');
var agent = web.agent();
var query = agent.urlEncode({ foo: 'bar' });
agent.request('GET', 'http://example.com?' + query);

--language perl|js|ts

Sets the interpreter language.

This setting can be changed once in the REPL with the .lang perl or .lang js commands.

Typescript (ts) is actually a transpiled ClaJS environment. Typescript is useful if you want to use recent EcmaScript features mostly, such as:

// undefined/null detection
const user = ci.load('user-1');
print( user?.name() ?? 'not available' );

// destructuring, spreads
const [first, ...arr] = [11,22,33];
const { mid } = db.collection('topic').findOne();
print( mid, first, ...arr );

// template strings
print( `Resulting mid is ${mid}`);

// for...of
for( const it of arr ) {
    print( it );
}

// arrow functions
const fn = mid => ci.load(mid);
print( fn(mid) );

// types!
const name : string = user.name();

// reduce
[111,222].reduce((obj,it) => (obj[it]=it,obj),{});

// and more

--logfile FILENAME

Writes all commands, elapsed time and output returned to a logfile.

It does not, however, write the STDOUT or STDERR console outputs to the file. So if you do a print("hello world") command, it will not print it to the file.

If you want to start the log write session once within the REPL, type:

.log FILENAME

To stop writing to the log file, type:

.close

--format yaml|json|json_pretty|perl

This is the data output format that will be shown in the console.

json_pretty is the same as json, JSON format, but with idented, more readable, output.

perl will output data in Perl data-format.

The format can also be changed on-the-fly within the REPL session:

.format json_pretty

--no-start

This option will start the REPL without starting the entire Clarive runtime (which takes a few seconds to complete).

This is useful if all commands will be run against the DB.

Once in the REPL, if you want to start the runtime, type:

.start

After a few seconds, the runtime commands will be available, such as ci.find(mid) (JS).

-e COMMAND

Instead of starting a REPL session, this will execute the COMMAND passed as argument and exit.

cla repl -c myconfig --no-start --language js -e 'db.getCollection("topic").findOne()'

# Or:

cla repl -c myconfig --language perl -e "mdb->topic->find_one()"

--script FILENAME

Reads the REPL commands from a script file, executes them and exits.

cla repl -c myconfig --script myscript.js