WANTED: command syntax tutorial

The cat command is a file system command. It is intended for the concatination of files.

Let's say that you have three files a.txt, b.txt and c.txt. To concatinate these three files into one, the command line is cat a.txt b.txt c.txt > d.txt.

Possibly, the most popular usage of the cat command is to concatinate a file to standard output. The result? A file is displayed. The following command displays the d.txt file.
cat d.txt

Example 1
The cat command displays a.txt, and then b.txt and then c.txt.
cat a.txt b.txt c.txt

Example 2
The cat command displays a.txt, and then http ://www.jnode.org/ and then c.txt.
cat a.txt --urls http ://www.jnode.org/ c.txt

Syntax
The command line syntax for the cat command is something like this:

cat ( [ -u | -urls ] file-1 ) [ ... ]

The syntax for the cat command is defined in fs/descriptors/org.jnode.fs.command.xml.

The relevant section of the document is:

   39   <extension point="org.jnode.shell.syntaxes">
   40     <syntax alias="cat">
   41       <empty description="copy standard input to standard output"/>
   42       <sequence description="fetch and concatenate urls to standard output">
   43         <option argLabel="urls" shortName="u" longName="urls"/>
   44         <repeat minCount="1">
   45           <argument argLabel="url"/>
   46         </repeat>
   47       </sequence>
   48       <repeat minCount="1" description="concatenate files to standard output">
   49         <argument argLabel="file"/>
   50       </repeat>
   51     </syntax>

Line 39: "org.jnode.shell.syntaxes" is an extension point for command syntax.

Line 40: The syntax entity represents the entire syntax for a command. The alias attribute is required and associates a syntax with a command.

Line 41: When parsing a command line, the empty tag does not consume arguments. This is a description of the cat command.

Line 42: A sequence tag represents a group of options and arguments, and others.

Line 43: An option tag is a command line option, such as -u and --urls. Since -u and --urls are actually one and the same option, the argLable attribute identifies an option internally.

Line 44: An option might be used more than once on a command line. When minCount is one or more, an option is required.

Line 45: An argument tag consumes one command line argument.

Line 48: When minCount is 1, an option is required.

Line 49: An argument tag consumes one command line argument.

The cat command is implemented in CatCommand.java.

   54     private final FileArgument ARG_FILE =
   55         new FileArgument("file", Argument.OPTIONAL | Argument.MULTIPLE,
   56                 "the files to be concatenated");

This arguments matches line 49 in the XML document (above). The argument is treated as a file name because ARG_FILE is a FileArgument. The argument label is "file". Argument.OPTIONAL and Argument.MULTIPLE are argument control flags. Argument.OPTIONAL means that this argument is optional. Argument.MULTIPLE means that this argument can be use multiple times on one command line.

   58     private final URLArgument ARG_URL =
   59         new URLArgument("url", Argument.OPTIONAL | Argument.MULTIPLE,
   60                 "the urls to be concatenated");

This argument matches line 45 in the XML document (above). The argument is treated as a URL because ARG_URL is URLArgument. The argument label is "url".

   62     private final FlagArgument FLAG_URLS =
   63         new FlagArgument("urls", Argument.OPTIONAL, "If set, arguments will be urls");

This argument matches line 43 in the XML document (above). The argument is treated as a flag because FLAG_URLs is FlagArgument. The argument label is "urls".

   67     public CatCommand() {
   68         super("Concatenate the contents of files, urls or standard input to standard output");
   69         registerArguments(ARG_FILE, ARG_URL, FLAG_URLS);
   70     }

Line 69: When created, the CatCommand registers its three arguments, ARG_FILE, ARG_URL and FLAG_URLS. The registerArguments() method is implemented in AbstractCommand.java.

Note: There seems to be just one tiny insignificant problem with this implementation. The order of the command line arguments will not be preserved. In other words, cat a.txt -u http: //www.jnode.org/ will display http ://www.jnode.org and then a.txt. Is that right?

For more information, see also org.jnode.fs.command.xml - http://jnode.svn.sourceforge.net/viewvc/jnode/trunk/fs/descriptors/org.j... .

CatCommand.java - http://jnode.svn.sourceforge.net/viewvc/jnode/trunk/fs/src/fs/org/jnode/...