(** Command line *)

(* This module is a wrapper around the ~Getopt~ library and helps to
 * define command-line arguments.
 *
 * Here is an example of how to use this module.
 * First, define the specification:
 *
 *    let open Command_line in
 *    begin
 *      set_header_doc (Sys.argv.(0) ^ " - One-line description");
 *      set_description_doc "Long description of the command.";
 *      set_specs
 *        [ { short='c'; long="check"; opt=Optional;
 *            doc="Checks the input data";
 *            arg=Without_arg; };
 *
 *          { short='b' ; long="basis" ; opt=Mandatory;
 *            arg=With_arg "<string>";
 *            doc="Name of the file containing the basis set"; } ;
 *
 *          { short='m' ; long="multiplicity" ; opt=Optional;
 *            arg=With_arg "<int>";
 *            doc="Spin multiplicity (2S+1). Default is singlet"; } ;
 *        ]
 *    end;
 *
 * Then, define what to do with the arguments:
 *
 *    let c =
 *      Command_line.get_bool "check"
 *    in
 *
 *    let basis =
 *      match Command_line.get "basis" with
 *      | Some x -> x
 *      | None -> assert false
 *    in
 *
 *    let multiplicity =
 *      match Command_line.get "multiplicity" with
 *      | None -> 1
 *      | Some n -> int_of_string n
 *    in
 *    ...
 *)


(* - <<<Short option>>>: in the command line, a dash with a single character
 *   (ex: =ls -l=)
 * - <<<Long option>>>: in the command line, two dashes with a word
 *   (ex: =ls --directory=)
 * - Command-line options can be `Mandatory` or `Optional`
 * - Documentation of the option is used in the help function
 * - Some options require an argument (`ls --ignore="*.ml"`), some
 *   don't (`ls -l`) and for some arguments the argument is optional
 *   (`git --log[=<n>]`) *)


(** Types *)

type short_opt     = char
type long_opt      = string
type optional      = Mandatory | Optional
type documentation = string
type argument      = | With_arg of string
                     | Without_arg
                     | With_opt_arg of string

type description = {
  short: short_opt ;
  long : long_opt  ;
  opt  : optional  ;
  doc  : documentation ;
  arg  : argument ;
}


(** Mutable attributes *)

val set_header_doc : string -> unit
(** Sets the header of the documentation provided by the ~help~ function: *)

val set_description_doc : string -> unit
(** Sets the description of the documentation provided by the ~help~ function: *)

val set_footer_doc : string -> unit
(** Sets the footer of the documentation provided by the ~help~ function: *)

val anonymous : long_opt -> optional -> documentation -> description
(** Creates an anonymous argument. *)


(** Query functions *)

val get       : long_opt -> string option
(** Returns the argument associated with a long option *)

val get_bool  : long_opt -> bool
(** True if the ~Optional~ argument is present in the command-line *)

val anon_args : unit -> string list
(** Returns the list of anonymous arguments *)


(** Specification *)

val set_specs : description list -> unit
(** Sets the specifications of the current program from a list of
 *  ~descrption~ variables. *)