jsish
Modules
Not logged in

Overview

A Jsi module is code that:

Here is an example module ./fileSize.jsi:

#!/usr/bin/env jsish
require('Sys'); // Optional
function fileSize(fargs:array|string=void, conf:object=void) {

    var options = { // Count bytes in files
        debug       :false, // Debug output
        max         :10     // Max number of files
    };
    var self = {
        cnt:0
    };
    
    function getLength(fargs:array|string) {
        if (typeof fargs === 'string')
            fargs = [fargs];
            
        for (var i in fargs) {
            if (i>=self.max) break;
            if (self.debug)
                puts('Count: '+fargs[i]);
            self.cnt += File.size(fargs[i]);
        }
        return self.cnt;
    }

    parseOpts(self, options, conf);
    
    if (fargs)
        return getLength(fargs);
        
    self.getLength = getLength; // Return object-command
    return self;
}

provide('fileSize');

if (isMain()) {
    puts(runModule(fileSize));
}

Invoked as:

./fileSize.jsi -debug true file1 file2 file3

Leading switches are passed in conf with the remaining arguments in fargs.

Note that options coming in from the command-line must be primitives.


Sys

The Sys package comprises the scripts zipped to the end of the jsish executable that implement command-line option/utilities such as the debugger and parseOpts.

Sys may be explicitly loaded with:

require('Sys');

However, this is completely optional as the code therein implicitly loads on-demand.


parseOpts

parseOpts processes options from conf, validating them against options, and assigning them to self.

Note that the following special boolean options are always accepted to control logging: Debug, Trace, Test.

From the command-line runModule does the marshalling of arguments.


Programmatic

Calling a module with no arguments causes it to just return self. This allows the it to be called programmatically:

require('fileSize');
var fcmd = fileSize();
fcmd.getLength('Makefile');
fcmd.getLength(['a','b']);
puts(fcmd.cnt);

Sections

The 7 parts of a module are:

Section Description
function All code is wrapped in a function with the same name as the file basename, providing bindings for incoming arguments.
options The var options = object itemizes the all options that can come in via the opts parameter.
self Local object state is stored in the self object. All defined and incoming options will be copied into self.
parseOptsThe call parseOpts(self, options, opts) performs option parsing as well as implementing -h help output
provideThe provide statement makes the module available as a package.
Info.isMain The isMain() command returns true if the current file was the one invoked from the command-line.
runModule The runModule() command parses command-line options and then invokes the current module.

Help

Help is available for a module by calling it with the single argument -h

/fileSize.jsi -h
/home/user/fileSize.jsi:121: error: ... 
OPTIONS FOR 'fileSize.jsi': // Count bytes in files
    -Debug      false   // LogDebug output
    -max        10      // Max number of files

ERROR

Help Limitations

Help information gets extracted from options by parseOpts, with the following limitations: