---

more/io/cmdline.h

Go to the documentation of this file.

//  Copyright (C) 2000--2002  Petter Urkedal (petter.urkedal@matfys.lth.se)
//
//  This file is free software; you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation; either version 2 of the License, or
//  (at your option) any later version.
//
//  This file is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program; if not, write to the Free Software
//  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
//
//  As a special exception, you may use this file as part of a free
//  software library without restriction.  Specifically, if other files
//  instantiate templates or use macros or inline functions from this
//  file, or you compile this file and link it with other files to
//  produce an executable, this file does not by itself cause the
//  resulting executable to be covered by the GNU General Public
//  License.  This exception does not however invalidate any other
//  reasons why the executable file might be covered by the GNU General
//  Public License.
//
//  $Id: cmdline.h,v 1.1 2002/05/30 18:01:37 petter_urkedal Exp $



//  This is a new command-line parser, simplified compared to
//  command.h, but still very general.

//  TODO:
//  * Some way to give specify that options are required and arguments
//  are optional.  One way to to this is to delimit required and
//  optional inserts by a call to some member function (like
//  `cmdl.the_rest_is_optional()').  It is probably better to specify
//  this as a bool arg to the inserters.
//  * Unifty with parsing of resources.
//    `some.resource' refers to `progname.some.resource' in RC file
//    `shortopt.c' is a synonym for `-c'
//    `longopt.name' is a synonym for `--name'
//  Alternatively, we call the above `r:some.resource', `s:c' and `l:name'.
//  Or, `r.some.resource', `s.c', `l.name'.
//  * An option argument to the ctor, allow ignoring unparse args
//  * Maybe implement insert_passthrough(std::string, std::string)
//  * If the user overrides --help, this shall not be treated specially.

#ifndef MORE_IO_CMDLINE_H
#define MORE_IO_CMDLINE_H


#include <iostream>
#include <functional>
#include <map>
#include <list>
#include <more/gen/closure.h>
#include <stdexcept>
#include <string>
#include <cstdlib>


namespace more {
namespace io {

  template<typename T>
    struct cmdline_arg_parser
        : std::unary_function<std::istream&, void>
    {
        cmdline_arg_parser(T& x, bool& ntf)
            : m_x(x), m_notify(ntf) {}

        void operator()(std::istream& is)
        {
            if (is >> m_x)
                m_notify = true;
        }

      private:
        T& m_x;
        bool& m_notify;
    };

  template<>
    struct cmdline_arg_parser<std::string>
        : std::unary_function<std::istream&, void>
    {
        cmdline_arg_parser(std::string& x, bool& f)
            : m_x(x), m_notify(f) {}
        void operator()(std::istream& is);

      private:
        std::string& m_x;
        bool& m_notify;
    };

  template<typename T>
    struct cmdline_setter : std::unary_function<std::istream&, void>
    {
        cmdline_setter(T& x, T const& v) : ref(x), value(v) {}
        void operator()(std::istream& is) { ref = value; }

      private:
        T& ref;
        T value;
    };

  template<typename T, typename OutputIterator>
    struct cmdline_copier : std::unary_function<std::istream&, void>
    {
        cmdline_copier(OutputIterator it) : m_it(it) {}

        void operator()(std::istream& is)
        {
            T x;
            is >> x;
            *m_it = x;
            ++m_it;
        }

      private:
        OutputIterator m_it;
    };


  /** \class cmdline cmdline.h more/io/cmdline.h
   **
   ** A command line parser.  Make sure to catch the \c relax
   ** exception.  If you need to take control of the <tt>--help</tt>
   ** option, you may alternatively detect it before calling \c parse
   ** and possibly call \c print_help within your own help printing
   ** code.
   **
   ** The following environment variables are handled by
   ** <tt>cmdline::parse</tt> and causes <tt>set_tslang</tt> to be called
   ** on the standard output streams.
   ** <ul>
   **   <li><tt>MORE_IO_MARKUP</tt> is the default markup language to use</li>
   **   <li><tt>MORE_IO_COUT_MARKUP</tt> overrides the ML for stdout.</li>
   **   <li><tt>MORE_IO_CERR_MARKUP</tt> overrides the ML for stderr.</li>
   ** </ul>
   ** Also, if <tt>MORE_IO_CMDLINE_ASSIGN</tt> is set to <tt>true</tt>
   ** or is unset <tt>parse</tt> accepts assignment style long-options
   ** without the “<tt>--</tt>” prefix, and if it is set to <tt>false</tt> the
   ** “<tt>--</tt>” prefix is required. */
  struct cmdline
  {
      typedef std::size_t size_type;
      typedef gen::unary_closure<std::istream&, void> closure_type;

      typedef unsigned int flag_type;
      static flag_type const enable_assignment_style = 1;
      static flag_type const disable_assignment_style = 2;

    private:
      typedef std::map<std::string, closure_type> opt_map_type;
      typedef std::list<closure_type> arg_list_type;
      typedef std::list< std::pair<std::string, std::string> > opt_doc_type;
      typedef std::list< std::string > arg_doc_type;

    public:
      /** An exception thrown when the command line options are
       ** ill-formed.  You should catch it and exit the program with
       ** non-zero status. */
      struct failure : std::runtime_error
      {
          failure(std::string const& what_)
              : std::runtime_error(what_+" (Try `--help'.)") {}
      };

      /** An exception thrown when the user has requested help.
       ** This is not an error, and you have to catch this exception
       ** and exit the program with status 0.  You may print
       ** additional help in the catch block. */
      struct relax : std::exception
      {
          relax(std::string const& what_) : msg(what_) {}
          virtual ~relax() throw() {}
          virtual const char* what() const throw() {
              return msg.c_str();
          }
        private:
          std::string msg;
      };

      /** Construct the parser. */
      explicit cmdline(flag_type fl = 0);

      /** Insert an option which will call \a f with its argument.
       ** This is the general form.  */
      template<typename UnaryFunction>
        void insert_functional(std::string const& opt,
                               std::string const& doc, UnaryFunction f)
        {
            priv_insert(opt, doc, closure_type(f));
        }

      /** Insert an option which will set \a x to its argument. */
      template<typename T>
        void insert_reference(std::string const& opt,
                              std::string const& doc, T& x,
                              bool& notify = null_notify)
        {
            notify = false;
            priv_insert(opt, doc,
                        closure_type(cmdline_arg_parser<T>(x, notify)));
        }

      /** Insert an option which takes no arugment and causes
       ** <tt>x=v</tt>. */
      template<typename T>
        void insert_setter(std::string const& opt,
                           std::string const& doc, T& x, T const& v)
        {
            priv_insert(opt, doc, closure_type(cmdline_setter<T>(x, v)));
        }

      /** Insert a reader which will copy each argument to \a opt to
       ** \a it. */
      template<typename T, typename OutputIterator>
        void insert_copier(std::string const& opt,
                           std::string const& doc, OutputIterator it)
        {
            priv_insert(opt, doc,
                        closure_type(cmdline_copier<T, OutputIterator>(it)));
        }

      /** Make the remaining arguments optional. */
      void optional()
      {
          n_required = arg_list.size();
      }

      /** Parse (\a arg, \a argv) as given to \c main. */
      void parse(int argc, char** argv);

      /** Print the documentation for the options.  This is done
       ** automatically when the <tt>--help</tt> option is given,
       ** provided you catch \c relax. */
      void print_help(std::ostream&) const;

      /** Return \c argv[0] as passed to \c parse. */
      static std::string const& program_name() { return prgname; }

    private:
      void priv_insert(std::string const&, std::string const&,
                       closure_type);
      opt_map_type      opt_map;
      arg_list_type     arg_list;
      opt_doc_type      opt_doc;
      arg_doc_type      arg_doc;
      int               n_required;
      flag_type         m_flags;

      static bool null_notify;
      static std::string prgname;

      // Common options
    public:
      static int verbose() { return s_opt_verb; }
      static int debug() { return s_opt_debug; }
    private:
      static int s_opt_verb;
      static int s_opt_debug;
  };

}} // more::io


#endif

// Local Variables:
// coding: utf-8
// End:

---