cmd_line_processing.hpp

Go to the documentation of this file.

/******************************************************************************
** Copyright © 2002 by J.M.McGuiness, coder@hussar.me.uk
**
** This library is free software; you can redistribute it and/or
** modify it under the terms of the GNU Lesser General Public
** License as published by the Free Software Foundation; either
** version 2.1 of the License, or (at your option) any later version.
**
** This library 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
** Lesser General Public License for more details.
**
** You should have received a copy of the GNU Lesser General Public
** License along with this library; if not, write to the Free Software
** Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
 
#include "logging.hpp"
#include "shared_ptr.hpp"
#include <libxml++/libxml++.h>
 
namespace jmmcg { namespace LIBJMMCG_VER_NAMESPACE {
 
   template<typename InputIterator,typename ValueType> inline std::pair<bool,InputIterator>
   BestStringMatch(const InputIterator &matches_begin,const InputIterator &matches_end,const ValueType &str) {
      typedef std::map<typename ValueType::size_type,std::vector<InputIterator> > comparison_sets_type;
      comparison_sets_type comparison_sets;
      // Construct a map of comparison values to sets of strings that match at that edit distance.
      for (InputIterator i(matches_begin);i!=matches_end;++i) {
         const ValueType tmp(*i);
         const typename comparison_sets_type::key_type edit_dist=tmp.compare(str);
//       JMMCG_TRACE(_T("Comparing to: ")<<tmp<<_T(", result: ")<<tostring(edit_dist));
         if (edit_dist<tmp.size()) {
//          JMMCG_TRACE(_T("Adding value: ")<<tmp<<_T(", to key: ")<<tostring(edit_dist));
            comparison_sets[edit_dist].push_back(i);
         }
      }
      // See if there is an exact match, i.e. zero. Due to the ordering properties of of a map, this will be the first element.
      if (comparison_sets.begin()->first==0) {
         assert(!comparison_sets.begin()->second.empty());
         // Is it ambiguous? i.e. is there more than one item in the matching set?
         // Unique match means only one element in the set, ambiguous morethan one, return it indicated thusly.
         return std::make_pair(comparison_sets.begin()->second.size()>1,*comparison_sets.begin()->second.begin());
      } else {
         // O.k. no exact match - due to the curious properties of "std::string::compare(...)" we now choose the one with the highest value. As a value of 1 seems to indicate no match. We've excluded complete nonsense matches by storing only those comparison values that are less than the target string length.
         // As we want the highest value, this will be the last element in the map.
         const typename comparison_sets_type::mapped_type &best_matches=(typename comparison_sets_type::const_iterator(comparison_sets.end()))->second;
//       JMMCG_TRACE(_T("No. matches: ")<<tostring(best_matches.size())<<_T(", first match: ")+tostring(*best_matches.begin()));
         assert(!best_matches.empty());
         return std::make_pair(best_matches.size()>1,*best_matches.begin());
      }
   }
 
   class CmdLineParamsData {
   public:
      __stdcall CmdLineParamsData();
      CmdLineParamsData(CmdLineParamsData const &)=delete;
      __stdcall ~CmdLineParamsData() {
      }
 
   protected:
      class ParamType : protected non_assignable {
      public:
         const tstring param;
         const tstring description;
 
         __stdcall ParamType(const tstring &p,const tstring &d)
         : param(p),description(d) {
         }
         __stdcall ParamType(const ParamType &pt)
         : param(pt.param),description(pt.description) {
         }
         __stdcall ~ParamType() {
         }
      };
 
      static const ParamType params[];
      static const tchar * const authors[];
      static const tchar version[];
      static const tchar copyright[];
      static const tchar warranty[];
      static const tchar contact_details[];
      static const tchar help_text[];
      const ParamType help_param;
      const ParamType version_param;
   };
 
   template<typename ProgOpts,class Except_>
   class CmdLineProcessorBase : virtual protected CmdLineParamsData {
   public:
      typedef ProgOpts ProgramOptions;
      typedef Except_ exception_type;
 
      __stdcall CmdLineProcessorBase(ProgramOptions &);
      CmdLineProcessorBase(CmdLineProcessorBase const &)=delete;
      virtual __stdcall ~CmdLineProcessorBase(void) {
      }
 
      virtual bool __fastcall ProcessParams(const unsigned int argv,const tchar * const * const argc,tostream &o);
 
      const shared_ptr<Logger<exception>,exception> & __fastcall Log(void) const noexcept(true) {
         assert(logger);
         return logger;
      }
 
   protected:
      ProgramOptions &prog_opts;
      const tchar *app_name;
 
      virtual bool __fastcall ProcessParamInternal(const unsigned int argv,const tchar * const * const argc,unsigned long &i,tostream &o);
      virtual void __fastcall DumpHelp(tostream &o) const;
 
   private:
      shared_ptr<Logger<exception>,exception> logger;
      const ParamType log_param;
 
      /// Instantiate this function to implement your own processing for you command line parameters.
      /**
       * i.e. when you recognise a parameter, set the appropriate value(s) in the "prog_opts" object.
       * You can adjust the value of the pointer into the list of parameters as you like.
       * For example to finish processing, set it to any value > argc, e.g. "std::numeric_limits<unsigned long>::max()".
       */
      virtual bool __fastcall ProcessParam(const unsigned long recognised_param,const tchar * const * const argc,unsigned long &i,tostream &o)=0;
 
      /// Override this to perform post-processing after the command-line arguments have been processed, such as loading the contents of a configuration file, if the default configuration file name is to be used.
      virtual bool __fastcall PostProcessParams(tostream &) {
         return true;
      }
 
      static tstring MakeLogLevelHelpStr(void);
      bool ProcessLogLevel(const unsigned int,const tchar * const * const,unsigned long &,tostream &);
      void DumpUnknownArg(const tchar * const arg,tostream &o) const;
      void DumpLogHelp(tostream &o) const;
      void DumpVersion(tostream &o) const;
   };
 
   /// A specialization for helping to making use of configuration files.
   template<typename ProgOpts,class Except_>
   class ConfigFile : virtual public CmdLineProcessorBase<ProgOpts,Except_> {
   public:
      typedef typename CmdLineProcessorBase<ProgOpts,Except_>::ProgramOptions ProgramOptions;
      typedef typename CmdLineProcessorBase<ProgOpts,Except_>::exception exception_t;
 
      explicit __stdcall ConfigFile(ProgramOptions &p);
      ConfigFile(ConfigFile const &)=delete;
      virtual __stdcall ~ConfigFile() {
      }
 
   protected:
      virtual bool __fastcall ProcessParamInternal(const unsigned int argv,const tchar * const * const argc,unsigned long &i,tostream &o);
      virtual void __fastcall DumpHelp(tostream &o) const;
 
   private:
      typedef typename file<tifstream, Except_::thread_traits::api_params_type::api_type, typename Except_::thread_traits::model_type> config_file_type;
      typedef CmdLineParamsData::ParamType ParamType;
 
      const ParamType config_param;
      tstring config_file_path;
 
      /// Implement this function to process the various data nodes read from the configuration file.
      /**
       * \return "false" for success, otherwise it failed.
       */
      virtual bool __fastcall PostProcessConfigFileItems(const xmlpp::NodeSet &,tostream &) = 0;
 
      bool __fastcall PostProcessParams(tostream &);
      xmlpp::NodeSet __fastcall CheckConfigFile(xmlpp::DomParser &,tostream &) const;
      xmlpp::NodeSet __fastcall CheckConfigFileValid(config_file_type &,xmlpp::DomParser &,tostream &) const;
 
      tstring __fastcall DefaultConfigFilePath(void) const;
   };
 
   inline
   CmdLineParamsData::CmdLineParamsData(void)
   : help_param(_T("--help"),_T("Show this help information.")),
   version_param(_T("--version"),_T("Display the version & copyright information.")) {
   }
 
   template<typename ProgOpts,class Except_> inline
   CmdLineProcessorBase<ProgOpts,Except_>::CmdLineProcessorBase(ProgramOptions &p)
   : prog_opts(p),app_name('\0'),logger(),
   log_param(_T("--loglevel"),MakeLogLevelHelpStr()) {
      assert(!help_param.param.empty() && !help_param.description.empty());
      assert(!log_param.param.empty() && !log_param.description.empty());
      assert(!version_param.param.empty() && !version_param.description.empty());
      assert(copyright);
      assert(warranty);
      assert(contact_details);
      assert(help_text);
      // If this assertion fails the number of strings in the "log_level_strs" array does not match the number of enumeration values in the "log_level_type" enum.
      // The "+1" is because of the zero-based indexing of arrays. There's n of them, but the last one is at [n-1].
      assert(sizeof(log_level_strs)/sizeof(tchar *)==static_cast<size_t>(log_info+1));
   }
 
   template<typename ProgOpts,class Except_> inline bool
   CmdLineProcessorBase<ProgOpts,Except_>::ProcessParams(const unsigned int argv, const tchar * const * const argc,tostream &o) {
      assert(argv>=0);
      assert(argc && argc[0]);
      app_name=argc[0];
      assert(app_name);
      logger.reset(new Logger<exception>(_T("/var/log/")+tstring(app_name).substr(tstring(app_name).rfind(_T("/"))+1,tstring::npos)+_T(".log"),app_name));
      for (unsigned long i=1;i<argv;++i) {
         assert(argc[i]);
         if (!ProcessParamInternal(argv,argc,i,o)) {
            return false;
         }
      }
      return PostProcessParams(o);
   }
 
   template<typename ProgOpts,class Except_> inline bool
   CmdLineProcessorBase<ProgOpts,Except_>::ProcessParamInternal(const unsigned int argv,const tchar * const * const argc,unsigned long &i,tostream &o) {
      assert(argc);
      assert(argc[i]);
      std::vector<std::string> args(3+sizeof(params)/sizeof(ParamType));
      args[0]=help_param.param;
      args[1]=log_param.param;
      args[2]=version_param.param;
      for (std::vector<std::string>::size_type j=3;j<args.size();++j) {
         args[j]=params[j-3].param;
      }
      const std::pair<bool,std::vector<std::string>::const_iterator> result(BestStringMatch(args.begin(),args.end(),tstring(argc[i])));
      JMMCG_TRACE(_T("Matching parameter: ")<<*result.second);
      if (*result.second==help_param.param) {
         DumpHelp(o);
      } else if (*result.second==log_param.param) {
         if (!ProcessLogLevel(argv,argc,i,o)) {
            DumpLogHelp(o);
            return false;
         }
      } else if (*result.second==version_param.param) {
         DumpVersion(o);
      } else if (!ProcessParam(result.second-args.begin()-3,argc,i,o)) {
         DumpUnknownArg(argc[i],o);
         return false;
      }
      return true;
   }
 
   template<typename ProgOpts,class Except_> inline void
   CmdLineProcessorBase<ProgOpts,Except_>::DumpHelp(tostream &o) const {
      assert(app_name);
      const tchar options_str[]=_T("[options]");
      o<<_T("Usage is:\n");
      o<<app_name;
      o<<_T(" ")<<options_str<<_T("\nWhere ")<<options_str<<_T(" must unambiguously match one (or more) of the following strings:\n");
      o<<_T("\t")<<help_param.param<<_T("\t\t")<<help_param.description<<_T("\n");
      DumpLogHelp(o);
      o<<_T("\t")<<version_param.param<<_T("\t")<<version_param.description<<_T("\n");
      for (unsigned long i=0;i<(sizeof(params)/sizeof(ParamType));++i) {
         assert(!params[i].param.empty() && !params[i].description.empty());
         o<<_T("\t")<<params[i].param<<_T("\t")<<params[i].description<<std::endl;
      }
   }
 
   template<typename ProgOpts,class Except_> inline tstring
   CmdLineProcessorBase<ProgOpts,Except_>::MakeLogLevelHelpStr(void) {
      const tchar param_str[]=_T("level");
      const unsigned long penultimate=(sizeof(log_level_strs)/sizeof(tchar*)-1);
      tostringstream ss;
      ss<<_T(" ")<<param_str<<_T("\tSet the logging level to '")<<param_str<<_T("'={");
      for (unsigned long i=0;i<penultimate;++i) {
         ss<<log_level_strs[i]<<_T("|");
      }
      ss<<log_level_strs[penultimate]<<_T("}, which must match unambiguously, the default is '")<<log_level_strs[0]<<_T("'; each level logs increasingly more information. The log file is: '");
      return ss.str();
   }
 
   template<typename ProgOpts,class Except_> inline bool
   CmdLineProcessorBase<ProgOpts,Except_>::ProcessLogLevel(const unsigned int argv,const tchar * const * const argc,unsigned long &i,tostream &o) {
      if (++i<=argv && argc[i] && !tstring(argc[i]).empty()) {
         const std::pair<bool,const tchar * const *> result(BestStringMatch(&(log_level_strs[0]),&(log_level_strs[sizeof(log_level_strs)/sizeof(tchar*)]),tstring(argc[i])));
         if (result.first) {
            o<<_T("Ambiguous match for supplied 'level' parameter: '")<<argc[i]<<_T("'.\n");
            DumpHelp(o);
         } else {
//          JMMCG_TRACE(_T("Matched with parameter: ")<<tostring(*result.second));
            logger->Level(static_cast<log_level_type>(result.second-&(log_level_strs[0])));
//          JMMCG_TRACE(_T("Resultant log level: ")<<tostring(logger->Level()));
         }
         return true;
         o<<_T("Unrecognised 'level' parameter: '")<<argc[i]<<_T("' for ")<<log_param.param<<_T(" option.\n");
         DumpHelp(o);
         return true;
      }
      o<<_T("Missing 'level' parameter for ")<<log_param.param<<_T(" option.\n");
      DumpHelp(o);
      return true;
   }
 
   template<typename ProgOpts,class Except_> inline void
   CmdLineProcessorBase<ProgOpts,Except_>::DumpUnknownArg(const tchar * const arg,tostream &o) const {
      o<<_T("Unrecognised command line parameter '")<<arg<<_T("'.\n");
      DumpHelp(o);
   }
 
   template<typename ProgOpts,class Except_> inline void
   CmdLineProcessorBase<ProgOpts,Except_>::DumpLogHelp(tostream &o) const {
      o<<_T("\t")<<log_param.param<<log_param.description<<logger->Path()<<_T("'.\n");
   }
 
   template<typename ProgOpts,class Except_> inline void
   CmdLineProcessorBase<ProgOpts,Except_>::DumpVersion(tostream &o) const {
      assert(app_name);
      o<<app_name<<_T(", Version: ")<<version<<_T("\n");
      o<<_T("Author(s):\n");
      for (unsigned long i=0;i<(sizeof(authors)/sizeof(tstring *));++i) {
         assert(authors[i]);
         o<<_T("\t")<<authors[i]<<_T("\n");
      }
      assert(copyright);
      o<<_T("Copyright © ")<<copyright<<_T("\n");
      assert(warranty);
      o<<_T("Warranty Information: ")<<warranty<<_T("\n");
      assert(contact_details);
      o<<_T("Contact details: ")<<contact_details<<_T("\n");
      assert(help_text);
      o<<_T("Brief description:\n")<<help_text<<std::endl;
   }
 
   template<typename ProgOpts,class Except_> inline
   ConfigFile<ProgOpts,Except_>::ConfigFile(ProgramOptions &p)
   : CmdLineProcessorBase<ProgramOptions,Except_>(p),config_param(_T("--config"),_T(" file_path\tSpecify the location (file_path) of the configuration file. The configuration file should be in XML format with a valid XDR schema (of the same name, in the same location, but with an '.xdr' extension). This schema referenced by the XML will be used as one of the tests to verify the appropriateness of the specified configuration file for this program. By default it is called: '")) {
   }
 
   template<typename ProgOpts,class Except_> inline bool
   ConfigFile<ProgOpts,Except_>::ProcessParamInternal(const unsigned int argv,const tchar * const * const argc,unsigned long &i,tostream &o) {
      const tstring::size_type hc=config_param.param.compare(argc[i]);
      if (hc>=0 && hc<config_param.param.size()-2) {
         if (++i<=argv && argc[i] && !tstring(argc[i]).empty()) {
            config_file_path=argc[i];
            return true;
         } else {
            o<<_T("Missing 'file_path' parameter for ")<<config_param.param<<_T(" option.\n");
            DumpHelp(o);
            return false;
         }
      } else {
         return CmdLineProcessorBase<ProgOpts,Except_>::ProcessParamInternal(argv,argc,i,o);
      }
   }
 
   template<typename ProgOpts,class Except_> inline void
   ConfigFile<ProgOpts,Except_>::DumpHelp(tostream &o) const {
      CmdLineProcessorBase<ProgOpts,Except_>::DumpHelp(o);
      o<<_T("\t")<<config_param.param<<config_param.description<<DefaultConfigFilePath()<<_T("'.")<<std::endl;
   }
 
   template<typename ProgOpts,class Except_> inline bool
   ConfigFile<ProgOpts,Except_>::PostProcessParams(tostream &o) {
      if (config_file_path.empty()) {
         config_file_path=DefaultConfigFilePath();
      }
      xmlpp::DomParser parser;
      const xmlpp::NodeSet data_items(CheckConfigFile(parser,o));
      if (!data_items.empty()) {
         // Process the data items and put them into the program options stucture...
         JMMCG_TRACE(_T("Process ")<<tostring(data_items.size())+_T(" node(s)..."));
         JMMCG_LOG((ConfigFile<ProgOpts,Except_>::Log()),log_info,_T("Process ")+tostring(data_items.size())+_T(" node(s)..."));
         if (!PostProcessConfigFileItems(data_items,o)) {
            o<<_T("There was an error whilst processing the configuration file.\n");
            DumpHelp(o);
            return false;
         }
         return true;
      } else {
         DumpHelp(o);
         return false;
      }
   }
 
   template<typename ProgOpts,class Except_> inline xmlpp::NodeSet
   ConfigFile<ProgOpts,Except_>::CheckConfigFile(xmlpp::DomParser &parser,tostream &o) const {
      try {
         // Check the file exists by opening it read-only...
         config_file_type config_file(config_file_path,std::ios_base::in,false);
         return CheckConfigFileValid(config_file,parser,o);
      } catch (const typename config_file_type::exception &e) {
         // Not interested in the details of the exception really - just the fact that it happened, so signifying a problem with opening the file to read it.
         o<<_T("The configuration file '")<<config_file_path<<_T("' was not found in the specified location.\n");
         JMMCG_LOG((ConfigFile<ProgOpts,Except_>::Log()),log_info,e.what());
      }
      return xmlpp::NodeSet();
   }
 
   template<typename ProgOpts,class Except_> inline xmlpp::NodeSet
   ConfigFile<ProgOpts,Except_>::CheckConfigFileValid(config_file_type &config_file,xmlpp::DomParser &parser,tostream &o) const {
      // Now check the contents. I use XML with an XDR schema defined, so just run the XML processor on it with the schema attached. If it is valid, we know that the structure of the file is good! (One of the *very* *few* useful things about XML...)
      try {
#warning TODO JMG: Seems to only like DTD validation:       parser.set_validate();
         parser.parse_stream(config_file);
         if (parser) {
            assert(dynamic_cast<const xmlpp::Element *>(parser.get_document()->get_root_node()));
            const xmlpp::NodeSet data_items(parser.get_document()->get_root_node()->find(_T("/Config/Data/*")));
//          JMMCG_TRACE(_T("X-Path to first item: ")<<(*data_items.begin())->get_path());
            if (data_items.empty()) {
               o<<_T("The configuration file '")<<config_file_path<<_T("' is not valid for this program.\n");
            }
            return data_items;
         }
      } catch (const std::exception &e) {
         o<<_T("Error processing the configuration file: '")<<e.what()<<_T("'\n");
      }
      return xmlpp::NodeSet();
   }
 
   template<typename ProgOpts,class Except_> inline tstring
   ConfigFile<ProgOpts,Except_>::DefaultConfigFilePath(void) const {
      return _T("~/.")+tstring(ConfigFile<ProgOpts,Except_>::app_name).substr(tstring(ConfigFile<ProgOpts,Except_>::app_name).rfind(_T("/"))+1,tstring::npos)+_T("rc.xml");
   }
 
} }