Parse and return command-line options

Author(s): Manuel Carro.

Usage and interface

Documentation on exports

PREDICATEgetopts/4

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.

PREDICATEcl_option/2

Usage:cl_option(Arguments,Option)

Check that Option is an option in Arguments.

Documentation on internals

REGTYPEspec/1

Usage:spec(Spec)

Spec is AtomName/Arity

    Documentation on imports

    This module has the following direct dependencies: