Using Command Line Completion (old syntax mechanism)

Note: this page describes the old syntax mechanism which is currently being phased out. Please refer to the parent menu for the pages on the new syntax mechanism.

The JNode Command Line Completion is one of the central aspects of the shell. JNode makes use of a sophisticated object model to declare command line arguments. This also provides for a standard way to extract a help-document that can be viewed by the user in different ways. Additionally, the very same object model can be used to access the arguments in a convenient manner, instead of doing the 133735th command line parsing implementation in computer history.

The following terms play an important role in this architecture:

  • Parameter
    A key that can be passed to a programm. Typically, this are command line switches like "-h" or "--help", or indicators for the type of the assigned argument.
  • Argument
    A value that can be passed to a program. This can be filenames, free texts, integers or whatever type of arguments the program needs.
  • Syntax
    A program can define multiple Syntaxes, which provide for structurally different tasks it can handle. A Syntax is defined as a collection of mandatory and optional Parameters.

A sample command

The command used in this document is a ZIP-like command. I will call it sip. It provides for a variety of different parameter types and syntaxes.

The sip command,in this example, will have the following syntaxes:


sip -c [-password <password>] [-r] <sipfile> [<file> ...]

sip -x [-password <password>] <sipfile> [<file> ...]

Named Parameters:

  • -c: compress directory contents to a sipfile
  • -x: extract a sipfile
  • -r: recurse through subdirectories

Arguments:

  • password: the password for the sipfile
  • sipfile: the sipfile to perform the operation on
  • file: if given, only includes the files in this list

Declaring Arguments and Parameters

Let's set some preconditions, which will be of importance in the following chapters.

  • we will put the command into the package org.jnode.tools.command
  • the actual java implementation of the packager are found in org.jnode.tools.sip

Therefore, the first lines of out Command class look like this:



package org.jnode.tools.command;



import org.jnode.tools.sip.*;

import org.jnode.shell.Command;

import org.jnode.shell.CommandLine;

import org.jnode.shell.help.*;



public class SipCommand implements Command{



After importing the necessary packages, let's dive into the declaration of the Arguments. This is almost necessarily the first step when you want to reuse arguments. Good practise is to always follow this pattern, so you don't have to completely rework the declaration sometime. In short, we will work above definition from bottom up.

You will note that all Arguments, Parameters and Syntaxes will be declared as static. This is needed because of the inner workings of the Command Line Completion, which has to have access to a static HELP_INFO field providing all necessary informations.



static StringArgument ARG_PASSWORD = new StringArgument("password", "the password for the sipfile");

static FileArgument ARG_SIPFILE = new FileArgument("sipfile", "the sipfile to perform the operation on");

static FileArgument ARG_FILE = new FileArgument("file", "if given, only includes the files in this list", Argument.MULTI);



Now we can declare the Parameters, beginning with the ones taking no Arguments.

Note: all Parameters are optional by default!



// Those two are mandatory, as we will define the two distinct syntaxes given above

static Parameter PARAM_COMPRESS = new Parameter(

"c", "compress directory contents to a sipfile", Parameter.MANDATORY);

static Parameter PARAM_EXTRACT = new Parameter(

"x", "extract a sipfile", Parameter.MANDATORY);



static Parameter PARAM_RECURSE = new Parameter(

"r", "recurse through subdirectories");



static Parameter PARAM_PASSWORD = new Parameter(

"password", "use a password to en-/decrypt the file", ARG_PASSWORD);



// here come our two anonymous Parameters used to pass the files

static Parameter PARAM_SIPFILE = new Parameter(

ARG_SIPFILE, Parameter.MANDATORY);

static Parameter PARAM_FILE = new Parameter(

ARG_FILE);

Wait!

There is something special about the second Syntax, the extract one. The command line completion for this one will fail, as it will try to suggest files that are in the current directory, not in the sipfile we want to extract from. We will need a special type of Argument to provide a convenient completion, along with an extra Parameter which uses it.