Pa_arg syntax extension

CAMLP4 syntax extension offering a special syntax for parsing command-line arguments.

Links

pa_arg has not been updated for ocaml 3.10! You must use the previous version of camlp4!

You can also get the current version of pa_arg via GODI. Here are instructions on using pa_arg with OCamlMakefile.

Documentation

Quickstart

Simple usage can be as easy as the following. If file test.ml contains this:

open Parseopt

type option myOptions = {
  alpha         : int; 
  bravo         : help = "provide a bravo message"; string;
  delta = false : action = set; bool;
  gamma = 3     : action = store 6; int;
  foxtrot       : [ `Ecks | `Why | `Zee ];
}

let () = 
  let options, args = parse_argv myOptions in
  Printf.printf "Received options\n%s\n\n" (myOptions.to_string options);
  print_string options.bravo;


Then this invocation:

test -delta -bravo 'Congratulations, pa_arg user!' -g -f why

prints

  Received options

alpha = None
bravo = Some foobar
delta = true
gamma = 6
foxtrot = why

Congratulations, pa_arg user!

Reference documentation

The options record returned by Parseopt.parse_argv is of type myOptions. which is just like the structure declared, except that options without default values become optional types (e.g. int becomes int option). The syntax extension also declares a value of type myOptions, called myOptions.

The above example demonstrates the use of the action and help parameters to modify the behavior of each option. The following parameters are available.

str=f       f takes an argument of the appropriate type and returns a string
            (otherwise to_string uses string_of_type or "user-specified data")

help=s      s is a help string for this option
            (otherwise the help string is based on the action below)

key=s       s is a list of option keys
            (otherwise the option keys are the formed from the field name.
            By default, a field foobar would have keys -f,-foobar.
            This can be customized by overriding the keyspecs field of 
            myOptions)

The default behavior on seeing an option key is to convert the key's argument (if the option isn't of type unit) to the appropriate return type, and store it in the field. There are three provided ways to modify this behavior. Each of the functions takes as a first argument a record of type (myOptions) action_parameters which stores the current value of the options record, the remaining command-line arguments, and the myOptions structure passed to the Parseopt.parse function.

action=f      f ap should return a value of the appropriate type.
              This indicates that the key does not have an argument.
              This should not be used for actions which do not return.

conversion=f  f ap s parses the single option string s and returns
              a value of the appropriate type.

handler=f     This option takes over parsing the rest of the line.
              f ap must return (options, args).

There are three functions in Parseopt available to any module as a simple action: Parseopt.set, Parseopt.clear and Parseopt.store. See the example for their usage.

The fieldname can be _ in which case an option is still generated, but no field in the record type. Obviously at least the `key' and one of the alternate parse parameters must be provided. Multiple such anonymous fields can be created in a single record.

You can also change some of the behavior of the parsing by modifying the myOptions structure before passing it to Parseopt.parse. See Parseopt.option_parameters.

The type of a field can be given as a polymorphic variant:

type option myOptions = { 
  ...
  foxtrot : [ `Ecks | `Why | `LongNameIDontWantToType "zee" ]
  ...
}

In this case, the valid arguments for the foxtrot option are "ecks", "why", and "zee", producing values of the appropriate type. Note that strings can be provided after a constructor name to offer a concise string to type on the command line. Also, as with all polymorphic variants, the same constructor may be used in multiple fields.

Other information

Author: Eric Breck

Program version: 0.2.3

This file $Revision: 1.8 $