/********************************************************
* ██████╗ ██████╗████████╗██╗
* ██╔════╝ ██╔════╝╚══██╔══╝██║
* ██║ ███╗██║ ██║ ██║
* ██║ ██║██║ ██║ ██║
* ╚██████╔╝╚██████╗ ██║ ███████╗
* ╚═════╝ ╚═════╝ ╚═╝ ╚══════╝
* Geophysical Computational Tools & Library (GCTL)
*
* Copyright (c) 2023 Yi Zhang (yizhang-geo@zju.edu.cn)
*
* GCTL is distributed under a dual licensing scheme. 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
* of the License, or (at your option) any later version. You should have
* received a copy of the GNU Lesser General Public License along with this
* program. If not, see .
*
* If the terms and conditions of the LGPL v.2. would prevent you from using
* the GCTL, please consider the option to obtain a commercial license for a
* fee. These licenses are offered by the GCTL's original author. As a rule,
* licenses are provided "as-is", unlimited in time for a one time fee. Please
* send corresponding requests to: yizhang-geo@zju.edu.cn. Please do not forget
* to include some description of your company and the realm of its activities.
* Also add information on how to contact you by electronic and paper mail.
******************************************************/
#ifndef _GCTL_GETOPT_HELP_H
#define _GCTL_GETOPT_HELP_H
#include "stream.h"
#ifdef _WINDOWS
#include "windows.h"
#include "getopt_win.h"
#else
#include "sys/ioctl.h"
#include "getopt.h"
#endif
namespace gctl
{
struct option_info
{
/**
* The following three variables we added here are mainly used to generate the
* 'help' page. The variable 'info' represents a short message that explains what
* the option does. 'format' express the argument's format that the option takes.
* Additionally, The variable 'manda' indicates whether the option is mandatory
* or optional.
*/
const char *info;
const char *format;
bool manda;
};
/**
* @brief display formatted help information in terminal
*
* This function will display formated help information in the terminal using
* the standard error output. We choose the error output to avoid unexpected
* redirection and make sure the information will appear in the terminal.
*
* @param[in] proname The program's name.
* @param[in] brief The brief information show right after the program's name.
* @param[in] exp_longopts The pointer of expanded longopts
* @param stdout 标准输出信道
*/
void getopt_long_help(const option *longopts, const option_info *expd_longopts, const char* proname,
const char* brief, std::ostream& sout=std::clog, std::string extra_usage = "");
/**
* @brief Display the help information of one option indicated by its id.
*
* @param[in] val The option's value
* @param exp_longopts The expanded longopts
* @param stdout 标准输出信道
*/
void getopt_long_option_info(int val, const option *longopts, const option_info *expd_longopts, std::ostream& sout=std::clog);
/**
* @brief 命令行参数拾取与帮助信息显示
*
* 此类基于GNU getopt_long()函数 更多信息可查阅相关资料
*
* 选项参数拾取规则（命令参数规则的说明）
* 1. 每个选项都包含一个短选项（一个字符）和一个长选项（一个字符串）。选项的名称必需唯一
* 2. has_arg = no_argument 表示选项不接受参数
* 3. has_arg = required_argument 表示选项后必需跟参数 可紧贴短选项或者空一格 长选项必需空一格或者用=号连接（推荐空格）
* 4. has_arg = optional_argument 表示选项后可跟参数 也可不跟 有参数时如果是短选项必需紧贴 长选项必需用=号连接
*/
class flags_parser
{
public:
flags_parser();
virtual ~flags_parser();
/**
* @brief 添加选项信息
*
* @param[in] s_name 选项的短名称 一般为一个大写或小写字母
* @param[in] f_name 选项的长名称
* @param[in] has_arg 选项是否接收参数
* @param flag 设置get_arg()函数的返回值，如果此参数不为NULL则get_arg()会在成功识别到参数时将s_name的值拷贝给flag指向的变量，同时返回0。
* @param[in] info 选项的简介信息
* @param[in] format 选项的参数格式
* @param[in] manda 选项是否为必须的，表示每次运行程序时都必须设置的参数。
*/
void add_opt(int s_name, const char* f_name, int has_arg, int *flag, const char* info,
const char* format, bool manda);
/**
* @brief 配置命令行参数选项
*
* 在调用参数拾取与帮助信息显示函数前需要初始化
*
* @param[in] argc 命令行参数的个数
* @param argv 命令行参数的指针
*/
void configure(int argc, char **argv);
/**
* @brief 检测是否所有必需元素都拾取成功
*
* @return 是否通过
*/
bool pass_mandatory();
/**
* @brief 检查命令行选项中是否有待检查的选项
*
* @param[in] s_name 待检查的选项
*
* @return 有则返回1，无返回0，强制选项无返回-1
*/
int set_opt(const int s_name);
/**
* @brief 检查命令行选项中是否有待检查的选项
*
* @param[in] f_name 待检查的选项长名称
*
* @return 有则返回1，无返回0，强制选项无返回-1
*/
int set_opt(const char* f_name);
/**
* @brief 检查命令行选项中是否有待检查的选项并返回参数值
*
* @param[in] s_name 待检查的选项
*
* @return 成功则返回参数值，否则返回NULL，对于可选参数选项，如果选项后无参数则返回NO_ARG
*/
std::string get_arg(const int s_name);
/**
* @brief 检查命令行选项中是否有待检查的选项并返回参数值
*
* @param[in] s_name 待检查的选项长名称
*
* @return 成功则返回参数值，否则返回NULL，对于可选参数选项，如果选项后无参数则返回NO_ARG
*/
std::string get_arg(const char* f_name);
/**
* @brief 拾取命令行参数
*
* @param[in] tar_val 目标选项的短名称列表
* @param[in] ret_str 目标选项的参数值
*/
void get_argv(std::initializer_list tar_val, std::initializer_list ret_str);
/**
* @brief 打印帮助信息页面
*/
void show_help_page(std::ostream& sout = std::clog, std::string extra_usage = "");
/**
* @brief 显示对应选项的帮助信息
*
* @param[in] s_name 选项名称
*/
void show_option_info(int s_name, std::ostream& sout=std::clog);
/**
* @brief 显示对应选项的帮助信息
*
* @param[in] s_name 选项名称
*/
void show_option_info(const char* f_name, std::ostream& sout=std::clog);
/**
* @brief 设置程序名称
*
* @param[in] proname 程序名称
*/
void set_proname(const char* proname);
/**
* @brief 设置程序简介信息
*
* @param[in] proinfo 简介信息
*/
void set_proinfo(const char* proinfo);
/**
* @brief 设置未找到选项时的返回字符串，默认为NULL
*
* @param[in] in_str 输入字符串
*/
void set_nofound_return(std::string in_str);
/**
* @brief 设置可选参数选项的默认返回字符串，默认为NO_ARG
*
* @param[in] in_str 输入字符串
*/
void set_noarg_return(std::string in_str);
/**
* @brief 显示选项识别字符串
*
* @param stdout 标准输出信道
*/
void show_arg_format(std::ostream& sout=std::clog);
protected:
std::vector