Line data Source code
1 : // Copyright (c) 2006-2022 Made to Order Software Corp. All Rights Reserved
2 : //
3 : // https://snapwebsites.org/project/advgetopt
4 : // contact@m2osw.com
5 : //
6 : // This program is free software; you can redistribute it and/or modify
7 : // it under the terms of the GNU General Public License as published by
8 : // the Free Software Foundation; either version 2 of the License, or
9 : // (at your option) any later version.
10 : //
11 : // This program is distributed in the hope that it will be useful,
12 : // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 : // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 : // GNU General Public License for more details.
15 : //
16 : // You should have received a copy of the GNU General Public License along
17 : // with this program; if not, write to the Free Software Foundation, Inc.,
18 : // 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19 :
20 : /** \file
21 : * \brief Advanced getopt usage() implementation.
22 : *
23 : * The advgetopt class usage() and helper functions are grouped in this
24 : * file.
25 : */
26 :
27 : // self
28 : //
29 : #include "advgetopt/advgetopt.h"
30 :
31 :
32 : // advgetopt lib
33 : //
34 : #include "advgetopt/exception.h"
35 :
36 :
37 : // C++ lib
38 : //
39 : #include <iomanip>
40 : #include <iostream>
41 :
42 :
43 : // C lib
44 : //
45 : #include <unistd.h>
46 : #include <sys/ioctl.h>
47 :
48 :
49 : // last include
50 : //
51 : #include <snapdev/poison.h>
52 :
53 :
54 :
55 :
56 : namespace advgetopt
57 : {
58 :
59 :
60 :
61 : /** \brief Transform group names in --\<name>-help commands.
62 : *
63 : * This function allows for the group names to be transformed into help
64 : * command line options.
65 : */
66 331 : void getopt::parse_options_from_group_names()
67 : {
68 : // add the --long-help if at least one option uses the GROUP1 or GROUP2
69 : //
70 707 : for(auto it(f_options_by_name.begin())
71 707 : ; it != f_options_by_name.end()
72 : ; ++it)
73 : {
74 384 : if(it->second->has_flag(GETOPT_FLAG_SHOW_GROUP1 | GETOPT_FLAG_SHOW_GROUP2))
75 : {
76 16 : option_info::pointer_t opt(std::make_shared<option_info>("long-help"));
77 8 : opt->add_flag(GETOPT_FLAG_COMMAND_LINE
78 : | GETOPT_FLAG_FLAG
79 : | GETOPT_FLAG_GROUP_COMMANDS);
80 8 : opt->set_help("show all the help from all the available options.");
81 8 : f_options_by_name["long-help"] = opt;
82 8 : if(f_options_by_short_name.find(L'?') == f_options_by_short_name.end())
83 : {
84 8 : opt->set_short_name(L'?');
85 8 : f_options_by_short_name[L'?'] = opt;
86 : }
87 8 : break;
88 : }
89 : }
90 :
91 331 : if(f_options_environment.f_groups == nullptr)
92 : {
93 : // no groups, ignore following loop
94 : //
95 297 : return;
96 : }
97 :
98 102 : for(group_description const * grp = f_options_environment.f_groups
99 102 : ; grp->f_group != GETOPT_FLAG_GROUP_NONE
100 : ; ++grp)
101 : {
102 : // the name is not mandatory, without it you do not get the command
103 : // line option but still get the group description
104 : //
105 68 : if(grp->f_name != nullptr
106 6 : && *grp->f_name != '\0')
107 : {
108 12 : std::string const name(grp->f_name);
109 12 : std::string const option_name(name + "-help");
110 12 : option_info::pointer_t opt(std::make_shared<option_info>(option_name));
111 6 : opt->add_flag(GETOPT_FLAG_COMMAND_LINE
112 : | GETOPT_FLAG_FLAG
113 : | GETOPT_FLAG_GROUP_COMMANDS);
114 12 : opt->set_help("show help from the \""
115 12 : + name
116 18 : + "\" group of options.");
117 6 : f_options_by_name[option_name] = opt;
118 : }
119 : }
120 : }
121 :
122 :
123 : /** \brief Search for \p group in the list of group names.
124 : *
125 : * This function is used to search for the name of a group.
126 : *
127 : * Groups are used by the usage() function to list options by some user
128 : * selected group.
129 : *
130 : * For example, it is often that a tool has a set of commands such as
131 : * `--delete` and a set of options such as `--verbose`. These can represent
132 : * to clear groups of commands and options.
133 : *
134 : * \param[in] group The group to look for (i.e. GETOPT_FLAG_GROUP_ONE).
135 : *
136 : * \return The group structure or nullptr when not found.
137 : */
138 45 : group_description const * getopt::find_group(flag_t group) const
139 : {
140 45 : if(f_options_environment.f_groups == nullptr)
141 : {
142 2 : return nullptr;
143 : }
144 :
145 43 : if((group & ~GETOPT_FLAG_GROUP_MASK) != 0)
146 : {
147 29 : throw getopt_logic_error("group parameter must represent a valid group.");
148 : }
149 14 : if(group == GETOPT_FLAG_GROUP_NONE)
150 : {
151 1 : throw getopt_logic_error("group NONE cannot be assigned a name so you cannot search for it.");
152 : }
153 :
154 21 : for(group_description const * grp(f_options_environment.f_groups)
155 21 : ; grp->f_group != GETOPT_FLAG_GROUP_NONE
156 : ; ++grp)
157 : {
158 20 : if(group == grp->f_group)
159 : {
160 12 : if((grp->f_name == nullptr || *grp->f_name == '\0')
161 2 : && (grp->f_description == nullptr || *grp->f_description == '\0'))
162 : {
163 2 : throw getopt_logic_error("at least one of a group name or description must be defined (a non-empty string).");
164 : }
165 10 : return grp;
166 : }
167 : }
168 :
169 : // group not defined
170 : //
171 1 : return nullptr;
172 : }
173 :
174 :
175 : /** \brief Create a string of the command line arguments.
176 : *
177 : * This function assembles the command line arguments in a string and
178 : * returns that string.
179 : *
180 : * The function has the ability to wrap strings around for better formatting.
181 : *
182 : * The list of arguments to show is defined by the \p show parameter. When
183 : * \p show is 0, then only the regular and error arguments are shown.
184 : * Otherwise only the argumenst with the specified flags are show. Only
185 : * the `..._SHOW_...` flags are valid here.
186 : *
187 : * When an error occurs, it is customary to set \p show to
188 : * GETOPT_FLAG_SHOW_USAGE_ON_ERROR so only a limited set of arguments
189 : * are shown.
190 : *
191 : * The library offers two groups in case you have a command line tools
192 : * with a large number of options, those two can be used to only show
193 : * those specific set of options with using a specific `--help` argument.
194 : *
195 : * \note
196 : * This function does NOT print anything in the output. This is your
197 : * responsibility. We do it this way because you may be using a logger
198 : * and not want to print the usage in the \em wrong destination.
199 : *
200 : * \bug
201 : * The options are written from our map. This means the order will be
202 : * alphabetical and not the order in which you defined the options.
203 : * We are not looking into fixing this problem. That's just something
204 : * you want to keep in mind.
205 : *
206 : * \param[in] show Selection of the options to show.
207 : *
208 : * \return The assembled command line arguments.
209 : */
210 79 : std::string getopt::usage( flag_t show ) const
211 : {
212 158 : std::stringstream ss;
213 :
214 79 : flag_t specific_group(show & GETOPT_FLAG_GROUP_MASK);
215 :
216 : // ignore all the non-show flags
217 : //
218 79 : show &= GETOPT_FLAG_SHOW_USAGE_ON_ERROR
219 : | GETOPT_FLAG_SHOW_ALL
220 : | GETOPT_FLAG_SHOW_GROUP1
221 : | GETOPT_FLAG_SHOW_GROUP2;
222 :
223 79 : size_t const line_width(get_line_width());
224 79 : ss << breakup_line(process_help_string(f_options_environment.f_help_header), 0, line_width);
225 :
226 158 : std::string save_default;
227 158 : std::string save_help;
228 :
229 79 : flag_t pos(GETOPT_FLAG_GROUP_MINIMUM);
230 79 : flag_t group_max(GETOPT_FLAG_GROUP_MAXIMUM);
231 79 : if(f_options_environment.f_groups == nullptr)
232 : {
233 72 : group_max = GETOPT_FLAG_GROUP_MINIMUM;
234 72 : specific_group = GETOPT_FLAG_GROUP_NONE;
235 : }
236 7 : else if(specific_group != GETOPT_FLAG_GROUP_NONE)
237 : {
238 : // only display that specific group if asked to do so
239 : //
240 2 : pos = specific_group >> GETOPT_FLAG_GROUP_SHIFT;
241 2 : group_max = pos;
242 : }
243 :
244 307 : for(; pos <= group_max; ++pos)
245 : {
246 114 : bool group_name_shown(false);
247 114 : flag_t const group(pos << GETOPT_FLAG_GROUP_SHIFT);
248 885 : for(auto const & opt : f_options_by_name)
249 : {
250 1542 : if((opt.second->get_flags() & GETOPT_FLAG_GROUP_MASK) != group
251 771 : && f_options_environment.f_groups != nullptr)
252 : {
253 : // this could be optimized but we'd probably not see much
254 : // difference overall and it's just for the usage() call
255 : //
256 506 : continue;
257 : }
258 :
259 444 : std::string const help(opt.second->get_help());
260 265 : if(help.empty())
261 : {
262 : // ignore entries without help
263 : //
264 10 : continue;
265 : }
266 :
267 255 : if(opt.second->has_flag(GETOPT_FLAG_ALIAS))
268 : {
269 : // ignore entries representing an alias
270 : //
271 12 : continue;
272 : }
273 :
274 243 : if((show & GETOPT_FLAG_SHOW_ALL) == 0)
275 : {
276 183 : if(show != 0)
277 : {
278 66 : if(!opt.second->has_flag(show))
279 : {
280 : // usage selected group is not present in this option, ignore
281 : //
282 58 : continue;
283 : }
284 : }
285 117 : else if(opt.second->has_flag(GETOPT_FLAG_SHOW_GROUP1 | GETOPT_FLAG_SHOW_GROUP2))
286 : {
287 : // do not show specialized groups
288 : //
289 6 : continue;
290 : }
291 : }
292 :
293 179 : if(!group_name_shown)
294 : {
295 84 : group_name_shown = true;
296 :
297 84 : if(group != GETOPT_FLAG_GROUP_NONE)
298 : {
299 8 : group_description const * grp(find_group(group));
300 8 : if(grp != nullptr)
301 : {
302 8 : ss << std::endl
303 8 : << breakup_line(process_help_string(grp->f_description), 0, line_width);
304 : }
305 : }
306 : }
307 :
308 358 : std::stringstream argument;
309 :
310 179 : if(opt.second->is_default_option())
311 : {
312 6 : switch(opt.second->get_flags() & (GETOPT_FLAG_REQUIRED | GETOPT_FLAG_MULTIPLE))
313 : {
314 1 : case 0:
315 1 : argument << "[default argument]";
316 1 : break;
317 :
318 1 : case GETOPT_FLAG_REQUIRED:
319 1 : argument << "<default argument>";
320 1 : break;
321 :
322 2 : case GETOPT_FLAG_MULTIPLE:
323 2 : argument << "[default arguments]";
324 2 : break;
325 :
326 2 : case GETOPT_FLAG_REQUIRED | GETOPT_FLAG_MULTIPLE:
327 2 : argument << "<default arguments>";
328 2 : break;
329 :
330 : }
331 : }
332 : else
333 : {
334 173 : argument << "--" << opt.second->get_name();
335 173 : if(opt.second->get_short_name() != NO_SHORT_NAME)
336 : {
337 49 : argument << " or -" << short_name_to_string(opt.second->get_short_name());
338 : }
339 :
340 173 : switch(opt.second->get_flags() & (GETOPT_FLAG_FLAG | GETOPT_FLAG_REQUIRED | GETOPT_FLAG_MULTIPLE))
341 : {
342 1 : case 0:
343 1 : argument << " [<arg>]";
344 1 : break;
345 :
346 33 : case GETOPT_FLAG_REQUIRED:
347 33 : argument << " <arg>";
348 33 : break;
349 :
350 8 : case GETOPT_FLAG_MULTIPLE:
351 8 : argument << " {<arg>}";
352 8 : break;
353 :
354 6 : case GETOPT_FLAG_REQUIRED | GETOPT_FLAG_MULTIPLE:
355 6 : argument << " <arg> {<arg>}";
356 6 : break;
357 :
358 : }
359 : }
360 :
361 179 : if(opt.second->has_default())
362 : {
363 : argument << " (default is \""
364 9 : << opt.second->get_default()
365 18 : << "\")";
366 : }
367 :
368 : // Output argument string with help
369 : //
370 179 : if(opt.second->is_default_option())
371 : {
372 6 : save_default = argument.str();
373 6 : save_help = help;
374 : }
375 : else
376 : {
377 346 : ss << format_usage_string(argument.str()
378 346 : , process_help_string(help.c_str())
379 : , 30
380 : , line_width);
381 : }
382 : }
383 : }
384 :
385 79 : if(!save_default.empty())
386 : {
387 12 : ss << format_usage_string(save_default
388 12 : , process_help_string(save_help.c_str())
389 : , 30
390 : , line_width);
391 : }
392 :
393 79 : if(f_options_environment.f_help_footer != nullptr
394 77 : && f_options_environment.f_help_footer[0] != '\0')
395 : {
396 77 : ss << std::endl;
397 77 : ss << breakup_line(process_help_string(f_options_environment.f_help_footer), 0, line_width);
398 : }
399 :
400 158 : return ss.str();
401 : }
402 :
403 :
404 : /** \brief Change the % flags in help strings.
405 : *
406 : * This function goes through the help string and replaces the `%\<flag>`
407 : * with various content available in the getopt object.
408 : *
409 : * This is helpful for various reasons. For example, you may use the
410 : * same set of options in several different programs, in which case the
411 : * `%p` is likely useful to print out the name of the program currently
412 : * in use.
413 : *
414 : * Similarly we offer ways to print out lists of configuration files,
415 : * the environment variable name & value, etc. The following is the
416 : * list of supported flags:
417 : *
418 : * \li "%%" -- print out a percent
419 : * \li "%a" -- print out the project name (a.k.a. application name)
420 : * \li "%b" -- print out the build date
421 : * \li "%c" -- print out the copyright notice
422 : * \li "%d" -- print out the first directory with configuration files.
423 : * \li "%*d" -- print out the complete list of directories with configuration
424 : * files.
425 : * \li "%e" -- print out the name of the environment variable.
426 : * \li "%*e" -- print out the name and value of the environment variable.
427 : * \li "%f" -- print out the first configuration path and filename.
428 : * \li "%*f" -- print out all the configuration full paths.
429 : * \li "%g" -- print out the list of existing configuration files.
430 : * \li "%*g" -- print out the list of all possible configuration files.
431 : * \li "%i" -- print out the directory to option files.
432 : * \li "%l" -- print out the license.
433 : * \li "%o" -- show the configuration filename where changes get written.
434 : * \li "%p" -- print out the program basename.
435 : * \li "%*p" -- print out the full program name.
436 : * \li "%s" -- print out the group name.
437 : * \li "%t" -- print out the build time.
438 : * \li "%v" -- print out the version.
439 : * \li "%w" -- print out the list of all the writable configuration files.
440 : *
441 : * Here is an example where the `%p` can be used:
442 : *
443 : * \code
444 : * "Usage: %p [-opt] filename ..."
445 : * \endcode
446 : *
447 : * The other flags are more often used in places like the copyright notice
448 : * the footer, the license notice, etc.
449 : *
450 : * \param[in] help A string that may include `%` flags.
451 : *
452 : * \return The string with any '%\<flag>' replaced.
453 : *
454 : * \sa parse_program_name()
455 : */
456 344 : std::string getopt::process_help_string(char const * help) const
457 : {
458 344 : if(help == nullptr)
459 : {
460 1 : return std::string();
461 : }
462 :
463 686 : std::string result;
464 :
465 38943 : while(help[0] != '\0')
466 : {
467 19300 : if(help[0] == '%')
468 : {
469 410 : switch(help[1])
470 : {
471 13 : case '%':
472 13 : result += '%';
473 13 : help += 2;
474 13 : break;
475 :
476 98 : case '*':
477 98 : switch(help[2])
478 : {
479 19 : case 'd':
480 19 : if(f_options_environment.f_configuration_directories != nullptr)
481 : {
482 16 : bool first(true);
483 68 : for(char const * const * directories(f_options_environment.f_configuration_directories)
484 68 : ; *directories != nullptr
485 : ; ++directories)
486 : {
487 52 : if(first)
488 : {
489 13 : first = false;
490 : }
491 : else
492 : {
493 39 : result += ", ";
494 : }
495 52 : result += *directories;
496 : }
497 : }
498 19 : help += 3;
499 19 : break;
500 :
501 28 : case 'e':
502 28 : if(f_options_environment.f_environment_variable_name != nullptr
503 22 : && *f_options_environment.f_environment_variable_name != '\0')
504 : {
505 16 : result += f_options_environment.f_environment_variable_name;
506 16 : char const * env(getenv(f_options_environment.f_environment_variable_name));
507 16 : if(env != nullptr)
508 : {
509 3 : result += '=';
510 3 : result += env;
511 : }
512 : else
513 : {
514 13 : result += " (not set)";
515 : }
516 : }
517 28 : help += 3;
518 28 : break;
519 :
520 19 : case 'f':
521 19 : if(f_options_environment.f_configuration_files != nullptr)
522 : {
523 16 : bool first(true);
524 68 : for(char const * const * filenames(f_options_environment.f_configuration_files)
525 68 : ; *filenames != nullptr
526 : ; ++filenames)
527 : {
528 52 : if(first)
529 : {
530 13 : first = false;
531 : }
532 : else
533 : {
534 39 : result += ", ";
535 : }
536 52 : result += *filenames;
537 : }
538 : }
539 19 : help += 3;
540 19 : break;
541 :
542 19 : case 'g':
543 : {
544 38 : string_list_t list(get_configuration_filenames(false, false));
545 19 : bool first(true);
546 193 : for(auto n : list)
547 : {
548 174 : if(first)
549 : {
550 13 : first = false;
551 : }
552 : else
553 : {
554 161 : result += ", ";
555 : }
556 174 : result += n;
557 : }
558 38 : help += 3;
559 : }
560 19 : break;
561 :
562 13 : case 'p':
563 13 : result += f_program_fullname;
564 13 : help += 3;
565 13 : break;
566 :
567 : }
568 98 : break;
569 :
570 19 : case 'a':
571 19 : if(f_options_environment.f_project_name != nullptr)
572 : {
573 16 : result += f_options_environment.f_project_name;
574 : }
575 19 : help += 2;
576 19 : break;
577 :
578 19 : case 'b':
579 19 : if(f_options_environment.f_build_date != nullptr)
580 : {
581 16 : result += f_options_environment.f_build_date;
582 : }
583 19 : help += 2;
584 19 : break;
585 :
586 19 : case 'c':
587 19 : if(f_options_environment.f_copyright != nullptr)
588 : {
589 16 : result += f_options_environment.f_copyright;
590 : }
591 19 : help += 2;
592 19 : break;
593 :
594 19 : case 'd':
595 19 : if(f_options_environment.f_configuration_directories != nullptr
596 16 : && *f_options_environment.f_configuration_directories != nullptr)
597 : {
598 13 : result += *f_options_environment.f_configuration_directories;
599 : }
600 19 : help += 2;
601 19 : break;
602 :
603 28 : case 'e':
604 28 : if(f_options_environment.f_environment_variable_name != nullptr)
605 : {
606 22 : result += f_options_environment.f_environment_variable_name;
607 : }
608 28 : help += 2;
609 28 : break;
610 :
611 19 : case 'f':
612 19 : if(f_options_environment.f_configuration_files != nullptr
613 16 : && *f_options_environment.f_configuration_files != nullptr)
614 : {
615 13 : result += *f_options_environment.f_configuration_files;
616 : }
617 19 : help += 2;
618 19 : break;
619 :
620 22 : case 'g':
621 : {
622 44 : string_list_t list(get_configuration_filenames(true, false));
623 22 : bool first(true);
624 34 : for(auto n : list)
625 : {
626 12 : if(first)
627 : {
628 6 : first = false;
629 : }
630 : else
631 : {
632 6 : result += ", ";
633 : }
634 12 : result += n;
635 : }
636 44 : help += 2;
637 : }
638 22 : break;
639 :
640 19 : case 'i':
641 : // in the advgetopt_options.cpp, we clearly add a final "/"
642 : // so we want to add it here too, to be consistent
643 : {
644 38 : std::string directory("/usr/share/advgetopt/options/");
645 19 : if(f_options_environment.f_options_files_directory != nullptr
646 16 : && *f_options_environment.f_options_files_directory != '\0')
647 : {
648 13 : directory = f_options_environment.f_options_files_directory;
649 13 : if(directory.back() != '/')
650 : {
651 13 : directory += '/';
652 : }
653 : }
654 38 : result += directory;
655 : }
656 19 : help += 2;
657 19 : break;
658 :
659 19 : case 'l':
660 19 : if(f_options_environment.f_license != nullptr)
661 : {
662 16 : result += f_options_environment.f_license;
663 : }
664 19 : help += 2;
665 19 : break;
666 :
667 0 : case 'm':
668 0 : if(f_options_environment.f_section_variables_name != nullptr)
669 : {
670 0 : result += f_options_environment.f_section_variables_name;
671 : }
672 0 : help += 2;
673 0 : break;
674 :
675 19 : case 'o':
676 : {
677 38 : string_list_t const list(get_configuration_filenames(false, true));
678 19 : if(!list.empty())
679 : {
680 13 : result += list.back();
681 : }
682 38 : help += 2;
683 : }
684 19 : break;
685 :
686 32 : case 'p':
687 32 : result += f_program_name;
688 32 : help += 2;
689 32 : break;
690 :
691 5 : case 's':
692 5 : if(f_options_environment.f_group_name != nullptr)
693 : {
694 5 : result += f_options_environment.f_group_name;
695 : }
696 5 : help += 2;
697 5 : break;
698 :
699 19 : case 't':
700 19 : if(f_options_environment.f_build_time != nullptr)
701 : {
702 16 : result += f_options_environment.f_build_time;
703 : }
704 19 : help += 2;
705 19 : break;
706 :
707 19 : case 'v':
708 19 : if(f_options_environment.f_version != nullptr)
709 : {
710 16 : result += f_options_environment.f_version;
711 : }
712 19 : help += 2;
713 19 : break;
714 :
715 22 : case 'w':
716 : {
717 44 : string_list_t const list(get_configuration_filenames(true, true));
718 22 : bool first(true);
719 31 : for(auto n : list)
720 : {
721 9 : if(first)
722 : {
723 6 : first = false;
724 : }
725 : else
726 : {
727 3 : result += ", ";
728 : }
729 9 : result += n;
730 : }
731 44 : help += 2;
732 : }
733 22 : break;
734 :
735 : }
736 : }
737 : else
738 : {
739 18890 : result += help[0];
740 18890 : ++help;
741 : }
742 : }
743 :
744 343 : return result;
745 : }
746 :
747 :
748 : /** \brief Format a help string to make it fit on a given width.
749 : *
750 : * This function properly wraps a set of help strings so they fit in
751 : * your console. The width has to be given by you at the moment.
752 : *
753 : * The function takes two strings, the argument with it's options
754 : * and the actual help string for that argument. If the argument
755 : * is short enough, it will appear on the first line with the
756 : * first line of help. If not, then one whole line is reserved
757 : * just for the argument and the help starts on the next line.
758 : *
759 : * \param[in] argument The option name with -- and arguments.
760 : * \param[in] help The help string for this argument.
761 : * \param[in] option_width Number of characters reserved for the option.
762 : * \param[in] line_width The maximum number of characters to display in width.
763 : *
764 : * \return A help string formatted for display.
765 : */
766 318 : std::string getopt::format_usage_string(
767 : std::string const & argument
768 : , std::string const & help
769 : , size_t const option_width
770 : , size_t const line_width)
771 : {
772 636 : std::stringstream ss;
773 :
774 318 : ss << " ";
775 :
776 318 : if(argument.size() < option_width - 3)
777 : {
778 : // enough space on a single line
779 : //
780 : ss << argument
781 258 : << std::setw(option_width - 3 - argument.size())
782 516 : << " ";
783 : }
784 60 : else if(argument.size() >= line_width - 4)
785 : {
786 : // argument too long for even one line on the screen!?
787 : // call the function to break it up with indentation of 3
788 : //
789 2 : ss << breakup_line(argument, 3, line_width);
790 :
791 4 : if(!help.empty()
792 2 : && option_width > 0)
793 : {
794 2 : ss << std::setw(option_width) << " ";
795 : }
796 : }
797 : else
798 : {
799 : // argument too long for the help to follow immediately
800 : //
801 58 : ss << argument
802 58 : << std::endl
803 : << std::setw(option_width)
804 58 : << " ";
805 : }
806 :
807 318 : ss << breakup_line(help, option_width, line_width);
808 :
809 636 : return ss.str();
810 : }
811 :
812 :
813 : /** \brief Breakup a string on multiple lines.
814 : *
815 : * This function breaks up the specified \p line of text in one or more
816 : * strings to fit your output.
817 : *
818 : * The \p line_width represents the maximum number of characters that get
819 : * printed in a row.
820 : *
821 : * The \p option_width parameter is the number of characters in the left
822 : * margin. When dealing with a very long argument, this width is 3 characters.
823 : * When dealing with the help itself, it is expected to be around 30.
824 : *
825 : * \note
826 : * This function always makes sure that the resulting string ends with
827 : * a newline character unless the input \p line string is empty.
828 : *
829 : * \param[in] line The line to breakup.
830 : * \param[in] option_width The number of characters in the left margin.
831 : * \param[in] line_width The total number of characters in the output.
832 : *
833 : * \return The broken up line as required.
834 : */
835 550 : std::string getopt::breakup_line(std::string line
836 : , size_t const option_width
837 : , size_t const line_width)
838 : {
839 1100 : std::stringstream ss;
840 :
841 550 : size_t const width(line_width - option_width);
842 :
843 : // TODO: once we have C++17, avoid substr() using std::string_view instead
844 : //
845 1222 : while(line.size() > width)
846 : {
847 1344 : std::string l;
848 672 : std::string::size_type const nl(line.find('\n'));
849 672 : if(nl != std::string::npos
850 404 : && nl < width)
851 : {
852 236 : l = line.substr(0, nl);
853 236 : line = line.substr(nl + 1);
854 : }
855 436 : else if(std::isspace(line[width]))
856 : {
857 : // special case when the space is right at the edge
858 : //
859 38 : l = line.substr(0, width);
860 38 : size_t pos(width);
861 2 : do
862 : {
863 40 : ++pos;
864 : }
865 40 : while(std::isspace(line[pos]));
866 38 : line = line.substr(pos);
867 : }
868 : else
869 : {
870 : // search for the last space before the edge of the screen
871 : //
872 398 : std::string::size_type pos(line.find_last_of(' ', width));
873 398 : if(pos == std::string::npos)
874 : {
875 : // no space found, cut right at the edge...
876 : // (this should be really rare)
877 : //
878 78 : l = line.substr(0, width);
879 78 : line = line.substr(width);
880 : }
881 : else
882 : {
883 : // we found a space, write everything up to that space
884 : //
885 320 : l = line.substr(0, pos);
886 :
887 : // remove additional spaces from the start of the next line
888 : do // LCOV_EXCL_LINE
889 : {
890 320 : ++pos;
891 : }
892 320 : while(std::isspace(line[pos]));
893 320 : line = line.substr(pos);
894 : }
895 : }
896 :
897 672 : ss << l
898 672 : << std::endl;
899 :
900 : // more to print? if so we need the indentation
901 : //
902 1344 : if(!line.empty()
903 672 : && option_width > 0)
904 : {
905 192 : ss << std::setw( option_width ) << " ";
906 : }
907 : }
908 :
909 : // some leftover?
910 : //
911 550 : if(!line.empty())
912 : {
913 550 : ss << line << std::endl;
914 : }
915 :
916 1100 : return ss.str();
917 : }
918 :
919 :
920 :
921 : /** \brief Retrieve the width of one line in your console.
922 : *
923 : * This function retrieves the width of the console in number of characters.
924 : *
925 : * If the process is not connected to a TTY, then the function returns 80.
926 : *
927 : * If the width is less than 40, the function returns 40.
928 : *
929 : * \return The width of the console screen.
930 : */
931 284 : size_t getopt::get_line_width()
932 : {
933 284 : std::int64_t cols(80);
934 :
935 284 : if(isatty(STDOUT_FILENO))
936 : {
937 : // when running coverage, the output is redirected for logging purposes
938 : // which means that isatty() returns false -- so at this time I just
939 : // exclude those since they are unreachable from my standard Unit Tests
940 : //
941 0 : winsize w;
942 : if(ioctl(STDOUT_FILENO, TIOCGWINSZ, &w) != -1) // LCOV_EXCL_LINE
943 : {
944 : cols = std::max(static_cast<unsigned short>(40), w.ws_col); // LCOV_EXCL_LINE
945 : }
946 : }
947 :
948 284 : return cols;
949 : }
950 :
951 :
952 :
953 6 : } // namespace advgetopt
954 : // vim: ts=4 sw=4 et
|
