Parse and return command-line options

Usage:getopts(Arguments,Opts,Matched,Rest)

Ciao Prolog parses the command-line arguments of its executables and passes them as a list of atoms to the main/1 predicate. Thus, a shell invocation such as

./my_program -file input.txt -file input2.txt --output_file out.txt -create-dir --decode --unsorte

makes main/1 receive an argument such as

['-file', 'input.txt', '-file', 'input2.txt', '--output_file', 'out.txt', '-create-dir', '--decode', '--unsorte']

getopts/4 can be used to parse such an command-line option list. passed in the Arguments parameter. Opts is a list of expected options, each option being an option spec, i.e., a term of the form atom/arity. For every atom a command-line option of the form '--atom' or '-atom' is expected, with arity arguments following it. An arity of zero can be omitted. For each matched option spec, the list Matched will contain a term of the form atom(Arg1, Arg2, ..., Argn), where n = arity. The list Rest will contain the unmatched element in Arguments.

Rest will respect the relative order of the elements in Arguments. The matching elements in Matched appear in the same order as the options in Opts, and for every option in Opts, its matches appear in the order as they came in Arguments.

Assuming Arguments is ['-file', 'input.txt', '-file', 'input2.txt', '--output_file', 'out.txt', '-create-dir', '--decode', '--unsorte'], some possible uses of getopts/4 follow.

• Check that a simple option has been selected:

  ?- getopts(Args, ['create-dir'], M, R).
  Args = ...
  M = ['create-dir'],
  R = ['-file','input.txt','-file','input2.txt','--output_file',
       'out.txt','--decode','--unsorte']

• Which argument was given to an option expecting an additional value?

  1 ?- getopts(Args, [output_file/1], M, R).
  Args = ...
  M = [output_file('out.txt')],
  R = ['-file','input.txt','-file','input2.txt','-create-dir',
       '--decode','--unsorte'] 
  
  1 ?- getopts(Args, [output_file/1], [output_file(F)], R).
  Args = ..
  F = 'out.txt',
  R = ['-file','input.txt','-file','input2.txt','-create-dir',
       '--decode','--unsorte']

• Extract options (and associated values) which can appear several times.

  1 ?- getopts(Args, [file/1], M, R).
  Args = ...
  M = [file('input.txt'),file('input2.txt')],
  R = ['--output_file','out.txt','-create-dir','--decode',
       '--unsorte']

• Was decoding selected?

  1 ?- getopts(Args, [decode], [_], R).
  Args = ...
  R = ['-file','input.txt','-file','input2.txt','--output_file',
       'out.txt', '-create-dir','--unsorte']

• Was encoding selected?

  1 ?- getopts(Args, [encoding], [_], R).
  no

• Was decoding not selected?

  1 ?- getopts(Args, [decode], [], R).
  no

• Are all the options passed to the program legal options? If this is not the case, which option(s) is/are not legal?

  1 ?- getopts(Args, [file/1, output_file/1, 'create-dir', 
                  encode, decode, unsorted], _, R).
  Args = ...
  R = ['--unsorte'] ?

The complexity of getopts/1 is currently O(La x Lo), where La is the length of the argument list and Lo is the length of the option list.

• Call and exit should be compatible with:
  (basic_props:list/2)Arguments is a list of atoms.
  (basic_props:list/2)Opts is a list of specs.
  (basic_props:list/2)Matched is a list of terms.
  (basic_props:list/2)Rest is a list of terms.
• The following properties should hold at call time:
  (term_typing:nonvar/1)Arguments is currently a term which is not a free variable.
  (term_typing:nonvar/1)Opts is currently a term which is not a free variable.

Usage:cl_option(Arguments,Option)

Check that Option is an option in Arguments.

• Call and exit should be compatible with:
  (basic_props:list/2)Arguments is a list of atoms.
  (getopts:spec/1)Option is AtomName/Arity
• The following properties should hold at call time:
  (term_typing:nonvar/1)Arguments is currently a term which is not a free variable.
  (term_typing:nonvar/1)Option is currently a term which is not a free variable.

Usage:spec(Spec)

Spec is AtomName/Arity