app.h

Go to the documentation of this file.

/* Copyright (c) 2008-2022 the MRtrix3 contributors.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * Covered Software is provided under this License on an "as is"
 * basis, without warranty of any kind, either expressed, implied, or
 * statutory, including, without limitation, warranties that the
 * Covered Software is free of defects, merchantable, fit for a
 * particular purpose or non-infringing.
 * See the Mozilla Public License v. 2.0 for more details.
 *
 * For more details, see http://www.mrtrix.org/.
 */
 
#ifndef __app_h__
#define __app_h__
 
#include <cstring>
#include <limits>
#include <string>
#include <thread>
 
#ifdef None
# undef None
#endif
 
#include "cmdline_option.h"
#include "types.h"
#include "file/path.h"
 
 
extern void usage ();
extern void run ();
 
namespace MR
{
  namespace App
  {
 
 
    extern const char* mrtrix_version;
    extern const char* build_date;
    extern int log_level;
    extern int exit_error_code;
    extern std::string NAME;
    extern std::string command_history_string;
    extern bool overwrite_files;
    extern void (*check_overwrite_files_func) (const std::string& name);
    extern bool fail_on_warn;
    extern bool terminal_use_colour;
    extern const std::thread::id main_thread_ID;
 
    extern int argc;
    extern const char* const* argv;
 
    extern const char* project_version;
    extern const char* project_build_date;
 
 
    const char* argtype_description (ArgType type);
 
    std::string help_head (int format);
    std::string help_synopsis (int format);
    std::string help_tail (int format);
    std::string usage_syntax (int format);
 
 
 
 
    // @{
 
    class Description : public vector<const char*> { NOMEMALIGN
      public:
        Description& operator+ (const char* text) {
          push_back (text);
          return *this;
        }
 
        Description& operator+ (const char* const text[]) {
          for (const char* const* p = text; *p; ++p)
            push_back (*p);
          return *this;
        }
 
        std::string syntax (int format) const;
    };
 
 
 
    class Example { NOMEMALIGN
      public:
        Example (const std::string& title,
                 const std::string& code,
                 const std::string& description) :
            title (title),
            code (code),
            description (description) { }
        const std::string title, code, description;
 
        operator std::string () const;
        std::string syntax (int format) const;
    };
 
    class ExampleList : public vector<Example> { NOMEMALIGN
      public:
        ExampleList& operator+ (const Example& example) {
          push_back (example);
          return *this;
        }
 
        std::string syntax (int format) const;
    };
 
 
 
 
    class ArgumentList : public vector<Argument> { NOMEMALIGN
      public:
        ArgumentList& operator+ (const Argument& argument) {
          push_back (argument);
          return *this;
        }
 
        std::string syntax (int format) const;
    };
 
 
 
 
 
    class OptionList : public vector<OptionGroup> { NOMEMALIGN
      public:
        OptionList& operator+ (const OptionGroup& option_group) {
          push_back (option_group);
          return *this;
        }
 
        OptionList& operator+ (const Option& option) {
          back() + option;
          return *this;
        }
 
        OptionList& operator+ (const Argument& argument) {
          back() + argument;
          return *this;
        }
 
        OptionGroup& back () {
          if (empty())
            push_back (OptionGroup());
          return vector<OptionGroup>::back();
        }
 
        std::string syntax (int format) const;
    };
 
 
 
 
    inline void check_overwrite (const std::string& name)
    {
      if (Path::exists (name) && !overwrite_files) {
        if (check_overwrite_files_func)
          check_overwrite_files_func (name);
        else
          throw Exception ("output file \"" + name + "\" already exists (use -force option to force overwrite)");
      }
    }
 
 
 
 
 
    void init (int argc, const char* const* argv);
 
    void verify_usage ();
 
    void parse_special_options ();
 
    void parse ();
 
    void sort_arguments (int argc, const char* const* argv);
 
    const Option* match_option (const char* stub);
 
    std::string full_usage ();
 
 
 
 
 
    class ParsedArgument { NOMEMALIGN
      public:
        operator std::string () const { return p; }
 
        const char* as_text () const { return p; }
        bool as_bool () const { return to<bool> (p); }
        int64_t as_int () const;
        uint64_t as_uint () const { return uint64_t (as_int()); }
        default_type as_float () const;
 
        vector<int32_t> as_sequence_int () const {
          assert (arg->type == IntSeq);
          try { return parse_ints<int32_t> (p); }
          catch (Exception& e) { error (e); }
          return vector<int32_t>();
        }
 
        vector<uint32_t> as_sequence_uint () const {
          assert (arg->type == IntSeq);
          try { return parse_ints<uint32_t> (p); }
          catch (Exception& e) { error (e); }
          return vector<uint32_t>();
        }
 
        vector<default_type> as_sequence_float () const {
          assert (arg->type == FloatSeq);
          try { return parse_floats (p); }
          catch (Exception& e) { error (e); }
          return vector<default_type>();
        }
 
        operator bool () const { return as_bool(); }
        operator int () const { return as_int(); }
        operator unsigned int () const { return as_uint(); }
        operator long int () const { return as_int(); }
        operator long unsigned int () const { return as_uint(); }
        operator long long int () const { return as_int(); }
        operator long long unsigned int () const { return as_uint(); }
        operator float () const { return as_float(); }
        operator double () const { return as_float(); }
        operator vector<int32_t> () const { return as_sequence_int(); }
        operator vector<uint32_t> () const { return as_sequence_uint(); }
        operator vector<default_type> () const { return as_sequence_float(); }
 
        const char* c_str () const { return p; }
 
      private:
        const Option* opt;
        const Argument* arg;
        const char* p;
 
        ParsedArgument (const Option* option, const Argument* argument, const char* text) :
          opt (option), arg (argument), p (text) {
          assert (text);
        }
 
        void error (Exception& e) const {
          std::string msg ("error parsing token \"");
          msg += p;
          if (opt) msg += std::string ("\" for option \"") + opt->id + "\"";
          else msg += std::string ("\" for argument \"") + arg->id + "\"";
          throw Exception (e, msg);
        }
 
        friend class ParsedOption;
        friend class Options;
        friend void  MR::App::init (int argc, const char* const* argv);
        friend void  MR::App::parse ();
        friend void  MR::App::sort_arguments (int argc, const char* const* argv);
    };
 
 
 
 
 
    class ParsedOption { NOMEMALIGN
      public:
        ParsedOption (const Option* option, const char* const* arguments) :
            opt (option), args (arguments)
        {
          for (size_t i = 0; i != option->size(); ++i) {
            const char* p = arguments[i];
            if (!consume_dash (p))
              continue;
            if (( (*option)[i].type == ImageIn || (*option)[i].type == ImageOut ) && is_dash (arguments[i]))
              continue;
            if ((*option)[i].type == Integer || (*option)[i].type == Float || (*option)[i].type == IntSeq ||
                (*option)[i].type == FloatSeq || (*option)[i].type == Various)
              continue;
            WARN (std::string("Value \"") + arguments[i] + "\" is being used as " +
                ((option->size() == 1) ?
                 "the expected argument " :
                 ("one of the " + str(option->size()) + " expected arguments ")) +
                "for option \"-" + option->id + "\", yet this itself looks like a separate command-line option; " +
                "the requisite input" +
                ((option->size() == 1) ? " " : "s ") +
                "to command-line option \"-" + option->id + "\" may have been erroneously omitted, which may cause " +
                "other command-line parsing errors");
          }
        }
 
        const Option* opt;
        const char* const* args;
 
        const ParsedArgument operator[] (size_t num) const {
          assert (num < opt->size());
          return ParsedArgument (opt, & (*opt) [num], args[num]);
        }
 
        bool operator== (const char* match) const {
          std::string name = lowercase (match);
          return name == opt->id;
        }
 
    };
 
 
    extern vector<ParsedArgument> argument;
    extern vector<ParsedOption> option;
 
 
    extern Description DESCRIPTION;
 
 
    extern ExampleList EXAMPLES;
 
 
    extern ArgumentList ARGUMENTS;
 
 
    extern OptionList OPTIONS;
 
 
 
    extern bool REQUIRES_AT_LEAST_ONE_ARGUMENT;
 
    extern const char* AUTHOR;
 
    extern const char* COPYRIGHT;
 
    extern const char* SYNOPSIS;
 
 
    extern Description REFERENCES;
 
 
    extern OptionGroup __standard_options;
 
 
 
 
    const vector<ParsedOption> get_options (const std::string& name);
 
 
 
    template <typename T>
    inline T get_option_value (const std::string& name, const T default_value)
    {
      auto opt = get_options(name);
      T r = (opt.size()) ? opt[0][0] : default_value;
      return r;
    }
 
 
    inline std::string operator+ (const char* left, const App::ParsedArgument& right)
    {
      std::string retval (left);
      retval += std::string (right);
      return retval;
    }
 
 
    inline std::ostream& operator<< (std::ostream& stream, const App::ParsedArgument& arg)
    {
      stream << std::string (arg);
      return stream;
    }
 
  }
 
}
 
#endif