WANTED: command syntax tutorial

Let's say that I have already written a command and now want to specify its syntax. Now what?

In addition to the command syntax documentation ( http://www.jnode.org/node/2549 ), I would like to develop a command syntax tutorial. A tutorial would start with familiar examples and focus on the translation of traditional command line parsing with writing an XML document.

Question: What is the name of the XML document? Is there a naming convention?

Question: Is the command syntax document going to be a resource?

Question: My command expects one argument. How do I specify that this argument is expected to be a valid file name?

Question: My command requires an argument. How do I specify that an argument is required?

Example: Understanding syntax of the cat command

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

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/...


For more information on plug-in descriptors, see also http://www.jnode.org/node/136 .

There is a bug ... but not that one.

In other words, cat a.txt -u http://www.jnode.org/ will display http ://www.jnode.org and then a.txt. Is that right?

The syntax says that there are three variants:

    cat -u <url> ...
    cat <file> ...

A "syntax" element is really treated as an "alternatives" element, with the child nodes as the alternatives.
The example that you give mixing URLs and URLs will match the 3rd alternative, and cause the '-u' and 'http://www.jnode.org/' srgs to be interpreted as pathnames. This is clearly incorrect, but not in the way that you were suggesting.

You could try an experiment to see if I'm right about how the syntax as defined works. The "usage" information displayed by "help cat" will give you some idea of what the syntax means. (Your description should recommend the use of the "help" command as a syntax debugging aid, together with the "syntax" command.) And you could then try running the command and trying to understand the reported errors.

This illustrates one of the problems with the current implementation of the JNode syntax system: the various Argument types match arguments in unexpected ways. It is hard to fault the FileArgument class here, since both '-u' and 'http://www.jnode.org/' are legal JNode pathnames. The real problem is in the syntax ... or maybe that we need variants of FileArgument that match (for example) files that already exist, files with "sensible" names and so on. Fixing things so that interleaved "cat" pathnames and URLs work as you are suggesting is still harder, and may entail a new kind of structured Argument and major surgery to the syntax infrastructure. Clearly more work is needed here ...

BTW, I like this material you are writing, and I'll promote it to a book page when you are done.