1 /* opt.h -- general-purpose command line option parser 2 Copyright (C) 2016-2021 Free Software Foundation, Inc. 3 4 GNU Mailutils is free software; you can redistribute it and/or 5 modify it under the terms of the GNU General Public License as 6 published by the Free Software Foundation; either version 3, or (at 7 your option) any later version. 8 9 GNU Mailutils is distributed in the hope that it will be useful, but 10 WITHOUT ANY WARRANTY; without even the implied warranty of 11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 General Public License for more details. 13 14 You should have received a copy of the GNU General Public License 15 along with GNU Mailutils. If not, see <http://www.gnu.org/licenses/>. 16 */ 17 18 #ifndef _MAILUTILS_CLI_H 19 #define _MAILUTILS_CLI_H 20 #include <stdio.h> 21 #include <mailutils/types.h> 22 #include <mailutils/cfg.h> 23 #include <mailutils/opt.h> 24 25 typedef void (*mu_cli_capa_commit_fp) (void *); 26 27 struct mu_cli_capa 28 { 29 char *name; 30 struct mu_option *opt; 31 struct mu_cfg_param *cfg; 32 mu_cfg_section_fp parser; 33 mu_cli_capa_commit_fp commit; 34 }; 35 36 void mu_cli_capa_init (void); 37 void mu_cli_capa_register (struct mu_cli_capa *capa); 38 void mu_cli_capa_extend_settings (char const *name, mu_list_t opts, 39 mu_list_t commits); 40 41 struct mu_cli_setup 42 { 43 struct mu_option **optv; /* Command-line options */ 44 struct mu_cfg_param *cfg; /* Configuration parameters */ 45 char *prog_doc; /* Program documentation string */ 46 char *prog_args; /* Program arguments string */ 47 char const **prog_alt_args; /* Alternative arguments string */ 48 char *prog_extra_doc; /* Extra documentation. This will be 49 displayed after options. */ 50 int ex_usage; /* If not 0, exit code on usage errors */ 51 int ex_config; /* If not 0, exit code on configuration 52 errors */ 53 int inorder:1; /* Don't permute options and arguments */ 54 int server:1; /* This is a server: don't read per-user 55 configuration files */ 56 void (*prog_doc_hook) (mu_stream_t); 57 }; 58 59 extern const char mu_version_copyright[]; 60 extern const char mu_general_help_text[]; 61 extern int mu_copyright_year; 62 63 void mu_version_print (mu_stream_t stream); 64 void mu_version_hook (struct mu_parseopt *po, mu_stream_t stream); 65 void mu_cli (int argc, char **argv, struct mu_cli_setup *setup, 66 char **capa, void *data, 67 int *ret_argc, char ***ret_argv); 68 void mu_cli_ext (int argc, char **argv, 69 struct mu_cli_setup *setup, 70 struct mu_parseopt *pohint, 71 struct mu_cfg_parse_hints *cfhint, 72 char **capa, 73 void *data, 74 int *ret_argc, char ***ret_argv); 75 76 char *mu_site_config_file (void); 77 78 void mu_acl_cfg_init (void); 79 80 /* Simplified interface */ 81 enum 82 { 83 MU_CLI_OPTION_END = -1, /* End of options */ 84 85 /* Argument: struct mu_option * 86 * Description: Supplies the array of options. Can be given mupliple 87 * times. 88 * Ref: optv in struct mu_cli_setup. 89 */ 90 MU_CLI_OPTION_OPTIONS, 91 92 /* Argument: struct mu_cfg_param * 93 * Description: Supplies configuration definitions. 94 * NULL argument is a no-op. 95 * Ref: cfg in struct mu_cli_setup 96 */ 97 MU_CLI_OPTION_CONFIG, 98 99 /* Argument: char ** 100 * Description: NULL-terminated array of capability strings. 101 * NULL argument is a no-op. 102 * Ref: capa argument to mu_cli and mu_cli_ext. 103 */ 104 MU_CLI_OPTION_CAPABILITIES, 105 106 /* Argument: int 107 * Description: Exit code to use on usage errors (default: EX_USAGE). 108 * Ref: ex_usage member of struct mu_cli_setup. 109 */ 110 MU_CLI_OPTION_EX_USAGE, 111 112 /* Argument: int 113 * Description: Exit code to use on configuration errors (default: 114 * EX_CONFIG). 115 * Ref: ex_config member of struct mu_cli_setup. 116 */ 117 MU_CLI_OPTION_EX_CONFIG, 118 119 /* Argument: none 120 * Description: Ignore usage errors. 121 * Ref: MU_PARSEOPT_IGNORE_ERRORS flag in opt.h 122 */ 123 MU_CLI_OPTION_IGNORE_ERRORS, 124 125 /* Argument: int * 126 * Description: A pointer to store the number of command line 127 * arguments in. 128 * Ref: ret_argc argument in mu_cli and mu_cli_ext. 129 */ 130 MU_CLI_OPTION_RETURN_ARGC, 131 132 /* Argument: char *** 133 * Description: A pointer to store the address of the array of 134 * command line arguments. 135 * Ref: ret_argv argument in mu_cli and mu_cli_ext. 136 */ 137 MU_CLI_OPTION_RETURN_ARGV, 138 139 /* Argument: none 140 * Description: Do not reorder options and arguments. 141 * Ref: The inorder member of struct mu_cli_setup and 142 * MU_PARSEOPT_IN_ORDER flag in opt.h 143 */ 144 MU_CLI_OPTION_IN_ORDER, 145 146 /* Argument: none 147 * Description: Don't provide standard options: -h, --help, --usage, 148 * --version. 149 * Ref: MU_PARSEOPT_NO_STDOPT flag in opt.h 150 */ 151 MU_CLI_OPTION_NO_STDOPT, 152 153 /* Argument: none 154 * Description: Don't exit on errors 155 * Ref: MU_PARSEOPT_NO_ERREXIT flag in opt.h 156 */ 157 MU_CLI_OPTION_NO_ERREXIT, 158 159 /* Argument: none 160 * Description: Apply all options immediately. 161 * Ref: MU_PARSEOPT_IMMEDIATE 162 */ 163 MU_CLI_OPTION_IMMEDIATE, 164 165 /* Argument: none 166 * Description: Don't sort options in help output. 167 * Ref: MU_PARSEOPT_NO_SORT flag in opt.h. 168 */ 169 MU_CLI_OPTION_NO_SORT, 170 171 /* Argument: char const * 172 * Description: Override the name of the program to use in error 173 * messages. 174 * NULL argument is a no-op. 175 * Ref: MU_PARSEOPT_PROG_NAME flag in opt.h 176 */ 177 MU_CLI_OPTION_PROG_NAME, 178 179 /* Argument: char const * 180 * Description: Documentation string for the program. It will be 181 * displayed on the line following the usage summary. 182 * NULL argument is a no-op. 183 * Ref: MU_PARSEOPT_PROG_DOC 184 */ 185 MU_CLI_OPTION_PROG_DOC, 186 187 /* Argument: char const * 188 * Description: Names of arguments for the program. These are 189 * displayed in the constructed usage summary. For example, if 190 * this keyword is set tp "A B" and the program name is "foo", then 191 * the help output will begin with 192 * Usage: foo A B 193 * 194 * Multiple instances are allowed. 195 * NULL argument is a no-op. 196 * Ref: MU_PARSEOPT_PROG_ARGS flag in opt.h 197 */ 198 MU_CLI_OPTION_PROG_ARGS, 199 200 /* Argument: char const * 201 * Description: Bug address for the package. 202 * Ref: MU_PARSEOPT_BUG_ADDRESS in opt.h 203 */ 204 MU_CLI_OPTION_BUG_ADDRESS, 205 206 /* Argument: char const * 207 * Description: Sets the PACKAGE_NAME. 208 * NULL argument is a no-op. 209 * Ref: MU_PARSEOPT_PACKAGE_NAME in opt.h 210 */ 211 MU_CLI_OPTION_PACKAGE_NAME, 212 213 /* Argument: char const * 214 * Description: URL of the package. 215 * NULL argument is a no-op. 216 * Ref: MU_PARSEOPT_PACKAGE_URL in opt.h 217 */ 218 MU_CLI_OPTION_PACKAGE_URL, 219 220 /* Argument: char const * 221 * Description: Extra help information. This will be displayed after 222 * the option list. 223 * NULL argument is a no-op. 224 * Ref: MU_PARSEOPT_EXTRA_INFO in opt.h 225 */ 226 MU_CLI_OPTION_EXTRA_INFO, 227 228 /* Argument: void (*) (struct mu_parseopt *, mu_stream_t) 229 * Description: Pointer to a function to be called as a part of the 230 * --help option handling, after outputting the option list. 231 * NULL argument is a no-op. 232 * Ref: po_help_hook member of struct mu_parseopt and the 233 * MU_PARSEOPT_HELP_HOOK flag in opt.h 234 */ 235 MU_CLI_OPTION_HELP_HOOK, 236 237 /* Argument: void * 238 * Description: Call-specific configuration data. This will be passed 239 * as the last argument to mu_cfg_tree_reduce. 240 * 241 * Ref: mu_cfg_tree_reduce 242 */ 243 MU_CLI_OPTION_DATA, 244 245 /* Argument: void (*) (struct mu_parseopt *, mu_stream_t) 246 * Description: User function to be called on --version. 247 * Ref: po_version_hook member of struct mu_parseopt and the 248 * MU_PARSEOPT_VERSION_HOOK flag in opt.h 249 */ 250 MU_CLI_OPTION_VERSION_HOOK, 251 252 /* Argument: void (*) (struct mu_parseopt *, mu_stream_t) 253 * Description: Pointer to a function to be called as a part of the 254 * --help option handling. This function will be called after printing 255 * initial program description (see MU_CLI_OPTION_PROG_DOC) and before 256 * printing the option summary. 257 * NULL argument is a no-op. 258 * Ref: po_prog_doc_hook member of struct mu_parseopt and the 259 * MU_PARSEOPT_PROG_DOC_HOOK in opt.h 260 */ 261 MU_CLI_OPTION_PROG_DOC_HOOK, 262 263 /* Argument: none 264 * Description: Long options start with single dash (a la find). Thid 265 * Disables recognition of traditional short options. 266 * Ref: MU_PARSEOPT_SINGLE_DASH flag in opt.h 267 */ 268 MU_CLI_OPTION_SINGLE_DASH, 269 270 /* Argument: char const * 271 * Description: Prefix that negates the value of a boolean option. 272 * NULL argument is a no-op. 273 * Ref: po_negation member of struct mu_parseopt and the 274 * MU_PARSEOPT_NEGATION flag in opt.h 275 */ 276 MU_CLI_OPTION_NEGATION, 277 278 /* Argument: char const * 279 * Description: Descriptive names of special arguments. If given, this 280 * will be printed in short usage summary after the regular options. 281 * NULL argument is a no-op. 282 * Ref: The po_special_args member of struct mu_parseopt and the 283 * MU_PARSEOPT_SPECIAL_ARGS flag in opt.h 284 */ 285 MU_CLI_OPTION_SPECIAL_ARGS, 286 287 288 /* Argument: char const * 289 * Description: Name of site-wide configuration file to parse. If NULL, 290 * the default site-wide configuration is assumed. 291 * Ref: The site_file member of struct mu_cfg_parse_hints and the 292 * MU_CFHINT_SITE_FILE flag in cfg.h 293 */ 294 MU_CLI_OPTION_CONF_SITE_FILE, 295 296 /* Argument: none 297 * Description: Enable the use of per-user configuration files. 298 * Ref: MU_CFHINT_PER_USER_FILE flag in cfg.h 299 */ 300 MU_CLI_OPTION_CONF_PER_USER_FILE, 301 302 /* Argument: none 303 * Description: Don't allow users to overide configuration settings 304 * from the command line. 305 * Ref: MU_CFHINT_NO_CONFIG_OVERRIDE flag in cfg.h 306 */ 307 MU_CLI_OPTION_CONF_NO_OVERRIDE, 308 309 /* Argument: char const * 310 * Description: Identifier of the per-program section in the configuration 311 * file or name of the per-program configuration file (used when 312 * processing the "include" statement with a directory name as its 313 * argument). If NULL or not set, program name is used. See also 314 * MU_CLI_OPTION_PROG_NAME. 315 * Ref: MU_CFHINT_PROGRAM flag in cfg.h 316 */ 317 MU_CLI_OPTION_CONF_PROGNAME, 318 }; 319 320 void mu_cli_simple (int argc, char **argv, ...); 321 322 #endif 323