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 = {
        package:'fileSize', // Note: "package" is used by Jsi_Conf to support "-h".
        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;
    }

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

provide('fileSize');

if (Info.isMain()) {
    puts(Jsi_Run('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 Jsi_Conf.

Sys may be explicitly loaded with:

require('Sys');

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


Jsi_Conf

Jsi_Conf is the option parser responsible processing options from conf validating them against options, and assigning them to that.

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


Programmatic

Calling a module with no arguments causes it to just return that. 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.
that Local object state is stored in the that object. All defined and incoming options will be copied into that.
Jsi_ConfThe call Jsi_Conf(that, 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 Info.isMain() command returns true if the current file was the one invoked from the command-line.
Jsi_Run The Jsi_Run() 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
/zvfs/lib/JsiUtil.jsi:121: error: throw: 
Count bytes in files

Options/defaults:
    -debug      0       // Debugging level
    -max        10      // Max number of files

ERROR

Help Limitations

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