#command-line-names

A built-in, global, unkeyed, read-only stream shelf used to access file names from the command line.

All words on the command line are recognized as either "names", command-line options, or errors. Only command-line names are placed in the #command-line-names shelf. The shelf contains any "words" on the command line not recognized as OmniMark command-line options. The following are the rules for distinguishing command-line names from command-line options:

1. Any exisiting OmniMark command-line option and its arguments are considered to be command-line options.
2. Any argument that begins with a single dash ("-") is reserved for future command-line options; the argument will be treated as an error. A word that begins with two dashes ("--") is recognized as a name.

If no words on the command line are recognized as names, the #command-line-names shelf has no items.

Variables initialized on the command line are often referred to as "command-line arguments" (such as a stream value set using "-d"). These are different from the names on the #command-line-names shelf. Command-line arguments are entered on the command line with an identification of the global shelf for which they set parameters, while the #command-line-names shelf is the set of "unrecognized" names on the command line.

#command-line-names is available to all types of OmniMark programs. It can be used to control input to process programs and cross-translations.

You can use #command-line-names to explicitly process the arguments on the command line. This allows you to:

• Save the name of the file being processed for use in programmer-generated messages.
• Avoid automatic file processing. This is especially useful for process programs or programs that use an external-text-entity #document rule to provide the text of the SGML document entity to be parsed.
• Retrieve the names of all files that will be or have been processed. This can speed up processing. By immediately checking for files named in the command line that do not exist, the program can quickly notify the user of "mistakes" in the command line.
• Provide a custom interface to the program; for example, some of the command-line names can represent options the program can recognize, others may name files to be processed.

The following example demonstrates how #command-line-names enables you to have names on the OmniMark command line interpreted as the URLs for HTML documents. The external-text-entity #document rule uses submit to make sure that find rules can be used to convert the HTML into appropriately conforming SGML. An externally defined "source" function called get-url is assumed to be available for getting the text of the HTML files via the Internet.

  context-translate

  external-text-entity #document
     repeat over #command-line-names
        submit get-url ("http://" || #command-line-names)
     again