// doc/parse_options.dox
  
  
  // Copyright 2009-2011 Microsoft Corporation
  
  // See ../../COPYING for clarification regarding multiple authors
  //
  // Licensed under the Apache License, Version 2.0 (the "License");
  // you may not use this file except in compliance with the License.
  // You may obtain a copy of the License at
  
  //  http://www.apache.org/licenses/LICENSE-2.0
  
  // THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  // KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED
  // WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,
  // MERCHANTABLITY OR NON-INFRINGEMENT.
  // See the Apache 2 License for the specific language governing permissions and
  // limitations under the License.
  
  namespace kaldi {
  /**
     \page parse_options Parsing command-line options
  
     \section parse_options_introduction Introduction
     
     The class ParseOptions handles the parsing of command-line options given
     to %main() via argc and argv.  First we give an example of how we invoke
     a typical Kaldi program from the command-line:
     \verbatim
     gmm-align --transition-scale=10.0 --beam=75 \
         exp/mono/tree exp/mono/30.mdl data/L.fst \
         'ark:add-deltas --print-args=false scp:data/train.scp ark:- |' \
          ark:data/train.tra ark:exp/tri/0.ali
     \endverbatim
     The command-line options, which only have a long form (there are no one-letter
     options), must appear before the positional arguments.  In this case there are
     six positional arguments, starting from \c "exp/mono/tree"; notice that the
     one starting with \c "ark:add-deltas" is a single string with spaces in it;
     the single-quotes get interpreted by the shell; this argument gets invoked
     as a pipe.
  
    \section parse_options_example Example of parsing command-line options
  
     We will illustrate how these options get handled at the C++ level by
     introducing some of the code from gmm-align.cc (we have modified
     it slightly to make it clearer):
  \code
  int main(int argc, char *argv[])
  {
    try { // try-catch block is standard and relates to handling of errors.
      using namespace kaldi;
  
      const char *usage =
          "Align features given [GMM-based] models.
  " 
          "Usage: align-gmm [options] tree-in model-in lexicon-fst-in feature-rspecifier "
          "transcriptions-rspecifier alignments-wspecifier
  ";
  
      // Initialize the ParseOptions object with the usage string.
      ParseOptions po(usage);
  
      // Declare options and set default values.
      bool binary = false;
      BaseFloat beam = 200.0;
      // Below is a structure containing options; its initializer sets defaults.
      TrainingGraphCompilerOptions gopts;
  
      // Register the options with the ParseOptions object.
      po.Register("binary", &binary, "Write output in binary mode");
      po.Register("beam", &beam, "Decoding beam");
      gopts.Register(&po);
  
      // The command-line options get parsed here.
      po.Read(argc, argv);
  
      // Check that there are a valid number of positional arguments.
      if(po.NumArgs() != 6) {
        po.PrintUsage();
        exit(1);
      }
  
      // The positional arguments get read here (they can only be obtained
      // from ParseOptions as strings).
      std::string tree_in_filename = po.GetArg(1);
      ...
      std::string alignment_wspecifier = po.GetArg(6);
  
      ...   
    } catch(const std::exception& e) {
      std::cerr << e.what();
      return -1;
    }
  }
  \endcode    
  The code above is mostly self-explanatory.  In a normal Kaldi program, the sequence
   is as follows:
    - You initialize the ParseOptions object with the usage string.
    - You declare, and set default values for, the optional arguments (and options
      structures).
    - You register the command-line options with the ParseOptions object
       (options structures have their own Register functions that do the same
       for all the variables they contain).
    - You do "po.Read(argc, argv);" [This will exit the program if invalid options were given]
    - You check that the number of positional options \c po.NumArgs() is in
      the valid range for your program.
    - You obtain the positional arguments with \c po.GetArg(1) and so on; for
      optional positional arguments that may be out of range, the convenience
      function \c po.GetOptArg(n) returns the n'th argument, or the empty
      string if n was out of range.
    
  Typically when writing a new command-line Kaldi program, it will be easiest
  to copy an existing one and modify it.
      
   \section parse_options_implicit Implicit command-line arguments
  
  Certain command-line options are automatically registered by the ParseOptions
  object itself.  These include the following:
     -  \c --config  This option loads command-line options from a config file.
          E.g. if we do --config=configs/my.conf, the file \c my.conf might
         contain:
  \verbatim
        --first-option=15  # This is the first option
        --second-option=false # This is the second option
  \endverbatim
     - \c --print-args  This boolean option controls whether the program prints the
        command-line arguments to the standard error (default is true); 
        \c --print-args=false will turn this off.
     - \c --help This boolean argument, if true will cause the program to print out a usage
          message (like other boolean arguments, just \c --help counts as true).  You 
          can usually get the usage message just by omitting all command-line arguments, because most
          programs require positional arguments.
     - \c --verbose This controls the verbose level, so that messages logged with KALDI_VLOG
          will get printed out.  More is higher (e.g. --verbose=2 is typical).
     
  */
  
  }