Command line arguments

You can read options from the command line used to run your OmniMark program. See the OmniMark Studio for Eclipse documentation for information on specifying command line options in OmniMark Studio for Eclipse. See the OmniMark Engine documentation for information on specifying command line options with OmniMark Engine.

Command line options starting with a single "-" character followed by one or more letters are reserved for use by the OmniMark Engine. Options specified without a "-" or with a double "-" character will be passed to your OmniMark program on the #args shelf.

You can access items on the #args shelf: 

  process
     local stream input-file-name
     local stream output-file-name
     do when number of #args < 2
        output "Not enough command line arguments.%n"
        halt with 2
     done
     set input-file-name to #args[1]
     set output-file-name to #args[2]

You can also repeat over the #args shelf. In the following code, we assume every item named on the command line is a file to be processed: 

  process
     repeat over #args
        submit file #args
     again

Command line options with parameters

You may want to use command line options that have parameters. For instance, you may wish to set the value of an arbitrary item on a shelf from the command line. This requires a three part command line option:

  1. the shelf name
  2. the index of the item to set: 3
  3. the value to be assigned to the item

You can use a "--" prefix on the name of the shelf, to make it clear that it is the first part of a multi-part option. This enables you to write a command line that looks like this: 

  --file-list 3 "foo" hello --file-list 7 "bar"

Here is a program that can read this command line and act appropriately: 

  global stream file-list size 10
  
    process
      local integer i initial {1}
      repeat
         exit when i > number of #args
         do when #args[i] = "--file-list"
            set file-list[#args[i + 1]] to #args[i + 2]
            increment i by 3
         else
            output "Individual item: '" || #args[i] || "'%n"
            increment i by 1
         done
         catch #program-error message msg
            ; handle out-of-range entries
            put #error msg || "%n"
      again
  
     ; now test the shelf
      repeat over file-list
        do when file-list is attached
          output "file-list[%d(#item)] = " || file-list || "%n"
        done
      again

Using the command line given above, this program will output: 

  Individual item: 'hello'
  file-list[3] = "foo"
  file-list[7] = "bar"

Note that there is nothing special about the "--" prefix, it is simply a useful convention for use in multi-part options. You can also use it for single options, if you wish.

Using #main-input

You can also access the command line indirectly using the keyword #main-input. When #main-input is referenced in a program, OmniMark assumes that all the items listed on the command line are file names. It opens all the files and concatenates them into one source which is represented by #main-input.

Note that OmniMark does not open all the files at once and build the source in memory. Rather, each file is opened and read in turn. However, the files are treated as a single continuous source, with no break between files. Thus: 

  process
     submit #main-input
submits all the files named on the command line as a single source, while 
  
  process
     repeat over #args
        submit #args
     again
submits each file in turn in a separate scanning operation.

When processing #main-input, if any of the items on the command line does not resolve to a file name that can be opened, OmniMark will generate an error when it fails to open the file.

Note that options starting in "--" are not exempt from inclusion in #main-input. If you use #main-input, the only options you can include on the command line are input file names. Note, however, that options beginning in "-", and any parameters belonging to those options, are not treated as file names in processing #main-input since these options are not passed to the OmniMark program.

Related Topics