yask_common_api.hpp

Go to the documentation of this file.

/*****************************************************************************
 
YASK: Yet Another Stencil Kit
Copyright (c) 2014-2024, Intel Corporation
 
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
 
* The above copyright notice and this permission notice shall be included in
  all copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
 
*****************************************************************************/
 
 
// This file uses Doxygen markup for API documentation-generation.
// See https://www.doxygen.nl/manual/index.html.
#pragma once
 
#include <cstdint>
#include <cinttypes>
#include <climits>
#include <type_traits>
#include <string>
#include <vector>
#include <set>
#include <map>
#include <iostream>
#include <ostream>
#include <sstream>
#include <memory>
#include <functional>
 
// Things SWIG can't handle.
#ifdef SWIG
#ifndef YASK_DEPRECATED
#define YASK_DEPRECATED
#endif
#ifndef YASK_NORETURN
#define YASK_NORETURN
#endif
#define YASK_INT64_T long int
#else
#ifndef YASK_DEPRECATED
#define YASK_DEPRECATED [[deprecated]]
#endif
#ifndef YASK_NORETURN
#define YASK_NORETURN [[noreturn]]
#endif
#define YASK_INT64_T std::int64_t
#endif
 
namespace yask {
 
 
    std::string yask_get_version_string();
 
 
    typedef YASK_INT64_T idx_t;
 
    typedef std::vector<idx_t> idx_t_vec;
 
 
    typedef std::initializer_list<idx_t> idx_t_init_list;
 
    typedef std::vector<std::string> string_vec;
 
    // Forward declarations of class-pointers.
 
    class yask_output;
    typedef std::shared_ptr<yask_output> yask_output_ptr;
 
    class yask_file_output;
    typedef std::shared_ptr<yask_file_output> yask_file_output_ptr;
 
    class yask_string_output;
    typedef std::shared_ptr<yask_string_output> yask_string_output_ptr;
 
    class yask_stdout_output;
    typedef std::shared_ptr<yask_stdout_output> yask_stdout_output_ptr;
 
    class yask_null_output;
    typedef std::shared_ptr<yask_null_output> yask_null_output_ptr;
 
 
    class yask_exception: public std::exception {
    private:
        std::string _msg;
 
    public:
 
        yask_exception() :
            _msg("YASK error") { };
 
        yask_exception(const std::string& message) :
            _msg(message) { };
 
        virtual ~yask_exception() { };
 
 
        virtual const char* what() const noexcept;
 
        virtual void add_message(const std::string& message );
 
 
        virtual const char* get_message() const;
    };
 
    #ifndef SWIG
    
 
    #define THROW_YASK_EXCEPTION(message) do {                      \
            auto msg = std::string("YASK error: ") + message;       \
            yask_exception e(msg);                                  \
            throw e;                                                \
        } while(0)
    
 
    #define FORMAT_AND_THROW_YASK_EXCEPTION(message) do {           \
            std::stringstream err;                                  \
            err << message;                                         \
            THROW_YASK_EXCEPTION(err.str());                        \
        } while(0)
 
    #endif
    
    class yask_output_factory {
    public:
        virtual ~yask_output_factory() {}
 
 
        virtual yask_file_output_ptr
        new_file_output(const std::string& file_name ) const;
 
 
        virtual yask_string_output_ptr
        new_string_output() const;
 
 
        virtual yask_stdout_output_ptr
        new_stdout_output() const;
 
 
        virtual yask_null_output_ptr
        new_null_output() const;
    };
 
    class yask_output {
    public:
        virtual ~yask_output() {}
 
 
        virtual std::ostream& get_ostream() =0;
    };
 
    class yask_file_output : public virtual yask_output {
    public:
        virtual ~yask_file_output() {}
 
 
        virtual std::string get_filename() const =0;
 
        virtual void close() =0;
    };
 
    class yask_string_output : public virtual yask_output {
    public:
        virtual ~yask_string_output() {}
 
 
        virtual std::string get_string() const =0;
 
        virtual void discard() =0;
    };
 
    class yask_stdout_output : public virtual yask_output {
    public:
        virtual ~yask_stdout_output() {}
    };
 
 
    class yask_null_output : public virtual yask_output {
    public:
        virtual ~yask_null_output() {}
    };
 
 
    std::vector<double>
    get_center_fd_coefficients(int derivative_order,
                               int radius );
 
 
    std::vector<double>
    get_forward_fd_coefficients(int derivative_order,
                                int accuracy_order );
    
 
    std::vector<double>
    get_backward_fd_coefficients(int derivative_order,
                                 int accuracy_order );
    
 
    std::vector<double>
    get_arbitrary_fd_coefficients(int derivative_order,
                                  double eval_point,
                                  const std::vector<double> sample_points );
 
    #ifndef SWIG
    
 
    class command_line_parser {
 
    public:
 
 
        class option_base {
 
        private:
            std::string _name;
            std::string _help;
            std::string _help_leader;
            std::string _current_value_str;
 
        protected:
 
            virtual void _print_help(std::ostream& os,
                                     const std::string& display_name,
                                     int width) const;
 
 
            virtual bool _is_opt(const string_vec& args, int& argi,
                                 const std::string& str) const;
 
 
            virtual double _double_val(const string_vec& args, int& argi);
 
 
            virtual idx_t _idx_val(const string_vec& args, int& argi);
 
 
            virtual std::string _string_val(const string_vec& args, int& argi);
 
        public:
            option_base(const std::string& name,
                        const std::string& help_msg,
                        const std::string& current_value_prefix = std::string("Current value = "),
                        const std::string& help_line_prefix = std::string("    ")) :
                _name(name), _help(help_msg),
                _help_leader(help_line_prefix),
                _current_value_str(current_value_prefix) 
            { }
            virtual ~option_base() { }
 
            virtual const std::string& get_name() const {
                return _name;
            }
 
            virtual const std::string& get_help() const {
                return _help;
            }
            
            virtual void print_help(std::ostream& os,
                                    int width) const {
                _print_help(os, _name, width);
            }
 
            virtual std::ostream& print_value(std::ostream& os) const =0;
 
 
            virtual bool check_arg(const string_vec& args, int& argi) =0;
        };
 
        typedef std::shared_ptr<option_base> option_ptr;
 
        class bool_option : public option_base {
            bool& _val;
 
        public:
            bool_option(const std::string& name,
                       const std::string& help_msg,
                       bool& val) :
                option_base(name, help_msg), _val(val) { }
 
            virtual void print_help(std::ostream& os,
                                    int width) const override;
 
            virtual std::ostream& print_value(std::ostream& os) const override {
                os << (_val ? "true" : "false");
                return os;
            }
 
            virtual bool check_arg(const string_vec& args, int& argi) override;
        };
 
        class int_option : public option_base {
            int& _val;
 
        public:
            int_option(const std::string& name,
                      const std::string& help_msg,
                      int& val) :
                option_base(name, help_msg), _val(val) { }
 
            virtual void print_help(std::ostream& os,
                                    int width) const override;
 
            virtual std::ostream& print_value(std::ostream& os) const override {
                os << _val;
                return os;
            }
 
            virtual bool check_arg(const string_vec& args, int& argi) override;
        };
 
        class double_option : public option_base {
            double& _val;
 
        public:
            double_option(const std::string& name,
                      const std::string& help_msg,
                      double& val) :
                option_base(name, help_msg), _val(val) { }
 
            virtual void print_help(std::ostream& os,
                                    int width) const override;
 
            virtual std::ostream& print_value(std::ostream& os) const override {
                os << _val;
                return os;
            }
 
            virtual bool check_arg(const string_vec& args, int& argi) override;
        };
 
        class idx_option : public option_base {
            idx_t& _val;
 
        public:
            idx_option(const std::string& name,
                       const std::string& help_msg,
                       idx_t& val) :
                option_base(name, help_msg), _val(val) { }
 
            virtual void print_help(std::ostream& os,
                                    int width) const override;
 
            virtual std::ostream& print_value(std::ostream& os) const override {
                os << _val;
                return os;
            }
 
            virtual bool check_arg(const string_vec& args, int& argi) override;
        };
 
        class string_option : public option_base {
            std::string& _val;
 
        public:
            string_option(const std::string& name,
                         const std::string& help_msg,
                         std::string& val) :
                option_base(name, help_msg), _val(val) { }
 
            virtual void print_help(std::ostream& os,
                                    int width) const override;
 
            virtual std::ostream& print_value(std::ostream& os) const override {
                os << "'" << _val << "'";
                return os;
            }
 
            virtual bool check_arg(const string_vec& args,
                                   int& argi) override;
        };
 
 
        class string_list_option : public option_base {
            std::set<std::string> _allowed_strs; // empty to allow any strings.
            string_vec& _val;
 
        public:
            string_list_option(const std::string& name,
                               const std::string& help_msg,
                               string_vec& val) :
                option_base(name, help_msg),
                _val(val) { }
 
            string_list_option(const std::string& name,
                               const std::string& help_msg,
                               const std::set<std::string>& allowed_strs,
                               string_vec& val) :
                option_base(name, help_msg),
                _allowed_strs(allowed_strs),
                _val(val) { }
 
            virtual void print_help(std::ostream& os,
                                    int width) const override;
 
            virtual std::ostream& print_value(std::ostream& os) const override {
                int n = 0;
                for (auto& v : _val) {
                    if (n)
                        os << ",";
                    os << v;
                    n++;
                }
                return os;
            }
 
            virtual bool check_arg(const string_vec& args, int& argi) override;
        };
 
    private:
        std::map<std::string, option_ptr> _opts;
        int _width = 78;
 
    public:
 
        command_line_parser() { }
 
        virtual ~command_line_parser() { }
 
        static string_vec set_args(const std::string& arg_string);
 
        virtual void set_width(int width) {
            _width = width;
        }
 
        virtual int get_width() const {
            return _width;
        }
 
        virtual void add_option(option_ptr opt) {
            _opts[opt->get_name()] = opt;
        }
 
        virtual void print_help(std::ostream& os) const;
 
        virtual void print_values(std::ostream& os) const;
 
 
        virtual std::string parse_args(const std::string& pgm_name,
                                       const string_vec& args);
 
        virtual std::string parse_args(const std::string& pgm_name,
                                       const std::string& arg_string) {
            auto args = set_args(arg_string);
            return parse_args(pgm_name, args);
        }
 
        virtual std::string parse_args(int argc, char** argv) {
            std::string pgm_name = argv[0];
            string_vec args;
            for (int i = 1; i < argc; i++)
                args.push_back(argv[i]);
            return parse_args(pgm_name, args);
        }
    };
 
 
    extern void
    yask_print_splash(std::ostream& os, int argc, char** argv,
                      std::string invocation_leader = "invocation: ");
    #endif
    
} // namespace yask.