From 4e2df3d5f77ddaaa5bcba78714125dae0c806c70 Mon Sep 17 00:00:00 2001 From: "Gary R. Van Sickle" Date: Mon, 22 Aug 2022 13:55:36 -0500 Subject: [PATCH 1/2] optionparser1.4->1.7. Makefile.am adjustments to pick up the updated library. Passes all tests. --- src/Makefile.am | 2 +- third_party/Makefile.am | 26 +- third_party/optionparser-1.4/Doxyfile | 1781 ----------- .../optionparser-1.4/DoxygenLayout.xml | 193 -- third_party/optionparser-1.4/README_ARGC_ARGV | 48 - third_party/optionparser-1.4/src/Makefile | 53 - third_party/optionparser-1.4/src/example.cpp | 56 - .../optionparser-1.4/src/example_arg.cc | 160 - .../optionparser-1.4/src/optionparser.h | 2823 ----------------- third_party/optionparser-1.4/src/printUsage.h | 11 - third_party/optionparser-1.4/src/testodr1.cc | 50 - third_party/optionparser-1.4/src/testodr2.cc | 39 - .../optionparser-1.4/src/testparse.cpp | 368 --- .../optionparser-1.4/src/testprintusage.cpp | 167 - 14 files changed, 15 insertions(+), 5762 deletions(-) delete mode 100644 third_party/optionparser-1.4/Doxyfile delete mode 100644 third_party/optionparser-1.4/DoxygenLayout.xml delete mode 100644 third_party/optionparser-1.4/README_ARGC_ARGV delete mode 100644 third_party/optionparser-1.4/src/Makefile delete mode 100644 third_party/optionparser-1.4/src/example.cpp delete mode 100644 third_party/optionparser-1.4/src/example_arg.cc delete mode 100644 third_party/optionparser-1.4/src/optionparser.h delete mode 100644 third_party/optionparser-1.4/src/printUsage.h delete mode 100644 third_party/optionparser-1.4/src/testodr1.cc delete mode 100644 third_party/optionparser-1.4/src/testodr2.cc delete mode 100644 third_party/optionparser-1.4/src/testparse.cpp delete mode 100644 third_party/optionparser-1.4/src/testprintusage.cpp diff --git a/src/Makefile.am b/src/Makefile.am index 64d5ca27..b5ad478c 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -44,7 +44,7 @@ libsrc_la_SOURCES = \ sync_queue_impl_selector.h \ TypeManager.cpp TypeManager.h -libsrc_la_CPPFLAGS = -I $(srcdir)/../third_party/optionparser-1.4/src $(AM_CPPFLAGS) +libsrc_la_CPPFLAGS = -I $(srcdir)/../third_party/optionparser-1.7/src $(AM_CPPFLAGS) libsrc_la_CFLAGS = $(AM_CFLAGS) $(PCRE_CFLAGS) $(PCRE2_CFLAGS) libsrc_la_CXXFLAGS = $(AM_CXXFLAGS) $(PCRE_CFLAGS) $(PCRE2_CFLAGS) libsrc_la_LIBADD = diff --git a/third_party/Makefile.am b/third_party/Makefile.am index 18e30303..e01f798b 100644 --- a/third_party/Makefile.am +++ b/third_party/Makefile.am @@ -50,20 +50,22 @@ check_LTLIBRARIES = ### The Lean Mean C++ Option Parser ### +LMCPPOP_RELEASE_NO = 1.7 + # This is a header-only library. We just need to rig things up so it gets distributed. EXTRA_DIST += \ - optionparser-1.4/DoxygenLayout.xml \ - optionparser-1.4/README_ARGC_ARGV \ - optionparser-1.4/src/printUsage.h \ - optionparser-1.4/src/example.cpp \ - optionparser-1.4/src/testodr1.cc \ - optionparser-1.4/src/testprintusage.cpp \ - optionparser-1.4/src/example_arg.cc \ - optionparser-1.4/src/testodr2.cc \ - optionparser-1.4/src/testparse.cpp \ - optionparser-1.4/src/Makefile \ - optionparser-1.4/src/optionparser.h \ - optionparser-1.4/Doxyfile + optionparser-$(LMCPPOP_RELEASE_NO)/DoxygenLayout.xml \ + optionparser-$(LMCPPOP_RELEASE_NO)/README_ARGC_ARGV \ + optionparser-$(LMCPPOP_RELEASE_NO)/src/printUsage.h \ + optionparser-$(LMCPPOP_RELEASE_NO)/src/example.cpp \ + optionparser-$(LMCPPOP_RELEASE_NO)/src/testodr1.cc \ + optionparser-$(LMCPPOP_RELEASE_NO)/src/testprintusage.cpp \ + optionparser-$(LMCPPOP_RELEASE_NO)/src/example_arg.cc \ + optionparser-$(LMCPPOP_RELEASE_NO)/src/testodr2.cc \ + optionparser-$(LMCPPOP_RELEASE_NO)/src/testparse.cpp \ + optionparser-$(LMCPPOP_RELEASE_NO)/src/Makefile \ + optionparser-$(LMCPPOP_RELEASE_NO)/src/optionparser.h \ + optionparser-$(LMCPPOP_RELEASE_NO)/Doxyfile ### ### Google Test diff --git a/third_party/optionparser-1.4/Doxyfile b/third_party/optionparser-1.4/Doxyfile deleted file mode 100644 index 02a8f14e..00000000 --- a/third_party/optionparser-1.4/Doxyfile +++ /dev/null @@ -1,1781 +0,0 @@ -# Doxyfile 1.7.6.1 - -# This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project. -# -# All text after a hash (#) is considered a comment and will be ignored. -# The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" "). - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- - -# This tag specifies the encoding used for all characters in the config file -# that follow. The default is UTF-8 which is also the encoding used for all -# text before the first occurrence of this tag. Doxygen uses libiconv (or the -# iconv built into libc) for the transcoding. See -# http://www.gnu.org/software/libiconv for the list of possible encodings. - -DOXYFILE_ENCODING = UTF-8 - -# The PROJECT_NAME tag is a single word (or sequence of words) that should -# identify the project. Note that if you do not use Doxywizard you need -# to put quotes around the project name if it contains spaces. - -PROJECT_NAME = "The Lean Mean C++ Option Parser" - -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. - -PROJECT_NUMBER = - -# Using the PROJECT_BRIEF tag one can provide an optional one line description -# for a project that appears at the top of each page and should give viewer -# a quick idea about the purpose of the project. Keep the description short. - -PROJECT_BRIEF = - -# With the PROJECT_LOGO tag one can specify an logo or icon that is -# included in the documentation. The maximum height of the logo should not -# exceed 55 pixels and the maximum width should not exceed 200 pixels. -# Doxygen will copy the logo to the output directory. - -PROJECT_LOGO = - -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. - -OUTPUT_DIRECTORY = - -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of -# source files, where putting all generated files in the same directory would -# otherwise cause performance problems for the file system. - -CREATE_SUBDIRS = NO - -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, -# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, -# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English -# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, -# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, -# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. - -OUTPUT_LANGUAGE = English - -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. - -BRIEF_MEMBER_DESC = YES - -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the -# brief descriptions will be completely suppressed. - -REPEAT_BRIEF = YES - -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is -# used as the annotated text. Otherwise, the brief description is used as-is. -# If left blank, the following values are used ("$name" is automatically -# replaced with the name of the entity): "The $name class" "The $name widget" -# "The $name file" "is" "provides" "specifies" "contains" -# "represents" "a" "an" "the" - -ABBREVIATE_BRIEF = - -# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief -# description. - -ALWAYS_DETAILED_SEC = YES - -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all -# inherited members of a class in the documentation of that class as if those -# members were ordinary class members. Constructors, destructors and assignment -# operators of the base classes will not be shown. - -INLINE_INHERITED_MEMB = NO - -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. - -FULL_PATH_NAMES = YES - -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. - -STRIP_FROM_PATH = - -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. - -STRIP_FROM_INC_PATH = - -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful if your file system -# doesn't support long names like on DOS, Mac, or CD-ROM. - -SHORT_NAMES = NO - -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like regular Qt-style comments -# (thus requiring an explicit @brief command for a brief description.) - -JAVADOC_AUTOBRIEF = NO - -# If the QT_AUTOBRIEF tag is set to YES then Doxygen will -# interpret the first line (until the first dot) of a Qt-style -# comment as the brief description. If set to NO, the comments -# will behave just like regular Qt-style comments (thus requiring -# an explicit \brief command for a brief description.) - -QT_AUTOBRIEF = NO - -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. - -MULTILINE_CPP_IS_BRIEF = NO - -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. - -INHERIT_DOCS = YES - -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce -# a new page for each member. If set to NO, the documentation of a member will -# be part of the file/class/namespace that contains it. - -SEPARATE_MEMBER_PAGES = NO - -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. - -TAB_SIZE = 8 - -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. - -ALIASES = - -# This tag can be used to specify a number of word-keyword mappings (TCL only). -# A mapping has the form "name=value". For example adding -# "class=itcl::class" will allow you to use the command class in the -# itcl::class meaning. - -TCL_SUBST = - -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C -# sources only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. - -OPTIMIZE_OUTPUT_FOR_C = NO - -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java -# sources only. Doxygen will then generate output that is more tailored for -# Java. For instance, namespaces will be presented as packages, qualified -# scopes will look different, etc. - -OPTIMIZE_OUTPUT_JAVA = NO - -# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran -# sources only. Doxygen will then generate output that is more tailored for -# Fortran. - -OPTIMIZE_FOR_FORTRAN = NO - -# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL -# sources. Doxygen will then generate output that is tailored for -# VHDL. - -OPTIMIZE_OUTPUT_VHDL = NO - -# Doxygen selects the parser to use depending on the extension of the files it -# parses. With this tag you can assign which parser to use for a given extension. -# Doxygen has a built-in mapping, but you can override or extend it using this -# tag. The format is ext=language, where ext is a file extension, and language -# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, -# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make -# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C -# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions -# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. - -EXTENSION_MAPPING = - -# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want -# to include (a tag file for) the STL sources as input, then you should -# set this tag to YES in order to let doxygen match functions declarations and -# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. -# func(std::string) {}). This also makes the inheritance and collaboration -# diagrams that involve STL classes more complete and accurate. - -BUILTIN_STL_SUPPORT = NO - -# If you use Microsoft's C++/CLI language, you should set this option to YES to -# enable parsing support. - -CPP_CLI_SUPPORT = NO - -# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. -# Doxygen will parse them like normal C++ but will assume all classes use public -# instead of private inheritance when no explicit protection keyword is present. - -SIP_SUPPORT = NO - -# For Microsoft's IDL there are propget and propput attributes to indicate getter -# and setter methods for a property. Setting this option to YES (the default) -# will make doxygen replace the get and set methods by a property in the -# documentation. This will only work if the methods are indeed getting or -# setting a simple type. If this is not the case, or you want to show the -# methods anyway, you should set this option to NO. - -IDL_PROPERTY_SUPPORT = YES - -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. - -DISTRIBUTE_GROUP_DOC = NO - -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. - -SUBGROUPING = YES - -# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and -# unions are shown inside the group in which they are included (e.g. using -# @ingroup) instead of on a separate page (for HTML and Man pages) or -# section (for LaTeX and RTF). - -INLINE_GROUPED_CLASSES = NO - -# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and -# unions with only public data fields will be shown inline in the documentation -# of the scope in which they are defined (i.e. file, namespace, or group -# documentation), provided this scope is documented. If set to NO (the default), -# structs, classes, and unions are shown on a separate page (for HTML and Man -# pages) or section (for LaTeX and RTF). - -INLINE_SIMPLE_STRUCTS = NO - -# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum -# is documented as struct, union, or enum with the name of the typedef. So -# typedef struct TypeS {} TypeT, will appear in the documentation as a struct -# with name TypeT. When disabled the typedef will appear as a member of a file, -# namespace, or class. And the struct will be named TypeS. This can typically -# be useful for C code in case the coding convention dictates that all compound -# types are typedef'ed and only the typedef is referenced, never the tag name. - -TYPEDEF_HIDES_STRUCT = NO - -# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to -# determine which symbols to keep in memory and which to flush to disk. -# When the cache is full, less often used symbols will be written to disk. -# For small to medium size projects (<1000 input files) the default value is -# probably good enough. For larger projects a too small cache size can cause -# doxygen to be busy swapping symbols to and from disk most of the time -# causing a significant performance penalty. -# If the system has enough physical memory increasing the cache will improve the -# performance by keeping more symbols in memory. Note that the value works on -# a logarithmic scale so increasing the size by one will roughly double the -# memory usage. The cache size is given by this formula: -# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, -# corresponding to a cache size of 2^16 = 65536 symbols. - -SYMBOL_CACHE_SIZE = 0 - -# Similar to the SYMBOL_CACHE_SIZE the size of the symbol lookup cache can be -# set using LOOKUP_CACHE_SIZE. This cache is used to resolve symbols given -# their name and scope. Since this can be an expensive process and often the -# same symbol appear multiple times in the code, doxygen keeps a cache of -# pre-resolved symbols. If the cache is too small doxygen will become slower. -# If the cache is too large, memory is wasted. The cache size is given by this -# formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range is 0..9, the default is 0, -# corresponding to a cache size of 2^16 = 65536 symbols. - -LOOKUP_CACHE_SIZE = 0 - -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- - -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES - -EXTRACT_ALL = NO - -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. - -EXTRACT_PRIVATE = YES - -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. - -EXTRACT_STATIC = NO - -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. - -EXTRACT_LOCAL_CLASSES = NO - -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. - -EXTRACT_LOCAL_METHODS = NO - -# If this flag is set to YES, the members of anonymous namespaces will be -# extracted and appear in the documentation as a namespace called -# 'anonymous_namespace{file}', where file will be replaced with the base -# name of the file that contains the anonymous namespace. By default -# anonymous namespaces are hidden. - -EXTRACT_ANON_NSPACES = YES - -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_MEMBERS = YES - -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_CLASSES = YES - -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the -# documentation. - -HIDE_FRIEND_COMPOUNDS = NO - -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. - -HIDE_IN_BODY_DOCS = NO - -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. - -INTERNAL_DOCS = YES - -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. - -CASE_SENSE_NAMES = YES - -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. - -HIDE_SCOPE_NAMES = YES - -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. - -SHOW_INCLUDE_FILES = NO - -# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen -# will list include files with double quotes in the documentation -# rather than with sharp brackets. - -FORCE_LOCAL_INCLUDES = YES - -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. - -INLINE_INFO = NO - -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. - -SORT_MEMBER_DOCS = YES - -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. - -SORT_BRIEF_DOCS = NO - -# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen -# will sort the (brief and detailed) documentation of class members so that -# constructors and destructors are listed first. If set to NO (the default) -# the constructors will appear in the respective orders defined by -# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. -# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO -# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO. - -SORT_MEMBERS_CTORS_1ST = NO - -# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the -# hierarchy of group names into alphabetical order. If set to NO (the default) -# the group names will appear in their defined order. - -SORT_GROUP_NAMES = NO - -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. -# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. - -SORT_BY_SCOPE_NAME = NO - -# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to -# do proper type resolution of all parameters of a function it will reject a -# match between the prototype and the implementation of a member function even -# if there is only one candidate or it is obvious which candidate to choose -# by doing a simple string match. By disabling STRICT_PROTO_MATCHING doxygen -# will still accept a match between prototype and implementation in such cases. - -STRICT_PROTO_MATCHING = NO - -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. - -GENERATE_TODOLIST = YES - -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. - -GENERATE_TESTLIST = YES - -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. - -GENERATE_BUGLIST = YES - -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. - -GENERATE_DEPRECATEDLIST= YES - -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. - -ENABLED_SECTIONS = - -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or macro consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and macros in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. - -MAX_INITIALIZER_LINES = 30 - -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the -# list will mention the files that were used to generate the documentation. - -SHOW_USED_FILES = YES - -# If the sources in your project are distributed over multiple directories -# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy -# in the documentation. The default is NO. - -SHOW_DIRECTORIES = NO - -# Set the SHOW_FILES tag to NO to disable the generation of the Files page. -# This will remove the Files entry from the Quick Index and from the -# Folder Tree View (if specified). The default is YES. - -SHOW_FILES = YES - -# Set the SHOW_NAMESPACES tag to NO to disable the generation of the -# Namespaces page. -# This will remove the Namespaces entry from the Quick Index -# and from the Folder Tree View (if specified). The default is YES. - -SHOW_NAMESPACES = YES - -# The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from -# the version control system). Doxygen will invoke the program by executing (via -# popen()) the command , where is the value of -# the FILE_VERSION_FILTER tag, and is the name of an input file -# provided by doxygen. Whatever the program writes to standard output -# is used as the file version. See the manual for examples. - -FILE_VERSION_FILTER = - -# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed -# by doxygen. The layout file controls the global structure of the generated -# output files in an output format independent way. The create the layout file -# that represents doxygen's defaults, run doxygen with the -l option. -# You can optionally specify a file name after the option, if omitted -# DoxygenLayout.xml will be used as the name of the layout file. - -LAYOUT_FILE = DoxygenLayout.xml - -# The CITE_BIB_FILES tag can be used to specify one or more bib files -# containing the references data. This must be a list of .bib files. The -# .bib extension is automatically appended if omitted. Using this command -# requires the bibtex tool to be installed. See also -# http://en.wikipedia.org/wiki/BibTeX for more info. For LaTeX the style -# of the bibliography can be controlled using LATEX_BIB_STYLE. To use this -# feature you need bibtex and perl available in the search path. - -CITE_BIB_FILES = - -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- - -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. - -QUIET = YES - -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. - -WARNINGS = YES - -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. - -WARN_IF_UNDOCUMENTED = YES - -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. - -WARN_IF_DOC_ERROR = YES - -# The WARN_NO_PARAMDOC option can be enabled to get warnings for -# functions that are documented, but have no documentation for their parameters -# or return value. If set to NO (the default) doxygen will only warn about -# wrong or incomplete parameter documentation, but not about the absence of -# documentation. - -WARN_NO_PARAMDOC = NO - -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. Optionally the format may contain -# $version, which will be replaced by the version of the file (if it could -# be obtained via FILE_VERSION_FILTER) - -WARN_FORMAT = "$file:$line: $text" - -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. - -WARN_LOGFILE = - -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- - -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. - -INPUT = src/ - -# This tag can be used to specify the character encoding of the source files -# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is -# also the default input encoding. Doxygen uses libiconv (or the iconv built -# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for -# the list of possible encodings. - -INPUT_ENCODING = UTF-8 - -# If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh -# *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py -# *.f90 *.f *.for *.vhd *.vhdl - -FILE_PATTERNS = - -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. - -RECURSIVE = NO - -# The EXCLUDE tag can be used to specify files and/or directories that should be -# excluded from the INPUT source files. This way you can easily exclude a -# subdirectory from a directory tree whose root is specified with the INPUT tag. -# Note that relative paths are relative to the directory from which doxygen is -# run. - -EXCLUDE = - -# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or -# directories that are symbolic links (a Unix file system feature) are excluded -# from the input. - -EXCLUDE_SYMLINKS = NO - -# If the value of the INPUT tag contains directories, you can use the -# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude -# certain files from those directories. Note that the wildcards are matched -# against the file with absolute path, so to exclude all test directories -# for example use the pattern */test/* - -EXCLUDE_PATTERNS = - -# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names -# (namespaces, classes, functions, etc.) that should be excluded from the -# output. The symbol name can be a fully qualified name, a word, or if the -# wildcard * is used, a substring. Examples: ANamespace, AClass, -# AClass::ANamespace, ANamespace::*Test - -EXCLUDE_SYMBOLS = - -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). - -EXAMPLE_PATH = src/ - -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. - -EXAMPLE_PATTERNS = example* - -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. - -EXAMPLE_RECURSIVE = NO - -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). - -IMAGE_PATH = - -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command , where -# is the value of the INPUT_FILTER tag, and is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. -# If FILTER_PATTERNS is specified, this tag will be -# ignored. - -INPUT_FILTER = - -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. -# Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. -# The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty or if -# non of the patterns match the file name, INPUT_FILTER is applied. - -FILTER_PATTERNS = - -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). - -FILTER_SOURCE_FILES = NO - -# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file -# pattern. A pattern will override the setting for FILTER_PATTERN (if any) -# and it is also possible to disable source filtering for a specific pattern -# using *.ext= (so without naming a filter). This option only has effect when -# FILTER_SOURCE_FILES is enabled. - -FILTER_SOURCE_PATTERNS = - -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- - -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. - -SOURCE_BROWSER = YES - -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. - -INLINE_SOURCES = NO - -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. - -STRIP_CODE_COMMENTS = YES - -# If the REFERENCED_BY_RELATION tag is set to YES -# then for each documented function all documented -# functions referencing it will be listed. - -REFERENCED_BY_RELATION = NO - -# If the REFERENCES_RELATION tag is set to YES -# then for each documented function all documented entities -# called/used by that function will be listed. - -REFERENCES_RELATION = NO - -# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) -# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from -# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will -# link to the source code. -# Otherwise they will link to the documentation. - -REFERENCES_LINK_SOURCE = YES - -# If the USE_HTAGS tag is set to YES then the references to source code -# will point to the HTML generated by the htags(1) tool instead of doxygen -# built-in source browser. The htags tool is part of GNU's global source -# tagging system (see http://www.gnu.org/software/global/global.html). You -# will need version 4.8.6 or higher. - -USE_HTAGS = NO - -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. - -VERBATIM_HEADERS = YES - -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- - -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. - -ALPHABETICAL_INDEX = NO - -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) - -COLS_IN_ALPHA_INDEX = 5 - -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. - -IGNORE_PREFIX = - -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- - -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. - -GENERATE_HTML = YES - -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. - -HTML_OUTPUT = html-dev - -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. - -HTML_FILE_EXTENSION = .html - -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a -# standard header. Note that when using a custom header you are responsible -# for the proper inclusion of any scripts and style sheets that doxygen -# needs, which is dependent on the configuration options used. -# It is advised to generate a default header using "doxygen -w html -# header.html footer.html stylesheet.css YourConfigFile" and then modify -# that header. Note that the header is subject to change so you typically -# have to redo this when upgrading to a newer version of doxygen or when -# changing the value of configuration settings such as GENERATE_TREEVIEW! - -HTML_HEADER = - -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. - -HTML_FOOTER = - -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# style sheet in the HTML output directory as well, or it will be erased! - -HTML_STYLESHEET = - -# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or -# other source files which should be copied to the HTML output directory. Note -# that these files will be copied to the base HTML output directory. Use the -# $relpath$ marker in the HTML_HEADER and/or HTML_FOOTER files to load these -# files. In the HTML_STYLESHEET file, use the file name only. Also note that -# the files will be copied as-is; there are no commands or markers available. - -HTML_EXTRA_FILES = - -# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. -# Doxygen will adjust the colors in the style sheet and background images -# according to this color. Hue is specified as an angle on a colorwheel, -# see http://en.wikipedia.org/wiki/Hue for more information. -# For instance the value 0 represents red, 60 is yellow, 120 is green, -# 180 is cyan, 240 is blue, 300 purple, and 360 is red again. -# The allowed range is 0 to 359. - -HTML_COLORSTYLE_HUE = 120 - -# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of -# the colors in the HTML output. For a value of 0 the output will use -# grayscales only. A value of 255 will produce the most vivid colors. - -HTML_COLORSTYLE_SAT = 150 - -# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to -# the luminance component of the colors in the HTML output. Values below -# 100 gradually make the output lighter, whereas values above 100 make -# the output darker. The value divided by 100 is the actual gamma applied, -# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, -# and 100 does not change the gamma. - -HTML_COLORSTYLE_GAMMA = 170 - -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting -# this to NO can help when comparing the output of multiple runs. - -HTML_TIMESTAMP = YES - -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. - -HTML_ALIGN_MEMBERS = YES - -# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML -# documentation will contain sections that can be hidden and shown after the -# page has loaded. For this to work a browser that supports -# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox -# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). - -HTML_DYNAMIC_SECTIONS = NO - -# If the GENERATE_DOCSET tag is set to YES, additional index files -# will be generated that can be used as input for Apple's Xcode 3 -# integrated development environment, introduced with OSX 10.5 (Leopard). -# To create a documentation set, doxygen will generate a Makefile in the -# HTML output directory. Running make will produce the docset in that -# directory and running "make install" will install the docset in -# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find -# it at startup. -# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html -# for more information. - -GENERATE_DOCSET = NO - -# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the -# feed. A documentation feed provides an umbrella under which multiple -# documentation sets from a single provider (such as a company or product suite) -# can be grouped. - -DOCSET_FEEDNAME = "Doxygen generated docs" - -# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that -# should uniquely identify the documentation set bundle. This should be a -# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen -# will append .docset to the name. - -DOCSET_BUNDLE_ID = org.doxygen.Project - -# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify -# the documentation publisher. This should be a reverse domain-name style -# string, e.g. com.mycompany.MyDocSet.documentation. - -DOCSET_PUBLISHER_ID = org.doxygen.Publisher - -# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. - -DOCSET_PUBLISHER_NAME = Publisher - -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) -# of the generated HTML documentation. - -GENERATE_HTMLHELP = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be -# written to the html output directory. - -CHM_FILE = - -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. - -HHC_LOCATION = - -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). - -GENERATE_CHI = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING -# is used to encode HtmlHelp index (hhk), content (hhc) and project file -# content. - -CHM_INDEX_ENCODING = - -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. - -BINARY_TOC = NO - -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. - -TOC_EXPAND = NO - -# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and -# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated -# that can be used as input for Qt's qhelpgenerator to generate a -# Qt Compressed Help (.qch) of the generated HTML documentation. - -GENERATE_QHP = NO - -# If the QHG_LOCATION tag is specified, the QCH_FILE tag can -# be used to specify the file name of the resulting .qch file. -# The path specified is relative to the HTML output folder. - -QCH_FILE = - -# The QHP_NAMESPACE tag specifies the namespace to use when generating -# Qt Help Project output. For more information please see -# http://doc.trolltech.com/qthelpproject.html#namespace - -QHP_NAMESPACE = org.doxygen.Project - -# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating -# Qt Help Project output. For more information please see -# http://doc.trolltech.com/qthelpproject.html#virtual-folders - -QHP_VIRTUAL_FOLDER = doc - -# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to -# add. For more information please see -# http://doc.trolltech.com/qthelpproject.html#custom-filters - -QHP_CUST_FILTER_NAME = - -# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the -# custom filter to add. For more information please see -# -# Qt Help Project / Custom Filters. - -QHP_CUST_FILTER_ATTRS = - -# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this -# project's -# filter section matches. -# -# Qt Help Project / Filter Attributes. - -QHP_SECT_FILTER_ATTRS = - -# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can -# be used to specify the location of Qt's qhelpgenerator. -# If non-empty doxygen will try to run qhelpgenerator on the generated -# .qhp file. - -QHG_LOCATION = - -# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files -# will be generated, which together with the HTML files, form an Eclipse help -# plugin. To install this plugin and make it available under the help contents -# menu in Eclipse, the contents of the directory containing the HTML and XML -# files needs to be copied into the plugins directory of eclipse. The name of -# the directory within the plugins directory should be the same as -# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before -# the help appears. - -GENERATE_ECLIPSEHELP = NO - -# A unique identifier for the eclipse help plugin. When installing the plugin -# the directory name containing the HTML and XML files should also have -# this name. - -ECLIPSE_DOC_ID = org.doxygen.Project - -# The DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) -# at top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. Since the tabs have the same information as the -# navigation tree you can set this option to NO if you already set -# GENERATE_TREEVIEW to YES. - -DISABLE_INDEX = NO - -# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index -# structure should be generated to display hierarchical information. -# If the tag value is set to YES, a side panel will be generated -# containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). -# Windows users are probably better off using the HTML help feature. -# Since the tree basically has the same information as the tab index you -# could consider to set DISABLE_INDEX to NO when enabling this option. - -GENERATE_TREEVIEW = NO - -# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values -# (range [0,1..20]) that doxygen will group on one line in the generated HTML -# documentation. Note that a value of 0 will completely suppress the enum -# values from appearing in the overview section. - -ENUM_VALUES_PER_LINE = 4 - -# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, -# and Class Hierarchy pages using a tree view instead of an ordered list. - -USE_INLINE_TREES = NO - -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. - -TREEVIEW_WIDTH = 250 - -# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open -# links to external symbols imported via tag files in a separate window. - -EXT_LINKS_IN_WINDOW = NO - -# Use this tag to change the font size of Latex formulas included -# as images in the HTML documentation. The default is 10. Note that -# when you change the font size after a successful doxygen run you need -# to manually remove any form_*.png images from the HTML output directory -# to force them to be regenerated. - -FORMULA_FONTSIZE = 10 - -# Use the FORMULA_TRANPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are -# not supported properly for IE 6.0, but are supported on all modern browsers. -# Note that when changing this option you need to delete any form_*.png files -# in the HTML output before the changes have effect. - -FORMULA_TRANSPARENT = YES - -# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax -# (see http://www.mathjax.org) which uses client side Javascript for the -# rendering instead of using prerendered bitmaps. Use this if you do not -# have LaTeX installed or if you want to formulas look prettier in the HTML -# output. When enabled you also need to install MathJax separately and -# configure the path to it using the MATHJAX_RELPATH option. - -USE_MATHJAX = NO - -# When MathJax is enabled you need to specify the location relative to the -# HTML output directory using the MATHJAX_RELPATH option. The destination -# directory should contain the MathJax.js script. For instance, if the mathjax -# directory is located at the same level as the HTML output directory, then -# MATHJAX_RELPATH should be ../mathjax. The default value points to the -# mathjax.org site, so you can quickly see the result without installing -# MathJax, but it is strongly recommended to install a local copy of MathJax -# before deployment. - -MATHJAX_RELPATH = http://www.mathjax.org/mathjax - -# The MATHJAX_EXTENSIONS tag can be used to specify one or MathJax extension -# names that should be enabled during MathJax rendering. - -MATHJAX_EXTENSIONS = - -# When the SEARCHENGINE tag is enabled doxygen will generate a search box -# for the HTML output. The underlying search engine uses javascript -# and DHTML and should work on any modern browser. Note that when using -# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets -# (GENERATE_DOCSET) there is already a search function so this one should -# typically be disabled. For large projects the javascript based search engine -# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. - -SEARCHENGINE = YES - -# When the SERVER_BASED_SEARCH tag is enabled the search engine will be -# implemented using a PHP enabled web server instead of at the web client -# using Javascript. Doxygen will generate the search PHP script and index -# file to put on the web server. The advantage of the server -# based approach is that it scales better to large projects and allows -# full text search. The disadvantages are that it is more difficult to setup -# and does not have live searching capabilities. - -SERVER_BASED_SEARCH = NO - -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- - -# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will -# generate Latex output. - -GENERATE_LATEX = NO - -# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `latex' will be used as the default path. - -LATEX_OUTPUT = latex - -# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be -# invoked. If left blank `latex' will be used as the default command name. -# Note that when enabling USE_PDFLATEX this option is only used for -# generating bitmaps for formulas in the HTML output, but not in the -# Makefile that is written to the output directory. - -LATEX_CMD_NAME = latex - -# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to -# generate index for LaTeX. If left blank `makeindex' will be used as the -# default command name. - -MAKEINDEX_CMD_NAME = makeindex - -# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact -# LaTeX documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_LATEX = NO - -# The PAPER_TYPE tag can be used to set the paper type that is used -# by the printer. Possible values are: a4, letter, legal and -# executive. If left blank a4wide will be used. - -PAPER_TYPE = a4 - -# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX -# packages that should be included in the LaTeX output. - -EXTRA_PACKAGES = - -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for -# the generated latex document. The header should contain everything until -# the first chapter. If it is left blank doxygen will generate a -# standard header. Notice: only use this tag if you know what you are doing! - -LATEX_HEADER = - -# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for -# the generated latex document. The footer should contain everything after -# the last chapter. If it is left blank doxygen will generate a -# standard footer. Notice: only use this tag if you know what you are doing! - -LATEX_FOOTER = - -# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated -# is prepared for conversion to pdf (using ps2pdf). The pdf file will -# contain links (just like the HTML output) instead of page references -# This makes the output suitable for online browsing using a pdf viewer. - -PDF_HYPERLINKS = YES - -# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of -# plain latex in the generated Makefile. Set this option to YES to get a -# higher quality PDF documentation. - -USE_PDFLATEX = YES - -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. -# command to the generated LaTeX files. This will instruct LaTeX to keep -# running if errors occur, instead of asking the user for help. -# This option is also used when generating formulas in HTML. - -LATEX_BATCHMODE = NO - -# If LATEX_HIDE_INDICES is set to YES then doxygen will not -# include the index chapters (such as File Index, Compound Index, etc.) -# in the output. - -LATEX_HIDE_INDICES = NO - -# If LATEX_SOURCE_CODE is set to YES then doxygen will include -# source code with syntax highlighting in the LaTeX output. -# Note that which sources are shown also depends on other settings -# such as SOURCE_BROWSER. - -LATEX_SOURCE_CODE = NO - -# The LATEX_BIB_STYLE tag can be used to specify the style to use for the -# bibliography, e.g. plainnat, or ieeetr. The default style is "plain". See -# http://en.wikipedia.org/wiki/BibTeX for more info. - -LATEX_BIB_STYLE = plain - -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- - -# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output -# The RTF output is optimized for Word 97 and may not look very pretty with -# other RTF readers or editors. - -GENERATE_RTF = NO - -# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `rtf' will be used as the default path. - -RTF_OUTPUT = rtf - -# If the COMPACT_RTF tag is set to YES Doxygen generates more compact -# RTF documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_RTF = NO - -# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated -# will contain hyperlink fields. The RTF file will -# contain links (just like the HTML output) instead of page references. -# This makes the output suitable for online browsing using WORD or other -# programs which support those fields. -# Note: wordpad (write) and others do not support links. - -RTF_HYPERLINKS = NO - -# Load style sheet definitions from file. Syntax is similar to doxygen's -# config file, i.e. a series of assignments. You only have to provide -# replacements, missing definitions are set to their default value. - -RTF_STYLESHEET_FILE = - -# Set optional variables used in the generation of an rtf document. -# Syntax is similar to doxygen's config file. - -RTF_EXTENSIONS_FILE = - -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- - -# If the GENERATE_MAN tag is set to YES (the default) Doxygen will -# generate man pages - -GENERATE_MAN = NO - -# The MAN_OUTPUT tag is used to specify where the man pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `man' will be used as the default path. - -MAN_OUTPUT = man - -# The MAN_EXTENSION tag determines the extension that is added to -# the generated man pages (default is the subroutine's section .3) - -MAN_EXTENSION = .3 - -# If the MAN_LINKS tag is set to YES and Doxygen generates man output, -# then it will generate one additional man file for each entity -# documented in the real man page(s). These additional files -# only source the real man page, but without them the man command -# would be unable to find the correct page. The default is NO. - -MAN_LINKS = NO - -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- - -# If the GENERATE_XML tag is set to YES Doxygen will -# generate an XML file that captures the structure of -# the code including all documentation. - -GENERATE_XML = NO - -# The XML_OUTPUT tag is used to specify where the XML pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `xml' will be used as the default path. - -XML_OUTPUT = xml - -# The XML_SCHEMA tag can be used to specify an XML schema, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_SCHEMA = - -# The XML_DTD tag can be used to specify an XML DTD, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_DTD = - -# If the XML_PROGRAMLISTING tag is set to YES Doxygen will -# dump the program listings (including syntax highlighting -# and cross-referencing information) to the XML output. Note that -# enabling this will significantly increase the size of the XML output. - -XML_PROGRAMLISTING = YES - -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- - -# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will -# generate an AutoGen Definitions (see autogen.sf.net) file -# that captures the structure of the code including all -# documentation. Note that this feature is still experimental -# and incomplete at the moment. - -GENERATE_AUTOGEN_DEF = NO - -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- - -# If the GENERATE_PERLMOD tag is set to YES Doxygen will -# generate a Perl module file that captures the structure of -# the code including all documentation. Note that this -# feature is still experimental and incomplete at the -# moment. - -GENERATE_PERLMOD = NO - -# If the PERLMOD_LATEX tag is set to YES Doxygen will generate -# the necessary Makefile rules, Perl scripts and LaTeX code to be able -# to generate PDF and DVI output from the Perl module output. - -PERLMOD_LATEX = NO - -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be -# nicely formatted so it can be parsed by a human reader. -# This is useful -# if you want to understand what is going on. -# On the other hand, if this -# tag is set to NO the size of the Perl module output will be much smaller -# and Perl will parse it just the same. - -PERLMOD_PRETTY = YES - -# The names of the make variables in the generated doxyrules.make file -# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. -# This is useful so different doxyrules.make files included by the same -# Makefile don't overwrite each other's variables. - -PERLMOD_MAKEVAR_PREFIX = - -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- - -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include -# files. - -ENABLE_PREPROCESSING = YES - -# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro -# names in the source code. If set to NO (the default) only conditional -# compilation will be performed. Macro expansion can be done in a controlled -# way by setting EXPAND_ONLY_PREDEF to YES. - -MACRO_EXPANSION = NO - -# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES -# then the macro expansion is limited to the macros specified with the -# PREDEFINED and EXPAND_AS_DEFINED tags. - -EXPAND_ONLY_PREDEF = NO - -# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files -# pointed to by INCLUDE_PATH will be searched when a #include is found. - -SEARCH_INCLUDES = YES - -# The INCLUDE_PATH tag can be used to specify one or more directories that -# contain include files that are not input files but should be processed by -# the preprocessor. - -INCLUDE_PATH = - -# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard -# patterns (like *.h and *.hpp) to filter out the header-files in the -# directories. If left blank, the patterns specified with FILE_PATTERNS will -# be used. - -INCLUDE_FILE_PATTERNS = - -# The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are -# omitted =1 is assumed. To prevent a macro definition from being -# undefined via #undef or recursively expanded use the := operator -# instead of the = operator. - -PREDEFINED = - -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. -# The macro definition that is found in the sources will be used. -# Use the PREDEFINED tag if you want to use a different macro definition that -# overrules the definition found in the source code. - -EXPAND_AS_DEFINED = - -# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then -# doxygen's preprocessor will remove all references to function-like macros -# that are alone on a line, have an all uppercase name, and do not end with a -# semicolon, because these will confuse the parser if not removed. - -SKIP_FUNCTION_MACROS = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- - -# The TAGFILES option can be used to specify one or more tagfiles. -# Optionally an initial location of the external documentation -# can be added for each tagfile. The format of a tag file without -# this location is as follows: -# -# TAGFILES = file1 file2 ... -# Adding location for the tag files is done as follows: -# -# TAGFILES = file1=loc1 "file2 = loc2" ... -# where "loc1" and "loc2" can be relative or absolute paths or -# URLs. If a location is present for each tag, the installdox tool -# does not have to be run to correct the links. -# Note that each tag file must have a unique name -# (where the name does NOT include the path) -# If a tag file is not located in the directory in which doxygen -# is run, you must also specify the path to the tagfile here. - -TAGFILES = - -# When a file name is specified after GENERATE_TAGFILE, doxygen will create -# a tag file that is based on the input files it reads. - -GENERATE_TAGFILE = - -# If the ALLEXTERNALS tag is set to YES all external classes will be listed -# in the class index. If set to NO only the inherited external classes -# will be listed. - -ALLEXTERNALS = NO - -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will -# be listed. - -EXTERNAL_GROUPS = YES - -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of `which perl'). - -PERL_PATH = /usr/bin/perl - -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- - -# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will -# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base -# or super classes. Setting the tag to NO turns the diagrams off. Note that -# this option also works with HAVE_DOT disabled, but it is recommended to -# install and use dot, since it yields more powerful graphs. - -CLASS_DIAGRAMS = YES - -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see -# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the -# documentation. The MSCGEN_PATH tag allows you to specify the directory where -# the mscgen tool resides. If left empty the tool is assumed to be found in the -# default search path. - -MSCGEN_PATH = - -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented -# or is not a class. - -HIDE_UNDOC_RELATIONS = YES - -# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is -# available from the path. This tool is part of Graphviz, a graph visualization -# toolkit from AT&T and Lucent Bell Labs. The other options in this section -# have no effect if this option is set to NO (the default) - -HAVE_DOT = NO - -# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is -# allowed to run in parallel. When set to 0 (the default) doxygen will -# base this on the number of processors available in the system. You can set it -# explicitly to a value larger than 0 to get control over the balance -# between CPU load and processing speed. - -DOT_NUM_THREADS = 0 - -# By default doxygen will use the Helvetica font for all dot files that -# doxygen generates. When you want a differently looking font you can specify -# the font name using DOT_FONTNAME. You need to make sure dot is able to find -# the font, which can be done by putting it in a standard location or by setting -# the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the -# directory containing the font. - -DOT_FONTNAME = Helvetica - -# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. -# The default size is 10pt. - -DOT_FONTSIZE = 10 - -# By default doxygen will tell dot to use the Helvetica font. -# If you specify a different font using DOT_FONTNAME you can use DOT_FONTPATH to -# set the path where dot can find it. - -DOT_FONTPATH = - -# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect inheritance relations. Setting this tag to YES will force the -# CLASS_DIAGRAMS tag to NO. - -CLASS_GRAPH = NO - -# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect implementation dependencies (inheritance, containment, and -# class references variables) of the class with other documented classes. - -COLLABORATION_GRAPH = NO - -# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for groups, showing the direct groups dependencies - -GROUP_GRAPHS = YES - -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and -# collaboration diagrams in a style similar to the OMG's Unified Modeling -# Language. - -UML_LOOK = NO - -# If set to YES, the inheritance and collaboration graphs will show the -# relations between templates and their instances. - -TEMPLATE_RELATIONS = NO - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT -# tags are set to YES then doxygen will generate a graph for each documented -# file showing the direct and indirect include dependencies of the file with -# other documented files. - -INCLUDE_GRAPH = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and -# HAVE_DOT tags are set to YES then doxygen will generate a graph for each -# documented header file showing the documented files that directly or -# indirectly include this file. - -INCLUDED_BY_GRAPH = YES - -# If the CALL_GRAPH and HAVE_DOT options are set to YES then -# doxygen will generate a call dependency graph for every global function -# or class method. Note that enabling this option will significantly increase -# the time of a run. So in most cases it will be better to enable call graphs -# for selected functions only using the \callgraph command. - -CALL_GRAPH = NO - -# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then -# doxygen will generate a caller dependency graph for every global function -# or class method. Note that enabling this option will significantly increase -# the time of a run. So in most cases it will be better to enable caller -# graphs for selected functions only using the \callergraph command. - -CALLER_GRAPH = NO - -# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen -# will generate a graphical hierarchy of all classes instead of a textual one. - -GRAPHICAL_HIERARCHY = YES - -# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES -# then doxygen will show the dependencies a directory has on other directories -# in a graphical way. The dependency relations are determined by the #include -# relations between the files in the directories. - -DIRECTORY_GRAPH = YES - -# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. Possible values are svg, png, jpg, or gif. -# If left blank png will be used. If you choose svg you need to set -# HTML_FILE_EXTENSION to xhtml in order to make the SVG files -# visible in IE 9+ (other browsers do not have this requirement). - -DOT_IMAGE_FORMAT = png - -# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to -# enable generation of interactive SVG images that allow zooming and panning. -# Note that this requires a modern browser other than Internet Explorer. -# Tested and working are Firefox, Chrome, Safari, and Opera. For IE 9+ you -# need to set HTML_FILE_EXTENSION to xhtml in order to make the SVG files -# visible. Older versions of IE do not have SVG support. - -INTERACTIVE_SVG = NO - -# The tag DOT_PATH can be used to specify the path where the dot tool can be -# found. If left blank, it is assumed the dot tool can be found in the path. - -DOT_PATH = - -# The DOTFILE_DIRS tag can be used to specify one or more directories that -# contain dot files that are included in the documentation (see the -# \dotfile command). - -DOTFILE_DIRS = - -# The MSCFILE_DIRS tag can be used to specify one or more directories that -# contain msc files that are included in the documentation (see the -# \mscfile command). - -MSCFILE_DIRS = - -# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of -# nodes that will be shown in the graph. If the number of nodes in a graph -# becomes larger than this value, doxygen will truncate the graph, which is -# visualized by representing a node as a red box. Note that doxygen if the -# number of direct children of the root node in a graph is already larger than -# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note -# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. - -DOT_GRAPH_MAX_NODES = 50 - -# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the -# graphs generated by dot. A depth value of 3 means that only nodes reachable -# from the root by following a path via at most 3 edges will be shown. Nodes -# that lay further from the root node will be omitted. Note that setting this -# option to 1 or 2 may greatly reduce the computation time needed for large -# code bases. Also note that the size of a graph can be further restricted by -# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. - -MAX_DOT_GRAPH_DEPTH = 0 - -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, because dot on Windows does not -# seem to support this out of the box. Warning: Depending on the platform used, -# enabling this option may lead to badly anti-aliased labels on the edges of -# a graph (i.e. they become hard to read). - -DOT_TRANSPARENT = NO - -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output -# files in one run (i.e. multiple -o and -T options on the command line). This -# makes dot run faster, but since only newer versions of dot (>1.8.10) -# support this, this feature is disabled by default. - -DOT_MULTI_TARGETS = NO - -# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will -# generate a legend page explaining the meaning of the various boxes and -# arrows in the dot generated graphs. - -GENERATE_LEGEND = YES - -# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will -# remove the intermediate dot files that are used to generate -# the various graphs. - -DOT_CLEANUP = YES diff --git a/third_party/optionparser-1.4/DoxygenLayout.xml b/third_party/optionparser-1.4/DoxygenLayout.xml deleted file mode 100644 index 474cc004..00000000 --- a/third_party/optionparser-1.4/DoxygenLayout.xml +++ /dev/null @@ -1,193 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/third_party/optionparser-1.4/README_ARGC_ARGV b/third_party/optionparser-1.4/README_ARGC_ARGV deleted file mode 100644 index c134cfa8..00000000 --- a/third_party/optionparser-1.4/README_ARGC_ARGV +++ /dev/null @@ -1,48 +0,0 @@ -POSIX Guidelines for command line arguments - -http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html - ----------------------------------------------- - -From the C standard: - -5.1.2.2.1 Program startup - -The function called at program startup is named main. The implementation declares no -prototype for this function. It shall be defined with a return type of int and with no -parameters: - - int main(void) { /* ... */ } - -or with two parameters (referred to here as argc and argv, though any names may be -used, as they are local to the function in which they are declared): - - int main(int argc, char *argv[]) { /* ... */ } - -or equivalent; or in some other implementation-defined manner. - -If they are declared, the parameters to the main function shall obey the following -constraints: - -— The value of argc shall be nonnegative. - -— argv[argc] shall be a null pointer. - -— If the value of argc is greater than zero, the array members argv[0] through - argv[argc-1] inclusive shall contain pointers to strings, which are given - implementation-defined values by the host environment prior to program startup. - The intent is to supply to the program information determined prior to program - startup from elsewhere in the hosted environment. If the host environment is - not capable of supplying strings with letters in both uppercase and lowercase, - the implementation shall ensure that the strings are received in lowercase. - -— If the value of argc is greater than zero, the string pointed to by argv[0] - represents the program name; argv[0][0] shall be the null character if the - program name is not available from the host environment. If the value of argc is - greater than one, the strings pointed to by argv[1] through argv[argc-1] - represent the program parameters. - -— The parameters argc and argv and the strings pointed to by the argv array shall - be modifiable by the program, and retain their last-stored values between program - startup and program termination. - diff --git a/third_party/optionparser-1.4/src/Makefile b/third_party/optionparser-1.4/src/Makefile deleted file mode 100644 index 2447e03b..00000000 --- a/third_party/optionparser-1.4/src/Makefile +++ /dev/null @@ -1,53 +0,0 @@ -CXX=g++ -CXXFLAGS=-W -Wall -g -fmessage-length=0 -CCFLAGS=$(CXXFLAGS) -fno-exceptions -fno-rtti -nodefaultlibs -OPTIMIZE=-Os -fomit-frame-pointer -#OPTIMIZE=-O0 -LD=gcc # gcc automatically picks the correct crt*.o and helper libraries to link -VERSION=1.4 -PACKAGEDIR=optionparser-$(VERSION) -TARBALL=../$(PACKAGEDIR).tar.gz - -all: example_arg testparse testprintusage testodr example doc - -# .cpp files depend on the C++ standard lib -%: %.cpp optionparser.h - $(CXX) $(CXXFLAGS) $(OPTIMIZE) -o $@ $< - -# .cc files depend only on libc -%.o: %.cc optionparser.h - $(CXX) $(CCFLAGS) $(OPTIMIZE) -c $< - -%: %.cc optionparser.h - $(CXX) $(CCFLAGS) $(OPTIMIZE) -lc -o $@ $< - -testprintusage: testprintusage.cpp optionparser.h - $(CXX) $(CXXFLAGS) $(OPTIMIZE) -Wno-unused-result -o $@ $< - -# testodr needs to be linked in a separate step rather than -# just passing both .cpp files to g++, because only this way -# can we be sure that duplicate definitions cause an error message. -testodr: testodr1.o testodr2.o - $(LD) -lc -o $@ $^ - -doc: - cd .. && doxygen - cd .. && cat Doxyfile | sed '/^INTERNAL_DOCS/s/YES/NO/;/^HTML_OUTPUT/s/-dev//' | doxygen - - -clean: - rm -f testodr testodr1.o testodr2.o example.o example testprintusage testparse example_arg - rm -rf ../html ../html-dev $(PACKAGEDIR) $(TARBALL) - rm -f *~ ../*~ - -package: - rm -rf $(PACKAGEDIR) - mkdir -p $(PACKAGEDIR)/src - cp ../Doxyfile ../DoxygenLayout.xml ../README_ARGC_ARGV $(PACKAGEDIR) - cp Makefile example.cpp example_arg.cc optionparser.h \ - testodr1.cc testodr2.cc testparse.cpp testprintusage.cpp \ - printUsage.h $(PACKAGEDIR)/src - tar --owner=0 --group=0 -czf $(TARBALL) $(PACKAGEDIR) - -upload: all package - cd .. && scp -r src/optionparser.h html/* optionparser-frs:/home/project-web/optionparser/htdocs - scp $(TARBALL) optionparser-frs:/home/frs/project/o/op/optionparser diff --git a/third_party/optionparser-1.4/src/example.cpp b/third_party/optionparser-1.4/src/example.cpp deleted file mode 100644 index d4dfd1df..00000000 --- a/third_party/optionparser-1.4/src/example.cpp +++ /dev/null @@ -1,56 +0,0 @@ -/* Written 2012 by Matthias S. Benkmann - * - * The author hereby waives all copyright and related rights to the contents - * of this example file (example.cpp) to the extent possible under the law. - */ - -/** - * @file - * @brief Small demo of The Lean Mean C++ Option Parser. - * - * @include example.cpp - */ - -#include -#include -#include -#include "optionparser.h" - -enum optionIndex { UNKNOWN, HELP, PLUS }; -const option::Descriptor usage[] = -{ - {UNKNOWN, 0, "", "",option::Arg::None, "USAGE: example [options]\n\n" - "Options:" }, - {HELP, 0,"", "help",option::Arg::None, " --help \tPrint usage and exit." }, - {PLUS, 0,"p","plus",option::Arg::None, " --plus, -p \tIncrement count." }, - {UNKNOWN, 0, "", "",option::Arg::None, "\nExamples:\n" - " example --unknown -- --this_is_no_option\n" - " example -unk --plus -ppp file1 file2\n" }, - {0,0,0,0,0,0} -}; - -int main(int argc, char* argv[]) -{ - argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present - option::Stats stats(usage, argc, argv); - std::vector options(stats.options_max); - std::vector buffer(stats.buffer_max); - option::Parser parse(usage, argc, argv, &options[0], &buffer[0]); - - if (parse.error()) - return 1; - - if (options[HELP] || argc == 0) { - option::printUsage(std::cout, usage); - return 0; - } - - std::cout << "--plus count: " << - options[PLUS].count() << "\n"; - - for (option::Option* opt = options[UNKNOWN]; opt; opt = opt->next()) - std::cout << "Unknown option: " << std::string(opt->name,opt->namelen) << "\n"; - - for (int i = 0; i < parse.nonOptionsCount(); ++i) - std::cout << "Non-option #" << i << ": " << parse.nonOption(i) << "\n"; -} diff --git a/third_party/optionparser-1.4/src/example_arg.cc b/third_party/optionparser-1.4/src/example_arg.cc deleted file mode 100644 index 82886f9a..00000000 --- a/third_party/optionparser-1.4/src/example_arg.cc +++ /dev/null @@ -1,160 +0,0 @@ -/* Written 2012 by Matthias S. Benkmann - * - * The author hereby waives all copyright and related rights to the contents - * of this example file (example_arg.cc) to the extent possible under the law. - */ - -/** - * @file - * @brief Demonstrates handling various types of option arguments (required, numeric,...) with - no dependency on the C++ standard library (only C lib). - * - * @include example_arg.cc - */ - -#include -#include -#include "optionparser.h" - -struct Arg: public option::Arg -{ - static void printError(const char* msg1, const option::Option& opt, const char* msg2) - { - fprintf(stderr, "%s", msg1); - fwrite(opt.name, opt.namelen, 1, stderr); - fprintf(stderr, "%s", msg2); - } - - static option::ArgStatus Unknown(const option::Option& option, bool msg) - { - if (msg) printError("Unknown option '", option, "'\n"); - return option::ARG_ILLEGAL; - } - - static option::ArgStatus Required(const option::Option& option, bool msg) - { - if (option.arg != 0) - return option::ARG_OK; - - if (msg) printError("Option '", option, "' requires an argument\n"); - return option::ARG_ILLEGAL; - } - - static option::ArgStatus NonEmpty(const option::Option& option, bool msg) - { - if (option.arg != 0 && option.arg[0] != 0) - return option::ARG_OK; - - if (msg) printError("Option '", option, "' requires a non-empty argument\n"); - return option::ARG_ILLEGAL; - } - - static option::ArgStatus Numeric(const option::Option& option, bool msg) - { - char* endptr = 0; - if (option.arg != 0 && strtol(option.arg, &endptr, 10)){}; - if (endptr != option.arg && *endptr == 0) - return option::ARG_OK; - - if (msg) printError("Option '", option, "' requires a numeric argument\n"); - return option::ARG_ILLEGAL; - } -}; - -enum optionIndex { UNKNOWN, HELP, OPTIONAL, REQUIRED, NUMERIC, NONEMPTY }; -const option::Descriptor usage[] = { -{ UNKNOWN, 0,"", "", Arg::Unknown, "USAGE: example_arg [options]\n\n" - "Options:" }, -{ HELP, 0,"", "help", Arg::None, " \t--help \tPrint usage and exit." }, -{ OPTIONAL,0,"o","optional",Arg::Optional," -o[], \t--optional[=]" - " \tTakes an argument but is happy without one." }, -{ REQUIRED,0,"r","required",Arg::Required," -r , \t--required= \tMust have an argument." }, -{ NUMERIC, 0,"n","numeric", Arg::Numeric, " -n , \t--numeric= \tRequires a number as argument." }, -{ NONEMPTY,0,"1","nonempty",Arg::NonEmpty," -1 , \t--nonempty=" - " \tCan NOT take the empty string as argument." }, -{ UNKNOWN, 0,"", "", Arg::None, - "\nExamples:\n" - " example_arg --unknown -o -n10 \n" - " example_arg -o -n10 file1 file2 \n" - " example_arg -nfoo file1 file2 \n" - " example_arg --optional -- file1 file2 \n" - " example_arg --optional file1 file2 \n" - " example_arg --optional=file1 file2 \n" - " example_arg --optional= file1 file2 \n" - " example_arg -o file1 file2 \n" - " example_arg -ofile1 file2 \n" - " example_arg -unk file1 file2 \n" - " example_arg -r -- file1 \n" - " example_arg -r file1 \n" - " example_arg --required \n" - " example_arg --required=file1 \n" - " example_arg --nonempty= file1 \n" - " example_arg --nonempty=foo --numeric=999 --optional=bla file1 \n" - " example_arg -1foo \n" - " example_arg -1 -- \n" - " example_arg -1 \"\" \n" -}, -{ 0, 0, 0, 0, 0, 0 } }; - -int main(int argc, char* argv[]) -{ - argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present - option::Stats stats(usage, argc, argv); - -#ifdef __GNUC__ - // GCC supports C99 VLAs for C++ with proper constructor calls. - option::Option options[stats.options_max], buffer[stats.buffer_max]; -#else - // use calloc() to allocate 0-initialized memory. It's not the same - // as properly constructed elements, but good enough. Obviously in an - // ordinary C++ program you'd use new[], but this file demonstrates that - // TLMC++OP can be used without any dependency on the C++ standard library. - option::Option* options = (option::Option*)calloc(stats.options_max, sizeof(option::Option)); - option::Option* buffer = (option::Option*)calloc(stats.buffer_max, sizeof(option::Option)); -#endif - - option::Parser parse(usage, argc, argv, options, buffer); - - if (parse.error()) - return 1; - - if (options[HELP] || argc == 0) - { - int columns = getenv("COLUMNS")? atoi(getenv("COLUMNS")) : 80; - option::printUsage(fwrite, stdout, usage, columns); - return 0; - } - - for (int i = 0; i < parse.optionsCount(); ++i) - { - option::Option& opt = buffer[i]; - fprintf(stdout, "Argument #%d is ", i); - switch (opt.index()) - { - case HELP: - // not possible, because handled further above and exits the program - case OPTIONAL: - if (opt.arg) - fprintf(stdout, "--optional with optional argument '%s'\n", opt.arg); - else - fprintf(stdout, "--optional without the optional argument\n"); - break; - case REQUIRED: - fprintf(stdout, "--required with argument '%s'\n", opt.arg); - break; - case NUMERIC: - fprintf(stdout, "--numeric with argument '%s'\n", opt.arg); - break; - case NONEMPTY: - fprintf(stdout, "--nonempty with argument '%s'\n", opt.arg); - break; - case UNKNOWN: - // not possible because Arg::Unknown returns ARG_ILLEGAL - // which aborts the parse with an error - break; - } - } - - for (int i = 0; i < parse.nonOptionsCount(); ++i) - fprintf(stdout, "Non-option argument #%d is %s\n", i, parse.nonOption(i)); -} diff --git a/third_party/optionparser-1.4/src/optionparser.h b/third_party/optionparser-1.4/src/optionparser.h deleted file mode 100644 index d43b7dfe..00000000 --- a/third_party/optionparser-1.4/src/optionparser.h +++ /dev/null @@ -1,2823 +0,0 @@ -/* - * The Lean Mean C++ Option Parser - * - * Copyright (C) 2012 Matthias S. Benkmann - * - * The "Software" in the following 2 paragraphs refers to this file containing - * the code to The Lean Mean C++ Option Parser. - * The "Software" does NOT refer to any other files which you - * may have received alongside this file (e.g. as part of a larger project that - * incorporates The Lean Mean C++ Option Parser). - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this 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. - */ - -/* - * NOTE: It is recommended that you read the processed HTML doxygen documentation - * rather than this source. If you don't know doxygen, it's like javadoc for C++. - * If you don't want to install doxygen you can find a copy of the processed - * documentation at - * - * http://optionparser.sourceforge.net/ - * - */ - -/** - * @file - * - * @brief This is the only file required to use The Lean Mean C++ Option Parser. - * Just \#include it and you're set. - * - * The Lean Mean C++ Option Parser handles the program's command line arguments - * (argc, argv). - * It supports the short and long option formats of getopt(), getopt_long() - * and getopt_long_only() but has a more convenient interface. - * The following features set it apart from other option parsers: - * - * @par Highlights: - *
    - *
  • It is a header-only library. Just \#include "optionparser.h" and you're set. - *
  • It is freestanding. There are no dependencies whatsoever, not even the - * C or C++ standard library. - *
  • It has a usage message formatter that supports column alignment and - * line wrapping. This aids localization because it adapts to - * translated strings that are shorter or longer (even if they contain - * Asian wide characters). - *
  • Unlike getopt() and derivatives it doesn't force you to loop through - * options sequentially. Instead you can access options directly like this: - *
      - *
    • Test for presence of a switch in the argument vector: - * @code if ( options[QUIET] ) ... @endcode - *
    • Evaluate --enable-foo/--disable-foo pair where the last one used wins: - * @code if ( options[FOO].last()->type() == DISABLE ) ... @endcode - *
    • Cumulative option (-v verbose, -vv more verbose, -vvv even more verbose): - * @code int verbosity = options[VERBOSE].count(); @endcode - *
    • Iterate over all --file=<fname> arguments: - * @code for (Option* opt = options[FILE]; opt; opt = opt->next()) - * fname = opt->arg; ... @endcode - *
    • If you really want to, you can still process all arguments in order: - * @code - * for (int i = 0; i < p.optionsCount(); ++i) { - * Option& opt = buffer[i]; - * switch(opt.index()) { - * case HELP: ... - * case VERBOSE: ... - * case FILE: fname = opt.arg; ... - * case UNKNOWN: ... - * @endcode - *
    - *
@n - * Despite these features the code size remains tiny. - * It is smaller than uClibc's GNU getopt() and just a - * couple 100 bytes larger than uClibc's SUSv3 getopt(). @n - * (This does not include the usage formatter, of course. But you don't have to use that.) - * - * @par Download: - * Tarball with examples and test programs: - * optionparser-1.4.tar.gz @n - * Just the header (this is all you really need): - * optionparser.h - * - * @par Changelog: - * Version 1.4: Fixed 2 printUsage() bugs that messed up output with small COLUMNS values @n - * Version 1.3: Compatible with Microsoft Visual C++. @n - * Version 1.2: Added @ref option::Option::namelen "Option::namelen" and removed the extraction - * of short option characters into a special buffer. @n - * Changed @ref option::Arg::Optional "Arg::Optional" to accept arguments if they are attached - * rather than separate. This is what GNU getopt() does and how POSIX recommends - * utilities should interpret their arguments.@n - * Version 1.1: Optional mode with argument reordering as done by GNU getopt(), so that - * options and non-options can be mixed. See - * @ref option::Parser::parse() "Parser::parse()". - * - * @par Feedback: - * Send questions, bug reports, feature requests etc. to: optionparser-feedback (a) lists.sourceforge.net - * @htmlonly @endhtmlonly - * - * - * @par Example program: - * (Note: @c option::* identifiers are links that take you to their documentation.) - * @code - * #error EXAMPLE SHORTENED FOR READABILITY. BETTER EXAMPLES ARE IN THE .TAR.GZ! - * #include - * #include "optionparser.h" - * - * enum optionIndex { UNKNOWN, HELP, PLUS }; - * const option::Descriptor usage[] = - * { - * {UNKNOWN, 0,"" , "" ,option::Arg::None, "USAGE: example [options]\n\n" - * "Options:" }, - * {HELP, 0,"" , "help",option::Arg::None, " --help \tPrint usage and exit." }, - * {PLUS, 0,"p", "plus",option::Arg::None, " --plus, -p \tIncrement count." }, - * {UNKNOWN, 0,"" , "" ,option::Arg::None, "\nExamples:\n" - * " example --unknown -- --this_is_no_option\n" - * " example -unk --plus -ppp file1 file2\n" }, - * {0,0,0,0,0,0} - * }; - * - * int main(int argc, char* argv[]) - * { - * argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present - * option::Stats stats(usage, argc, argv); - * option::Option options[stats.options_max], buffer[stats.buffer_max]; - * option::Parser parse(usage, argc, argv, options, buffer); - * - * if (parse.error()) - * return 1; - * - * if (options[HELP] || argc == 0) { - * option::printUsage(std::cout, usage); - * return 0; - * } - * - * std::cout << "--plus count: " << - * options[PLUS].count() << "\n"; - * - * for (option::Option* opt = options[UNKNOWN]; opt; opt = opt->next()) - * std::cout << "Unknown option: " << opt->name << "\n"; - * - * for (int i = 0; i < parse.nonOptionsCount(); ++i) - * std::cout << "Non-option #" << i << ": " << parse.nonOption(i) << "\n"; - * } - * @endcode - * - * @par Option syntax: - * @li The Lean Mean C++ Option Parser follows POSIX getopt() conventions and supports - * GNU-style getopt_long() long options as well as Perl-style single-minus - * long options (getopt_long_only()). - * @li short options have the format @c -X where @c X is any character that fits in a char. - * @li short options can be grouped, i.e. -X -Y is equivalent to @c -XY. - * @li a short option may take an argument either separate (-X foo) or - * attached (@c -Xfoo). You can make the parser accept the additional format @c -X=foo by - * registering @c X as a long option (in addition to being a short option) and - * enabling single-minus long options. - * @li an argument-taking short option may be grouped if it is the last in the group, e.g. - * @c -ABCXfoo or -ABCX foo (@c foo is the argument to the @c -X option). - * @li a lone minus character @c '-' is not treated as an option. It is customarily used where - * a file name is expected to refer to stdin or stdout. - * @li long options have the format @c --option-name. - * @li the option-name of a long option can be anything and include any characters. - * Even @c = characters will work, but don't do that. - * @li [optional] long options may be abbreviated as long as the abbreviation is unambiguous. - * You can set a minimum length for abbreviations. - * @li [optional] long options may begin with a single minus. The double minus form is always - * accepted, too. - * @li a long option may take an argument either separate ( --option arg ) or - * attached ( --option=arg ). In the attached form the equals sign is mandatory. - * @li an empty string can be passed as an attached long option argument: --option-name= . - * Note the distinction between an empty string as argument and no argument at all. - * @li an empty string is permitted as separate argument to both long and short options. - * @li Arguments to both short and long options may start with a @c '-' character. E.g. - * -X-X , -X -X or --long-X=-X . If @c -X - * and @c --long-X take an argument, that argument will be @c "-X" in all 3 cases. - * @li If using the built-in @ref option::Arg::Optional "Arg::Optional", optional arguments must - * be attached. - * @li the special option @c -- (i.e. without a name) terminates the list of - * options. Everything that follows is a non-option argument, even if it starts with - * a @c '-' character. The @c -- itself will not appear in the parse results. - * @li the first argument that doesn't start with @c '-' or @c '--' and does not belong to - * a preceding argument-taking option, will terminate the option list and is the - * first non-option argument. All following command line arguments are treated as - * non-option arguments, even if they start with @c '-' . @n - * NOTE: This behaviour is mandated by POSIX, but GNU getopt() only honours this if it is - * explicitly requested (e.g. by setting POSIXLY_CORRECT). @n - * You can enable the GNU behaviour by passing @c true as first argument to - * e.g. @ref option::Parser::parse() "Parser::parse()". - * @li Arguments that look like options (i.e. @c '-' followed by at least 1 character) but - * aren't, are NOT treated as non-option arguments. They are treated as unknown options and - * are collected into a list of unknown options for error reporting. @n - * This means that in order to pass a first non-option - * argument beginning with the minus character it is required to use the - * @c -- special option, e.g. - * @code - * program -x -- --strange-filename - * @endcode - * In this example, @c --strange-filename is a non-option argument. If the @c -- - * were omitted, it would be treated as an unknown option. @n - * See @ref option::Descriptor::longopt for information on how to collect unknown options. - * - */ - -#ifndef OPTIONPARSER_H_ -#define OPTIONPARSER_H_ - -/** @brief The namespace of The Lean Mean C++ Option Parser. */ -namespace option -{ - -#ifdef _MSC_VER -#include -#pragma intrinsic(_BitScanReverse) -struct MSC_Builtin_CLZ -{ - static int builtin_clz(unsigned x) - { - unsigned long index; - _BitScanReverse(&index, x); - return 32-index; // int is always 32bit on Windows, even for target x64 - } -}; -#define __builtin_clz(x) MSC_Builtin_CLZ::builtin_clz(x) -#endif - -class Option; - -/** - * @brief Possible results when checking if an argument is valid for a certain option. - * - * In the case that no argument is provided for an option that takes an - * optional argument, return codes @c ARG_OK and @c ARG_IGNORE are equivalent. - */ -enum ArgStatus -{ - //! The option does not take an argument. - ARG_NONE, - //! The argument is acceptable for the option. - ARG_OK, - //! The argument is not acceptable but that's non-fatal because the option's argument is optional. - ARG_IGNORE, - //! The argument is not acceptable and that's fatal. - ARG_ILLEGAL -}; - -/** - * @brief Signature of functions that check if an argument is valid for a certain type of option. - * - * Every Option has such a function assigned in its Descriptor. - * @code - * Descriptor usage[] = { {UNKNOWN, 0, "", "", Arg::None, ""}, ... }; - * @endcode - * - * A CheckArg function has the following signature: - * @code ArgStatus CheckArg(const Option& option, bool msg); @endcode - * - * It is used to check if a potential argument would be acceptable for the option. - * It will even be called if there is no argument. In that case @c option.arg will be @c NULL. - * - * If @c msg is @c true and the function determines that an argument is not acceptable and - * that this is a fatal error, it should output a message to the user before - * returning @ref ARG_ILLEGAL. If @c msg is @c false the function should remain silent (or you - * will get duplicate messages). - * - * See @ref ArgStatus for the meaning of the return values. - * - * While you can provide your own functions, - * often the following pre-defined checks (which never return @ref ARG_ILLEGAL) will suffice: - * - * @li @c Arg::None @copybrief Arg::None - * @li @c Arg::Optional @copybrief Arg::Optional - * - */ -typedef ArgStatus (*CheckArg)(const Option& option, bool msg); - -/** - * @brief Describes an option, its help text (usage) and how it should be parsed. - * - * The main input when constructing an option::Parser is an array of Descriptors. - - * @par Example: - * @code - * enum OptionIndex {CREATE, ...}; - * enum OptionType {DISABLE, ENABLE, OTHER}; - * - * const option::Descriptor usage[] = { - * { CREATE, // index - * OTHER, // type - * "c", // shortopt - * "create", // longopt - * Arg::None, // check_arg - * "--create Tells the program to create something." // help - * } - * , ... - * }; - * @endcode - */ -struct Descriptor -{ - /** - * @brief Index of this option's linked list in the array filled in by the parser. - * - * Command line options whose Descriptors have the same index will end up in the same - * linked list in the order in which they appear on the command line. If you have - * multiple long option aliases that refer to the same option, give their descriptors - * the same @c index. - * - * If you have options that mean exactly opposite things - * (e.g. @c --enable-foo and @c --disable-foo ), you should also give them the same - * @c index, but distinguish them through different values for @ref type. - * That way they end up in the same list and you can just take the last element of the - * list and use its type. This way you get the usual behaviour where switches later - * on the command line override earlier ones without having to code it manually. - * - * @par Tip: - * Use an enum rather than plain ints for better readability, as shown in the example - * at Descriptor. - */ - const unsigned index; - - /** - * @brief Used to distinguish between options with the same @ref index. - * See @ref index for details. - * - * It is recommended that you use an enum rather than a plain int to make your - * code more readable. - */ - const int type; - - /** - * @brief Each char in this string will be accepted as a short option character. - * - * The string must not include the minus character @c '-' or you'll get undefined - * behaviour. - * - * If this Descriptor should not have short option characters, use the empty - * string "". NULL is not permitted here! - * - * See @ref longopt for more information. - */ - const char* const shortopt; - - /** - * @brief The long option name (without the leading @c -- ). - * - * If this Descriptor should not have a long option name, use the empty - * string "". NULL is not permitted here! - * - * While @ref shortopt allows multiple short option characters, each - * Descriptor can have only a single long option name. If you have multiple - * long option names referring to the same option use separate Descriptors - * that have the same @ref index and @ref type. You may repeat - * short option characters in such an alias Descriptor but there's no need to. - * - * @par Dummy Descriptors: - * You can use dummy Descriptors with an - * empty string for both @ref shortopt and @ref longopt to add text to - * the usage that is not related to a specific option. See @ref help. - * The first dummy Descriptor will be used for unknown options (see below). - * - * @par Unknown Option Descriptor: - * The first dummy Descriptor in the list of Descriptors, - * whose @ref shortopt and @ref longopt are both the empty string, will be used - * as the Descriptor for unknown options. An unknown option is a string in - * the argument vector that is not a lone minus @c '-' but starts with a minus - * character and does not match any Descriptor's @ref shortopt or @ref longopt. @n - * Note that the dummy descriptor's @ref check_arg function @e will be called and - * its return value will be evaluated as usual. I.e. if it returns @ref ARG_ILLEGAL - * the parsing will be aborted with Parser::error()==true. @n - * if @c check_arg does not return @ref ARG_ILLEGAL the descriptor's - * @ref index @e will be used to pick the linked list into which - * to put the unknown option. @n - * If there is no dummy descriptor, unknown options will be dropped silently. - * - */ - const char* const longopt; - - /** - * @brief For each option that matches @ref shortopt or @ref longopt this function - * will be called to check a potential argument to the option. - * - * This function will be called even if there is no potential argument. In that case - * it will be passed @c NULL as @c arg parameter. Do not confuse this with the empty - * string. - * - * See @ref CheckArg for more information. - */ - const CheckArg check_arg; - - /** - * @brief The usage text associated with the options in this Descriptor. - * - * You can use option::printUsage() to format your usage message based on - * the @c help texts. You can use dummy Descriptors where - * @ref shortopt and @ref longopt are both the empty string to add text to - * the usage that is not related to a specific option. - * - * See option::printUsage() for special formatting characters you can use in - * @c help to get a column layout. - * - * @attention - * Must be UTF-8-encoded. If your compiler supports C++11 you can use the "u8" - * prefix to make sure string literals are properly encoded. - */ - const char* help; -}; - -/** - * @brief A parsed option from the command line together with its argument if it has one. - * - * The Parser chains all parsed options with the same Descriptor::index together - * to form a linked list. This allows you to easily implement all of the common ways - * of handling repeated options and enable/disable pairs. - * - * @li Test for presence of a switch in the argument vector: - * @code if ( options[QUIET] ) ... @endcode - * @li Evaluate --enable-foo/--disable-foo pair where the last one used wins: - * @code if ( options[FOO].last()->type() == DISABLE ) ... @endcode - * @li Cumulative option (-v verbose, -vv more verbose, -vvv even more verbose): - * @code int verbosity = options[VERBOSE].count(); @endcode - * @li Iterate over all --file=<fname> arguments: - * @code for (Option* opt = options[FILE]; opt; opt = opt->next()) - * fname = opt->arg; ... @endcode - */ -class Option -{ - Option* next_; - Option* prev_; -public: - /** - * @brief Pointer to this Option's Descriptor. - * - * Remember that the first dummy descriptor (see @ref Descriptor::longopt) is used - * for unknown options. - * - * @attention - * @c desc==NULL signals that this Option is unused. This is the default state of - * elements in the result array. You don't need to test @c desc explicitly. You - * can simply write something like this: - * @code - * if (options[CREATE]) - * { - * ... - * } - * @endcode - * This works because of operator const Option*() . - */ - const Descriptor* desc; - - /** - * @brief The name of the option as used on the command line. - * - * The main purpose of this string is to be presented to the user in messages. - * - * In the case of a long option, this is the actual @c argv pointer, i.e. the first - * character is a '-'. In the case of a short option this points to the option - * character within the @c argv string. - * - * Note that in the case of a short option group or an attached option argument, this - * string will contain additional characters following the actual name. Use @ref namelen - * to filter out the actual option name only. - * - */ - const char* name; - - /** - * @brief Pointer to this Option's argument (if any). - * - * NULL if this option has no argument. Do not confuse this with the empty string which - * is a valid argument. - */ - const char* arg; - - /** - * @brief The length of the option @ref name. - * - * Because @ref name points into the actual @c argv string, the option name may be - * followed by more characters (e.g. other short options in the same short option group). - * This value is the number of bytes (not characters!) that are part of the actual name. - * - * For a short option, this length is always 1. For a long option this length is always - * at least 2 if single minus long options are permitted and at least 3 if they are disabled. - * - * @note - * In the pathological case of a minus within a short option group (e.g. @c -xf-z), this - * length is incorrect, because this case will be misinterpreted as a long option and the - * name will therefore extend to the string's 0-terminator or a following '=" character - * if there is one. This is irrelevant for most uses of @ref name and @c namelen. If you - * really need to distinguish the case of a long and a short option, compare @ref name to - * the @c argv pointers. A long option's @c name is always identical to one of them, - * whereas a short option's is never. - */ - int namelen; - - /** - * @brief Returns Descriptor::type of this Option's Descriptor, or 0 if this Option - * is invalid (unused). - * - * Because this method (and last(), too) can be used even on unused Options with desc==0, you can (provided - * you arrange your types properly) switch on type() without testing validity first. - * @code - * enum OptionType { UNUSED=0, DISABLED=0, ENABLED=1 }; - * enum OptionIndex { FOO }; - * const Descriptor usage[] = { - * { FOO, ENABLED, "", "enable-foo", Arg::None, 0 }, - * { FOO, DISABLED, "", "disable-foo", Arg::None, 0 }, - * { 0, 0, 0, 0, 0, 0 } }; - * ... - * switch(options[FOO].last()->type()) // no validity check required! - * { - * case ENABLED: ... - * case DISABLED: ... // UNUSED==DISABLED ! - * } - * @endcode - */ - int type() const - { - return desc == 0 ? 0 : desc->type; - } - - /** - * @brief Returns Descriptor::index of this Option's Descriptor, or -1 if this Option - * is invalid (unused). - */ - int index() const - { - return desc == 0 ? -1 : (int)desc->index; - } - - /** - * @brief Returns the number of times this Option (or others with the same Descriptor::index) - * occurs in the argument vector. - * - * This corresponds to the number of elements in the linked list this Option is part of. - * It doesn't matter on which element you call count(). The return value is always the same. - * - * Use this to implement cumulative options, such as -v, -vv, -vvv for - * different verbosity levels. - * - * Returns 0 when called for an unused/invalid option. - */ - int count() - { - int c = (desc == 0 ? 0 : 1); - Option* p = first(); - while (!p->isLast()) - { - ++c; - p = p->next_; - }; - return c; - } - - /** - * @brief Returns true iff this is the first element of the linked list. - * - * The first element in the linked list is the first option on the command line - * that has the respective Descriptor::index value. - * - * Returns true for an unused/invalid option. - */ - bool isFirst() const - { - return isTagged(prev_); - } - - /** - * @brief Returns true iff this is the last element of the linked list. - * - * The last element in the linked list is the last option on the command line - * that has the respective Descriptor::index value. - * - * Returns true for an unused/invalid option. - */ - bool isLast() const - { - return isTagged(next_); - } - - /** - * @brief Returns a pointer to the first element of the linked list. - * - * Use this when you want the first occurrence of an option on the command line to - * take precedence. Note that this is not the way most programs handle options. - * You should probably be using last() instead. - * - * @note - * This method may be called on an unused/invalid option and will return a pointer to the - * option itself. - */ - Option* first() - { - Option* p = this; - while (!p->isFirst()) - p = p->prev_; - return p; - } - - /** - * @brief Returns a pointer to the last element of the linked list. - * - * Use this when you want the last occurrence of an option on the command line to - * take precedence. This is the most common way of handling conflicting options. - * - * @note - * This method may be called on an unused/invalid option and will return a pointer to the - * option itself. - * - * @par Tip: - * If you have options with opposite meanings (e.g. @c --enable-foo and @c --disable-foo), you - * can assign them the same Descriptor::index to get them into the same list. Distinguish them by - * Descriptor::type and all you have to do is check last()->type() to get - * the state listed last on the command line. - */ - Option* last() - { - return first()->prevwrap(); - } - - /** - * @brief Returns a pointer to the previous element of the linked list or NULL if - * called on first(). - * - * If called on first() this method returns NULL. Otherwise it will return the - * option with the same Descriptor::index that precedes this option on the command - * line. - */ - Option* prev() - { - return isFirst() ? 0 : prev_; - } - - /** - * @brief Returns a pointer to the previous element of the linked list with wrap-around from - * first() to last(). - * - * If called on first() this method returns last(). Otherwise it will return the - * option with the same Descriptor::index that precedes this option on the command - * line. - */ - Option* prevwrap() - { - return untag(prev_); - } - - /** - * @brief Returns a pointer to the next element of the linked list or NULL if called - * on last(). - * - * If called on last() this method returns NULL. Otherwise it will return the - * option with the same Descriptor::index that follows this option on the command - * line. - */ - Option* next() - { - return isLast() ? 0 : next_; - } - - /** - * @brief Returns a pointer to the next element of the linked list with wrap-around from - * last() to first(). - * - * If called on last() this method returns first(). Otherwise it will return the - * option with the same Descriptor::index that follows this option on the command - * line. - */ - Option* nextwrap() - { - return untag(next_); - } - - /** - * @brief Makes @c new_last the new last() by chaining it into the list after last(). - * - * It doesn't matter which element you call append() on. The new element will always - * be appended to last(). - * - * @attention - * @c new_last must not yet be part of a list, or that list will become corrupted, because - * this method does not unchain @c new_last from an existing list. - */ - void append(Option* new_last) - { - Option* p = last(); - Option* f = first(); - p->next_ = new_last; - new_last->prev_ = p; - new_last->next_ = tag(f); - f->prev_ = tag(new_last); - } - - /** - * @brief Casts from Option to const Option* but only if this Option is valid. - * - * If this Option is valid (i.e. @c desc!=NULL), returns this. - * Otherwise returns NULL. This allows testing an Option directly - * in an if-clause to see if it is used: - * @code - * if (options[CREATE]) - * { - * ... - * } - * @endcode - * It also allows you to write loops like this: - * @code for (Option* opt = options[FILE]; opt; opt = opt->next()) - * fname = opt->arg; ... @endcode - */ - operator const Option*() const - { - return desc ? this : 0; - } - - /** - * @brief Casts from Option to Option* but only if this Option is valid. - * - * If this Option is valid (i.e. @c desc!=NULL), returns this. - * Otherwise returns NULL. This allows testing an Option directly - * in an if-clause to see if it is used: - * @code - * if (options[CREATE]) - * { - * ... - * } - * @endcode - * It also allows you to write loops like this: - * @code for (Option* opt = options[FILE]; opt; opt = opt->next()) - * fname = opt->arg; ... @endcode - */ - operator Option*() - { - return desc ? this : 0; - } - - /** - * @brief Creates a new Option that is a one-element linked list and has NULL - * @ref desc, @ref name, @ref arg and @ref namelen. - */ - Option() : - desc(0), name(0), arg(0), namelen(0) - { - prev_ = tag(this); - next_ = tag(this); - } - - /** - * @brief Creates a new Option that is a one-element linked list and has the given - * values for @ref desc, @ref name and @ref arg. - * - * If @c name_ points at a character other than '-' it will be assumed to refer to a - * short option and @ref namelen will be set to 1. Otherwise the length will extend to - * the first '=' character or the string's 0-terminator. - */ - Option(const Descriptor* desc_, const char* name_, const char* arg_) - { - init(desc_, name_, arg_); - } - - /** - * @brief Makes @c *this a copy of @c orig except for the linked list pointers. - * - * After this operation @c *this will be a one-element linked list. - */ - void operator=(const Option& orig) - { - init(orig.desc, orig.name, orig.arg); - } - - /** - * @brief Makes @c *this a copy of @c orig except for the linked list pointers. - * - * After this operation @c *this will be a one-element linked list. - */ - Option(const Option& orig) - { - init(orig.desc, orig.name, orig.arg); - } - -private: - /** - * @internal - * @brief Sets the fields of this Option to the given values (extracting @c name if necessary). - * - * If @c name_ points at a character other than '-' it will be assumed to refer to a - * short option and @ref namelen will be set to 1. Otherwise the length will extend to - * the first '=' character or the string's 0-terminator. - */ - void init(const Descriptor* desc_, const char* name_, const char* arg_) - { - desc = desc_; - name = name_; - arg = arg_; - prev_ = tag(this); - next_ = tag(this); - namelen = 0; - if (name == 0) - return; - namelen = 1; - if (name[0] != '-') - return; - while (name[namelen] != 0 && name[namelen] != '=') - ++namelen; - } - - static Option* tag(Option* ptr) - { - return (Option*) ((unsigned long long) ptr | 1); - } - - static Option* untag(Option* ptr) - { - return (Option*) ((unsigned long long) ptr & ~1ull); - } - - static bool isTagged(Option* ptr) - { - return ((unsigned long long) ptr & 1); - } -}; - -/** - * @brief Functions for checking the validity of option arguments. - * - * @copydetails CheckArg - * - * The following example code - * can serve as starting place for writing your own more complex CheckArg functions: - * @code - * struct Arg: public option::Arg - * { - * static void printError(const char* msg1, const option::Option& opt, const char* msg2) - * { - * fprintf(stderr, "ERROR: %s", msg1); - * fwrite(opt.name, opt.namelen, 1, stderr); - * fprintf(stderr, "%s", msg2); - * } - * - * static option::ArgStatus Unknown(const option::Option& option, bool msg) - * { - * if (msg) printError("Unknown option '", option, "'\n"); - * return option::ARG_ILLEGAL; - * } - * - * static option::ArgStatus Required(const option::Option& option, bool msg) - * { - * if (option.arg != 0) - * return option::ARG_OK; - * - * if (msg) printError("Option '", option, "' requires an argument\n"); - * return option::ARG_ILLEGAL; - * } - * - * static option::ArgStatus NonEmpty(const option::Option& option, bool msg) - * { - * if (option.arg != 0 && option.arg[0] != 0) - * return option::ARG_OK; - * - * if (msg) printError("Option '", option, "' requires a non-empty argument\n"); - * return option::ARG_ILLEGAL; - * } - * - * static option::ArgStatus Numeric(const option::Option& option, bool msg) - * { - * char* endptr = 0; - * if (option.arg != 0 && strtol(option.arg, &endptr, 10)){}; - * if (endptr != option.arg && *endptr == 0) - * return option::ARG_OK; - * - * if (msg) printError("Option '", option, "' requires a numeric argument\n"); - * return option::ARG_ILLEGAL; - * } - * }; - * @endcode - */ -struct Arg -{ - //! @brief For options that don't take an argument: Returns ARG_NONE. - static ArgStatus None(const Option&, bool) - { - return ARG_NONE; - } - - //! @brief Returns ARG_OK if the argument is attached and ARG_IGNORE otherwise. - static ArgStatus Optional(const Option& option, bool) - { - if (option.arg && option.name[option.namelen] != 0) - return ARG_OK; - else - return ARG_IGNORE; - } -}; - -/** - * @brief Determines the minimum lengths of the buffer and options arrays used for Parser. - * - * Because Parser doesn't use dynamic memory its output arrays have to be pre-allocated. - * If you don't want to use fixed size arrays (which may turn out too small, causing - * command line arguments to be dropped), you can use Stats to determine the correct sizes. - * Stats work cumulative. You can first pass in your default options and then the real - * options and afterwards the counts will reflect the union. - */ -struct Stats -{ - /** - * @brief Number of elements needed for a @c buffer[] array to be used for - * @ref Parser::parse() "parsing" the same argument vectors that were fed - * into this Stats object. - * - * @note - * This number is always 1 greater than the actual number needed, to give - * you a sentinel element. - */ - unsigned buffer_max; - - /** - * @brief Number of elements needed for an @c options[] array to be used for - * @ref Parser::parse() "parsing" the same argument vectors that were fed - * into this Stats object. - * - * @note - * @li This number is always 1 greater than the actual number needed, to give - * you a sentinel element. - * @li This number depends only on the @c usage, not the argument vectors, because - * the @c options array needs exactly one slot for each possible Descriptor::index. - */ - unsigned options_max; - - /** - * @brief Creates a Stats object with counts set to 1 (for the sentinel element). - */ - Stats() : - buffer_max(1), options_max(1) // 1 more than necessary as sentinel - { - } - - /** - * @brief Creates a new Stats object and immediately updates it for the - * given @c usage and argument vector. You may pass 0 for @c argc and/or @c argv, - * if you just want to update @ref options_max. - * - * @note - * The calls to Stats methods must match the later calls to Parser methods. - * See Parser::parse() for the meaning of the arguments. - */ - Stats(bool gnu, const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, // - bool single_minus_longopt = false) : - buffer_max(1), options_max(1) // 1 more than necessary as sentinel - { - add(gnu, usage, argc, argv, min_abbr_len, single_minus_longopt); - } - - //! @brief Stats(...) with non-const argv. - Stats(bool gnu, const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, // - bool single_minus_longopt = false) : - buffer_max(1), options_max(1) // 1 more than necessary as sentinel - { - add(gnu, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt); - } - - //! @brief POSIX Stats(...) (gnu==false). - Stats(const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, // - bool single_minus_longopt = false) : - buffer_max(1), options_max(1) // 1 more than necessary as sentinel - { - add(false, usage, argc, argv, min_abbr_len, single_minus_longopt); - } - - //! @brief POSIX Stats(...) (gnu==false) with non-const argv. - Stats(const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, // - bool single_minus_longopt = false) : - buffer_max(1), options_max(1) // 1 more than necessary as sentinel - { - add(false, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt); - } - - /** - * @brief Updates this Stats object for the - * given @c usage and argument vector. You may pass 0 for @c argc and/or @c argv, - * if you just want to update @ref options_max. - * - * @note - * The calls to Stats methods must match the later calls to Parser methods. - * See Parser::parse() for the meaning of the arguments. - */ - void add(bool gnu, const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, // - bool single_minus_longopt = false); - - //! @brief add() with non-const argv. - void add(bool gnu, const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, // - bool single_minus_longopt = false) - { - add(gnu, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt); - } - - //! @brief POSIX add() (gnu==false). - void add(const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, // - bool single_minus_longopt = false) - { - add(false, usage, argc, argv, min_abbr_len, single_minus_longopt); - } - - //! @brief POSIX add() (gnu==false) with non-const argv. - void add(const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, // - bool single_minus_longopt = false) - { - add(false, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt); - } -private: - class CountOptionsAction; -}; - -/** - * @brief Checks argument vectors for validity and parses them into data - * structures that are easier to work with. - * - * @par Example: - * @code - * int main(int argc, char* argv[]) - * { - * argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present - * option::Stats stats(usage, argc, argv); - * option::Option options[stats.options_max], buffer[stats.buffer_max]; - * option::Parser parse(usage, argc, argv, options, buffer); - * - * if (parse.error()) - * return 1; - * - * if (options[HELP]) - * ... - * @endcode - */ -class Parser -{ - int op_count; //!< @internal @brief see optionsCount() - int nonop_count; //!< @internal @brief see nonOptionsCount() - const char** nonop_args; //!< @internal @brief see nonOptions() - bool err; //!< @internal @brief see error() -public: - - /** - * @brief Creates a new Parser. - */ - Parser() : - op_count(0), nonop_count(0), nonop_args(0), err(false) - { - } - - /** - * @brief Creates a new Parser and immediately parses the given argument vector. - * @copydetails parse() - */ - Parser(bool gnu, const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[], - int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1) : - op_count(0), nonop_count(0), nonop_args(0), err(false) - { - parse(gnu, usage, argc, argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); - } - - //! @brief Parser(...) with non-const argv. - Parser(bool gnu, const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[], - int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1) : - op_count(0), nonop_count(0), nonop_args(0), err(false) - { - parse(gnu, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); - } - - //! @brief POSIX Parser(...) (gnu==false). - Parser(const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[], int min_abbr_len = 0, - bool single_minus_longopt = false, int bufmax = -1) : - op_count(0), nonop_count(0), nonop_args(0), err(false) - { - parse(false, usage, argc, argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); - } - - //! @brief POSIX Parser(...) (gnu==false) with non-const argv. - Parser(const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[], int min_abbr_len = 0, - bool single_minus_longopt = false, int bufmax = -1) : - op_count(0), nonop_count(0), nonop_args(0), err(false) - { - parse(false, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); - } - - /** - * @brief Parses the given argument vector. - * - * @param gnu if true, parse() will not stop at the first non-option argument. Instead it will - * reorder arguments so that all non-options are at the end. This is the default behaviour - * of GNU getopt() but is not conforming to POSIX. @n - * Note, that once the argument vector has been reordered, the @c gnu flag will have - * no further effect on this argument vector. So it is enough to pass @c gnu==true when - * creating Stats. - * @param usage Array of Descriptor objects that describe the options to support. The last entry - * of this array must have 0 in all fields. - * @param argc The number of elements from @c argv that are to be parsed. If you pass -1, the number - * will be determined automatically. In that case the @c argv list must end with a NULL - * pointer. - * @param argv The arguments to be parsed. If you pass -1 as @c argc the last pointer in the @c argv - * list must be NULL to mark the end. - * @param options Each entry is the first element of a linked list of Options. Each new option - * that is parsed will be appended to the list specified by that Option's - * Descriptor::index. If an entry is not yet used (i.e. the Option is invalid), - * it will be replaced rather than appended to. @n - * The minimum length of this array is the greatest Descriptor::index value that - * occurs in @c usage @e PLUS ONE. - * @param buffer Each argument that is successfully parsed (including unknown arguments, if they - * have a Descriptor whose CheckArg does not return @ref ARG_ILLEGAL) will be stored in this - * array. parse() scans the array for the first invalid entry and begins writing at that - * index. You can pass @c bufmax to limit the number of options stored. - * @param min_abbr_len Passing a value min_abbr_len > 0 enables abbreviated long - * options. The parser will match a prefix of a long option as if it was - * the full long option (e.g. @c --foob=10 will be interpreted as if it was - * @c --foobar=10 ), as long as the prefix has at least @c min_abbr_len characters - * (not counting the @c -- ) and is unambiguous. - * @n Be careful if combining @c min_abbr_len=1 with @c single_minus_longopt=true - * because the ambiguity check does not consider short options and abbreviated - * single minus long options will take precedence over short options. - * @param single_minus_longopt Passing @c true for this option allows long options to begin with - * a single minus. The double minus form will still be recognized. Note that - * single minus long options take precedence over short options and short option - * groups. E.g. @c -file would be interpreted as @c --file and not as - * -f -i -l -e (assuming a long option named @c "file" exists). - * @param bufmax The greatest index in the @c buffer[] array that parse() will write to is - * @c bufmax-1. If there are more options, they will be processed (in particular - * their CheckArg will be called) but not stored. @n - * If you used Stats::buffer_max to dimension this array, you can pass - * -1 (or not pass @c bufmax at all) which tells parse() that the buffer is - * "large enough". - * @attention - * Remember that @c options and @c buffer store Option @e objects, not pointers. Therefore it - * is not possible for the same object to be in both arrays. For those options that are found in - * both @c buffer[] and @c options[] the respective objects are independent copies. And only the - * objects in @c options[] are properly linked via Option::next() and Option::prev(). - * You can iterate over @c buffer[] to - * process all options in the order they appear in the argument vector, but if you want access to - * the other Options with the same Descriptor::index, then you @e must access the linked list via - * @c options[]. You can get the linked list in options from a buffer object via something like - * @c options[buffer[i].index()]. - */ - void parse(bool gnu, const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[], - int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1); - - //! @brief parse() with non-const argv. - void parse(bool gnu, const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[], - int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1) - { - parse(gnu, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); - } - - //! @brief POSIX parse() (gnu==false). - void parse(const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[], - int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1) - { - parse(false, usage, argc, argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); - } - - //! @brief POSIX parse() (gnu==false) with non-const argv. - void parse(const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[], int min_abbr_len = 0, - bool single_minus_longopt = false, int bufmax = -1) - { - parse(false, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); - } - - /** - * @brief Returns the number of valid Option objects in @c buffer[]. - * - * @note - * @li The returned value always reflects the number of Options in the buffer[] array used for - * the most recent call to parse(). - * @li The count (and the buffer[]) includes unknown options if they are collected - * (see Descriptor::longopt). - */ - int optionsCount() - { - return op_count; - } - - /** - * @brief Returns the number of non-option arguments that remained at the end of the - * most recent parse() that actually encountered non-option arguments. - * - * @note - * A parse() that does not encounter non-option arguments will leave this value - * as well as nonOptions() undisturbed. This means you can feed the Parser a - * default argument vector that contains non-option arguments (e.g. a default filename). - * Then you feed it the actual arguments from the user. If the user has supplied at - * least one non-option argument, all of the non-option arguments from the default - * disappear and are replaced by the user's non-option arguments. However, if the - * user does not supply any non-option arguments the defaults will still be in - * effect. - */ - int nonOptionsCount() - { - return nonop_count; - } - - /** - * @brief Returns a pointer to an array of non-option arguments (only valid - * if nonOptionsCount() >0 ). - * - * @note - * @li parse() does not copy arguments, so this pointer points into the actual argument - * vector as passed to parse(). - * @li As explained at nonOptionsCount() this pointer is only changed by parse() calls - * that actually encounter non-option arguments. A parse() call that encounters only - * options, will not change nonOptions(). - */ - const char** nonOptions() - { - return nonop_args; - } - - /** - * @brief Returns nonOptions()[i] (@e without checking if i is in range!). - */ - const char* nonOption(int i) - { - return nonOptions()[i]; - } - - /** - * @brief Returns @c true if an unrecoverable error occurred while parsing options. - * - * An illegal argument to an option (i.e. CheckArg returns @ref ARG_ILLEGAL) is an - * unrecoverable error that aborts the parse. Unknown options are only an error if - * their CheckArg function returns @ref ARG_ILLEGAL. Otherwise they are collected. - * In that case if you want to exit the program if either an illegal argument - * or an unknown option has been passed, use code like this - * - * @code - * if (parser.error() || options[UNKNOWN]) - * exit(1); - * @endcode - * - */ - bool error() - { - return err; - } - -private: - friend struct Stats; - class StoreOptionAction; - struct Action; - - /** - * @internal - * @brief This is the core function that does all the parsing. - * @retval false iff an unrecoverable error occurred. - */ - static bool workhorse(bool gnu, const Descriptor usage[], int numargs, const char** args, Action& action, - bool single_minus_longopt, bool print_errors, int min_abbr_len); - - /** - * @internal - * @brief Returns true iff @c st1 is a prefix of @c st2 and - * in case @c st2 is longer than @c st1, then - * the first additional character is '='. - * - * @par Examples: - * @code - * streq("foo", "foo=bar") == true - * streq("foo", "foobar") == false - * streq("foo", "foo") == true - * streq("foo=bar", "foo") == false - * @endcode - */ - static bool streq(const char* st1, const char* st2) - { - while (*st1 != 0) - if (*st1++ != *st2++) - return false; - return (*st2 == 0 || *st2 == '='); - } - - /** - * @internal - * @brief Like streq() but handles abbreviations. - * - * Returns true iff @c st1 and @c st2 have a common - * prefix with the following properties: - * @li (if min > 0) its length is at least @c min characters or the same length as @c st1 (whichever is smaller). - * @li (if min <= 0) its length is the same as that of @c st1 - * @li within @c st2 the character following the common prefix is either '=' or end-of-string. - * - * Examples: - * @code - * streqabbr("foo", "foo=bar",) == true - * streqabbr("foo", "fo=bar" , 2) == true - * streqabbr("foo", "fo" , 2) == true - * streqabbr("foo", "fo" , 0) == false - * streqabbr("foo", "f=bar" , 2) == false - * streqabbr("foo", "f" , 2) == false - * streqabbr("fo" , "foo=bar",) == false - * streqabbr("foo", "foobar" ,) == false - * streqabbr("foo", "fobar" ,) == false - * streqabbr("foo", "foo" ,) == true - * @endcode - */ - static bool streqabbr(const char* st1, const char* st2, long long min) - { - const char* st1start = st1; - while (*st1 != 0 && (*st1 == *st2)) - { - ++st1; - ++st2; - } - - return (*st1 == 0 || (min > 0 && (st1 - st1start) >= min)) && (*st2 == 0 || *st2 == '='); - } - - /** - * @internal - * @brief Returns true iff character @c ch is contained in the string @c st. - * - * Returns @c true for @c ch==0 . - */ - static bool instr(char ch, const char* st) - { - while (*st != 0 && *st != ch) - ++st; - return *st == ch; - } - - /** - * @internal - * @brief Rotates args[-count],...,args[-1],args[0] to become - * args[0],args[-count],...,args[-1]. - */ - static void shift(const char** args, int count) - { - for (int i = 0; i > -count; --i) - { - const char* temp = args[i]; - args[i] = args[i - 1]; - args[i - 1] = temp; - } - } -}; - -/** - * @internal - * @brief Interface for actions Parser::workhorse() should perform for each Option it - * parses. - */ -struct Parser::Action -{ - - /// @note 2017-01-26 GRVS Added virtual destructor. - virtual ~Action() = default; - - /** - * @brief Called by Parser::workhorse() for each Option that has been successfully - * parsed (including unknown - * options if they have a Descriptor whose Descriptor::check_arg does not return - * @ref ARG_ILLEGAL. - * - * Returns @c false iff a fatal error has occured and the parse should be aborted. - */ - virtual bool perform(Option&) - { - return true; - } - - /** - * @brief Called by Parser::workhorse() after finishing the parse. - * @param numargs the number of non-option arguments remaining - * @param args pointer to the first remaining non-option argument (if numargs > 0). - * - * @return - * @c false iff a fatal error has occurred. - */ - virtual bool finished(int numargs, const char** args) - { - (void) numargs; - (void) args; - return true; - } -}; - -/** - * @internal - * @brief An Action to pass to Parser::workhorse() that will increment a counter for - * each parsed Option. - */ -class Stats::CountOptionsAction: public Parser::Action -{ - unsigned* buffer_max; -public: - /** - * Creates a new CountOptionsAction that will increase @c *buffer_max_ for each - * parsed Option. - */ - CountOptionsAction(unsigned* buffer_max_) : - buffer_max(buffer_max_) - { - } - - bool perform(Option&) - { - if (*buffer_max == 0x7fffffff) - return false; // overflow protection: don't accept number of options that doesn't fit signed int - ++*buffer_max; - return true; - } -}; - -/** - * @internal - * @brief An Action to pass to Parser::workhorse() that will store each parsed Option in - * appropriate arrays (see Parser::parse()). - */ -class Parser::StoreOptionAction: public Parser::Action -{ - Parser& parser; - Option* options; - Option* buffer; - int bufmax; //! Number of slots in @c buffer. @c -1 means "large enough". -public: - /** - * @brief Creates a new StoreOption action. - * @param parser_ the parser whose op_count should be updated. - * @param options_ each Option @c o is chained into the linked list @c options_[o.desc->index] - * @param buffer_ each Option is appended to this array as long as there's a free slot. - * @param bufmax_ number of slots in @c buffer_. @c -1 means "large enough". - */ - StoreOptionAction(Parser& parser_, Option options_[], Option buffer_[], int bufmax_) : - parser(parser_), options(options_), buffer(buffer_), bufmax(bufmax_) - { - // find first empty slot in buffer (if any) - int bufidx = 0; - while ((bufmax < 0 || bufidx < bufmax) && buffer[bufidx]) - ++bufidx; - - // set parser's optionCount - parser.op_count = bufidx; - } - - bool perform(Option& option) - { - if (bufmax < 0 || parser.op_count < bufmax) - { - if (parser.op_count == 0x7fffffff) - return false; // overflow protection: don't accept number of options that doesn't fit signed int - - buffer[parser.op_count] = option; - int idx = buffer[parser.op_count].desc->index; - if (options[idx]) - options[idx].append(buffer[parser.op_count]); - else - options[idx] = buffer[parser.op_count]; - ++parser.op_count; - } - return true; // NOTE: an option that is discarded because of a full buffer is not fatal - } - - bool finished(int numargs, const char** args) - { - // only overwrite non-option argument list if there's at least 1 - // new non-option argument. Otherwise we keep the old list. This - // makes it easy to use default non-option arguments. - if (numargs > 0) - { - parser.nonop_count = numargs; - parser.nonop_args = args; - } - - return true; - } -}; - -inline void Parser::parse(bool gnu, const Descriptor usage[], int argc, const char** argv, Option options[], - Option buffer[], int min_abbr_len, bool single_minus_longopt, int bufmax) -{ - StoreOptionAction action(*this, options, buffer, bufmax); - err = !workhorse(gnu, usage, argc, argv, action, single_minus_longopt, true, min_abbr_len); -} - -inline void Stats::add(bool gnu, const Descriptor usage[], int argc, const char** argv, int min_abbr_len, - bool single_minus_longopt) -{ - // determine size of options array. This is the greatest index used in the usage + 1 - int i = 0; - while (usage[i].shortopt != 0) - { - if (usage[i].index + 1 >= options_max) - options_max = (usage[i].index + 1) + 1; // 1 more than necessary as sentinel - - ++i; - } - - CountOptionsAction action(&buffer_max); - Parser::workhorse(gnu, usage, argc, argv, action, single_minus_longopt, false, min_abbr_len); -} - -inline bool Parser::workhorse(bool gnu, const Descriptor usage[], int numargs, const char** args, Action& action, - bool single_minus_longopt, bool print_errors, int min_abbr_len) -{ - // protect against NULL pointer - if (args == 0) - numargs = 0; - - int nonops = 0; - - while (numargs != 0 && *args != 0) - { - const char* param = *args; // param can be --long-option, -srto or non-option argument - - // in POSIX mode the first non-option argument terminates the option list - // a lone minus character is a non-option argument - if (param[0] != '-' || param[1] == 0) - { - if (gnu) - { - ++nonops; - ++args; - if (numargs > 0) - --numargs; - continue; - } - else - break; - } - - // -- terminates the option list. The -- itself is skipped. - if (param[1] == '-' && param[2] == 0) - { - shift(args, nonops); - ++args; - if (numargs > 0) - --numargs; - break; - } - - bool handle_short_options; - const char* longopt_name; - if (param[1] == '-') // if --long-option - { - handle_short_options = false; - longopt_name = param + 2; - } - else - { - handle_short_options = true; - longopt_name = param + 1; //for testing a potential -long-option - } - - bool try_single_minus_longopt = single_minus_longopt; - bool have_more_args = (numargs > 1 || numargs < 0); // is referencing argv[1] valid? - - do // loop over short options in group, for long options the body is executed only once - { - int idx = 0; - - const char* optarg = nullptr; /// @note 2017-01-26 GRVS Initialize to nullptr, wasn't initialized before. - - /******************** long option **********************/ - if (handle_short_options == false || try_single_minus_longopt) - { - idx = 0; - while (usage[idx].longopt != 0 && !streq(usage[idx].longopt, longopt_name)) - ++idx; - - if (usage[idx].longopt == 0 && min_abbr_len > 0) // if we should try to match abbreviated long options - { - int i1 = 0; - while (usage[i1].longopt != 0 && !streqabbr(usage[i1].longopt, longopt_name, min_abbr_len)) - ++i1; - if (usage[i1].longopt != 0) - { // now test if the match is unambiguous by checking for another match - int i2 = i1 + 1; - while (usage[i2].longopt != 0 && !streqabbr(usage[i2].longopt, longopt_name, min_abbr_len)) - ++i2; - - if (usage[i2].longopt == 0) // if there was no second match it's unambiguous, so accept i1 as idx - idx = i1; - } - } - - // if we found something, disable handle_short_options (only relevant if single_minus_longopt) - if (usage[idx].longopt != 0) - handle_short_options = false; - - try_single_minus_longopt = false; // prevent looking for longopt in the middle of shortopt group - - optarg = longopt_name; - while (*optarg != 0 && *optarg != '=') - ++optarg; - if (*optarg == '=') // attached argument - ++optarg; - else - // possibly detached argument - optarg = (have_more_args ? args[1] : 0); - } - - /************************ short option ***********************************/ - if (handle_short_options) - { - if (*++param == 0) // point at the 1st/next option character - break; // end of short option group - - idx = 0; - while (usage[idx].shortopt != 0 && !instr(*param, usage[idx].shortopt)) - ++idx; - - if (param[1] == 0) // if the potential argument is separate - optarg = (have_more_args ? args[1] : 0); - else - // if the potential argument is attached - optarg = param + 1; - } - - const Descriptor* descriptor = &usage[idx]; - - if (descriptor->shortopt == 0) /************** unknown option ********************/ - { - // look for dummy entry (shortopt == "" and longopt == "") to use as Descriptor for unknown options - idx = 0; - while (usage[idx].shortopt != 0 && (usage[idx].shortopt[0] != 0 || usage[idx].longopt[0] != 0)) - ++idx; - descriptor = (usage[idx].shortopt == 0 ? 0 : &usage[idx]); - } - - if (descriptor != 0) - { - Option option(descriptor, param, optarg); - switch (descriptor->check_arg(option, print_errors)) - { - case ARG_ILLEGAL: - return false; // fatal - case ARG_OK: - // skip one element of the argument vector, if it's a separated argument - if (optarg != 0 && have_more_args && optarg == args[1]) - { - shift(args, nonops); - if (numargs > 0) - --numargs; - ++args; - } - - // No further short options are possible after an argument - handle_short_options = false; - - break; - case ARG_IGNORE: - case ARG_NONE: - option.arg = 0; - break; - } - - if (!action.perform(option)) - return false; - } - - } while (handle_short_options); - - shift(args, nonops); - ++args; - if (numargs > 0) - --numargs; - - } // while - - if (numargs > 0 && *args == 0) // It's a bug in the caller if numargs is greater than the actual number - numargs = 0; // of arguments, but as a service to the user we fix this if we spot it. - - if (numargs < 0) // if we don't know the number of remaining non-option arguments - { // we need to count them - numargs = 0; - while (args[numargs] != 0) - ++numargs; - } - - return action.finished(numargs + nonops, args - nonops); -} - -/** - * @internal - * @brief The implementation of option::printUsage(). - */ -struct PrintUsageImplementation -{ - /** - * @internal - * @brief Interface for Functors that write (part of) a string somewhere. - */ - struct IStringWriter - { - /** - * @brief Writes the given number of chars beginning at the given pointer somewhere. - */ - virtual void operator()(const char*, int) = 0; /// @note 2017-01-26 GRVS Made pure virtual. - }; - - /** - * @internal - * @brief Encapsulates a function with signature func(string, size) where - * string can be initialized with a const char* and size with an int. - */ - template - struct FunctionWriter: public IStringWriter - { - Function* write; - - virtual void operator()(const char* str, int size) override /// @note 2017-01-26 GRVS Added override. - { - (*write)(str, size); - } - - FunctionWriter(Function* w) : - write(w) - { - } - }; - - /** - * @internal - * @brief Encapsulates a reference to an object with a write(string, size) - * method like that of @c std::ostream. - */ - template - struct OStreamWriter: public IStringWriter - { - OStream& ostream; - - virtual void operator()(const char* str, int size) override - { - ostream.write(str, size); - } - - OStreamWriter(OStream& o) : - ostream(o) - { - } - }; - - /** - * @internal - * @brief Like OStreamWriter but encapsulates a @c const reference, which is - * typically a temporary object of a user class. - */ - template - struct TemporaryWriter: public IStringWriter - { - const Temporary& userstream; - - virtual void operator()(const char* str, int size) override - { - userstream.write(str, size); - } - - TemporaryWriter(const Temporary& u) : - userstream(u) - { - } - }; - - /** - * @internal - * @brief Encapsulates a function with the signature func(fd, string, size) (the - * signature of the @c write() system call) - * where fd can be initialized from an int, string from a const char* and size from an int. - */ - template - struct SyscallWriter: public IStringWriter - { - Syscall* write; - int fd; - - virtual void operator()(const char* str, int size) override - { - (*write)(fd, str, size); - } - - SyscallWriter(Syscall* w, int f) : - write(w), fd(f) - { - } - }; - - /** - * @internal - * @brief Encapsulates a function with the same signature as @c std::fwrite(). - */ - template - struct StreamWriter: public IStringWriter - { - Function* fwrite; - Stream* stream; - - virtual void operator()(const char* str, int size) override - { - (*fwrite)(str, size, 1, stream); - } - - StreamWriter(Function* w, Stream* s) : - fwrite(w), stream(s) - { - } - }; - - /** - * @internal - * @brief Sets i1 = max(i1, i2) - */ - static void upmax(int& i1, int i2) - { - i1 = (i1 >= i2 ? i1 : i2); - } - - /** - * @internal - * @brief Moves the "cursor" to column @c want_x assuming it is currently at column @c x - * and sets @c x=want_x . - * If x > want_x , a line break is output before indenting. - * - * @param write Spaces and possibly a line break are written via this functor to get - * the desired indentation @c want_x . - * @param[in,out] x the current indentation. Set to @c want_x by this method. - * @param want_x the desired indentation. - */ - static void indent(IStringWriter& write, int& x, int want_x) - { - int indent = want_x - x; - if (indent < 0) - { - write("\n", 1); - indent = want_x; - } - - if (indent > 0) - { - char space = ' '; - for (int i = 0; i < indent; ++i) - write(&space, 1); - x = want_x; - } - } - - /** - * @brief Returns true if ch is the unicode code point of a wide character. - * - * @note - * The following character ranges are treated as wide - * @code - * 1100..115F - * 2329..232A (just 2 characters!) - * 2E80..A4C6 except for 303F - * A960..A97C - * AC00..D7FB - * F900..FAFF - * FE10..FE6B - * FF01..FF60 - * FFE0..FFE6 - * 1B000...... - * @endcode - */ - static bool isWideChar(unsigned ch) - { - if (ch == 0x303F) - return false; - - return ((0x1100 <= ch && ch <= 0x115F) || (0x2329 <= ch && ch <= 0x232A) || (0x2E80 <= ch && ch <= 0xA4C6) - || (0xA960 <= ch && ch <= 0xA97C) || (0xAC00 <= ch && ch <= 0xD7FB) || (0xF900 <= ch && ch <= 0xFAFF) - || (0xFE10 <= ch && ch <= 0xFE6B) || (0xFF01 <= ch && ch <= 0xFF60) || (0xFFE0 <= ch && ch <= 0xFFE6) - || (0x1B000 <= ch)); - } - - /** - * @internal - * @brief Splits a @c Descriptor[] array into tables, rows, lines and columns and - * iterates over these components. - * - * The top-level organizational unit is the @e table. - * A table begins at a Descriptor with @c help!=NULL and extends up to - * a Descriptor with @c help==NULL. - * - * A table consists of @e rows. Due to line-wrapping and explicit breaks - * a row may take multiple lines on screen. Rows within the table are separated - * by \\n. They never cross Descriptor boundaries. This means a row ends either - * at \\n or the 0 at the end of the help string. - * - * A row consists of columns/cells. Columns/cells within a row are separated by \\t. - * Line breaks within a cell are marked by \\v. - * - * Rows in the same table need not have the same number of columns/cells. The - * extreme case are interjections, which are rows that contain neither \\t nor \\v. - * These are NOT treated specially by LinePartIterator, but they are treated - * specially by printUsage(). - * - * LinePartIterator iterates through the usage at 3 levels: table, row and part. - * Tables and rows are as described above. A @e part is a line within a cell. - * LinePartIterator iterates through 1st parts of all cells, then through the 2nd - * parts of all cells (if any),... @n - * Example: The row "1 \v 3 \t 2 \v 4" has 2 cells/columns and 4 parts. - * The parts will be returned in the order 1, 2, 3, 4. - * - * It is possible that some cells have fewer parts than others. In this case - * LinePartIterator will "fill up" these cells with 0-length parts. IOW, LinePartIterator - * always returns the same number of parts for each column. Note that this is different - * from the way rows and columns are handled. LinePartIterator does @e not guarantee that - * the same number of columns will be returned for each row. - * - */ - class LinePartIterator - { - const Descriptor* tablestart; //!< The 1st descriptor of the current table. - const Descriptor* rowdesc; //!< The Descriptor that contains the current row. - const char* rowstart; //!< Ptr to 1st character of current row within rowdesc->help. - const char* ptr; //!< Ptr to current part within the current row. - int col; //!< Index of current column. - int len; //!< Length of the current part (that ptr points at) in BYTES - int screenlen; //!< Length of the current part in screen columns (taking narrow/wide chars into account). - int max_line_in_block; //!< Greatest index of a line within the block. This is the number of \\v within the cell with the most \\vs. - int line_in_block; //!< Line index within the current cell of the current part. - int target_line_in_block; //!< Line index of the parts we should return to the user on this iteration. - bool hit_target_line; //!< Flag whether we encountered a part with line index target_line_in_block in the current cell. - - /** - * @brief Determines the byte and character lengths of the part at @ref ptr and - * stores them in @ref len and @ref screenlen respectively. - */ - void update_length() - { - screenlen = 0; - for (len = 0; ptr[len] != 0 && ptr[len] != '\v' && ptr[len] != '\t' && ptr[len] != '\n'; ++len) - { - ++screenlen; - unsigned ch = (unsigned char) ptr[len]; - if (ch > 0xC1) // everything <= 0xC1 (yes, even 0xC1 itself) is not a valid UTF-8 start byte - { - // int __builtin_clz (unsigned int x) - // Returns the number of leading 0-bits in x, starting at the most significant bit - unsigned mask = (unsigned) -1 >> __builtin_clz(ch ^ 0xff); - ch = ch & mask; // mask out length bits, we don't verify their correctness - while (((unsigned char) ptr[len + 1] ^ 0x80) <= 0x3F) // while next byte is continuation byte - { - ch = (ch << 6) ^ (unsigned char) ptr[len + 1] ^ 0x80; // add continuation to char code - ++len; - } - // ch is the decoded unicode code point - if (ch >= 0x1100 && isWideChar(ch)) // the test for 0x1100 is here to avoid the function call in the Latin case - ++screenlen; - } - } - } - - public: - //! @brief Creates an iterator for @c usage. - LinePartIterator(const Descriptor usage[]) : - tablestart(usage), rowdesc(0), rowstart(0), ptr(0), col(-1), len(0), max_line_in_block(0), line_in_block(0), - target_line_in_block(0), hit_target_line(true) - { - } - - /** - * @brief Moves iteration to the next table (if any). Has to be called once on a new - * LinePartIterator to move to the 1st table. - * @retval false if moving to next table failed because no further table exists. - */ - bool nextTable() - { - // If this is NOT the first time nextTable() is called after the constructor, - // then skip to the next table break (i.e. a Descriptor with help == 0) - if (rowdesc != 0) - { - while (tablestart->help != 0 && tablestart->shortopt != 0) - ++tablestart; - } - - // Find the next table after the break (if any) - while (tablestart->help == 0 && tablestart->shortopt != 0) - ++tablestart; - - restartTable(); - return rowstart != 0; - } - - /** - * @brief Reset iteration to the beginning of the current table. - */ - void restartTable() - { - rowdesc = tablestart; - rowstart = tablestart->help; - ptr = 0; - } - - /** - * @brief Moves iteration to the next row (if any). Has to be called once after each call to - * @ref nextTable() to move to the 1st row of the table. - * @retval false if moving to next row failed because no further row exists. - */ - bool nextRow() - { - if (ptr == 0) - { - restartRow(); - return rowstart != 0; - } - - while (*ptr != 0 && *ptr != '\n') - ++ptr; - - if (*ptr == 0) - { - if ((rowdesc + 1)->help == 0) // table break - return false; - - ++rowdesc; - rowstart = rowdesc->help; - } - else // if (*ptr == '\n') - { - rowstart = ptr + 1; - } - - restartRow(); - return true; - } - - /** - * @brief Reset iteration to the beginning of the current row. - */ - void restartRow() - { - ptr = rowstart; - col = -1; - len = 0; - screenlen = 0; - max_line_in_block = 0; - line_in_block = 0; - target_line_in_block = 0; - hit_target_line = true; - } - - /** - * @brief Moves iteration to the next part (if any). Has to be called once after each call to - * @ref nextRow() to move to the 1st part of the row. - * @retval false if moving to next part failed because no further part exists. - * - * See @ref LinePartIterator for details about the iteration. - */ - bool next() - { - if (ptr == 0) - return false; - - if (col == -1) - { - col = 0; - update_length(); - return true; - } - - ptr += len; - while (true) - { - switch (*ptr) - { - case '\v': - upmax(max_line_in_block, ++line_in_block); - ++ptr; - break; - case '\t': - if (!hit_target_line) // if previous column did not have the targetline - { // then "insert" a 0-length part - update_length(); - hit_target_line = true; - return true; - } - - hit_target_line = false; - line_in_block = 0; - ++col; - ++ptr; - break; - case 0: - case '\n': - if (!hit_target_line) // if previous column did not have the targetline - { // then "insert" a 0-length part - update_length(); - hit_target_line = true; - return true; - } - - if (++target_line_in_block > max_line_in_block) - { - update_length(); - return false; - } - - hit_target_line = false; - line_in_block = 0; - col = 0; - ptr = rowstart; - continue; - default: - ++ptr; - continue; - } // switch - - if (line_in_block == target_line_in_block) - { - update_length(); - hit_target_line = true; - return true; - } - } // while - } - - /** - * @brief Returns the index (counting from 0) of the column in which - * the part pointed to by @ref data() is located. - */ - int column() - { - return col; - } - - /** - * @brief Returns the index (counting from 0) of the line within the current column - * this part belongs to. - */ - int line() - { - return target_line_in_block; // NOT line_in_block !!! It would be wrong if !hit_target_line - } - - /** - * @brief Returns the length of the part pointed to by @ref data() in raw chars (not UTF-8 characters). - */ - int length() - { - return len; - } - - /** - * @brief Returns the width in screen columns of the part pointed to by @ref data(). - * Takes multi-byte UTF-8 sequences and wide characters into account. - */ - int screenLength() - { - return screenlen; - } - - /** - * @brief Returns the current part of the iteration. - */ - const char* data() - { - return ptr; - } - }; - - /** - * @internal - * @brief Takes input and line wraps it, writing out one line at a time so that - * it can be interleaved with output from other columns. - * - * The LineWrapper is used to handle the last column of each table as well as interjections. - * The LineWrapper is called once for each line of output. If the data given to it fits - * into the designated width of the last column it is simply written out. If there - * is too much data, an appropriate split point is located and only the data up to this - * split point is written out. The rest of the data is queued for the next line. - * That way the last column can be line wrapped and interleaved with data from - * other columns. The following example makes this clearer: - * @code - * Column 1,1 Column 2,1 This is a long text - * Column 1,2 Column 2,2 that does not fit into - * a single line. - * @endcode - * - * The difficulty in producing this output is that the whole string - * "This is a long text that does not fit into a single line" is the - * 1st and only part of column 3. In order to produce the above - * output the string must be output piecemeal, interleaved with - * the data from the other columns. - */ - class LineWrapper - { - static const int bufmask = 15; //!< Must be a power of 2 minus 1. - /** - * @brief Ring buffer for length component of pair (data, length). - */ - int lenbuf[bufmask + 1]; - /** - * @brief Ring buffer for data component of pair (data, length). - */ - const char* datbuf[bufmask + 1]; - /** - * @brief The indentation of the column to which the LineBuffer outputs. LineBuffer - * assumes that the indentation has already been written when @ref process() - * is called, so this value is only used when a buffer flush requires writing - * additional lines of output. - */ - int x; - /** - * @brief The width of the column to line wrap. - */ - int width; - int head; //!< @brief index for next write - int tail; //!< @brief index for next read - 1 (i.e. increment tail BEFORE read) - - /** - * @brief Multiple methods of LineWrapper may decide to flush part of the buffer to - * free up space. The contract of process() says that only 1 line is output. So - * this variable is used to track whether something has output a line. It is - * reset at the beginning of process() and checked at the end to decide if - * output has already occurred or is still needed. - */ - bool wrote_something; - - bool buf_empty() - { - return ((tail + 1) & bufmask) == head; - } - - bool buf_full() - { - return tail == head; - } - - void buf_store(const char* data, int len) - { - lenbuf[head] = len; - datbuf[head] = data; - head = (head + 1) & bufmask; - } - - //! @brief Call BEFORE reading ...buf[tail]. - void buf_next() - { - tail = (tail + 1) & bufmask; - } - - /** - * @brief Writes (data,len) into the ring buffer. If the buffer is full, a single line - * is flushed out of the buffer into @c write. - */ - void output(IStringWriter& write, const char* data, int len) - { - if (buf_full()) - write_one_line(write); - - buf_store(data, len); - } - - /** - * @brief Writes a single line of output from the buffer to @c write. - */ - void write_one_line(IStringWriter& write) - { - if (wrote_something) // if we already wrote something, we need to start a new line - { - write("\n", 1); - int _ = 0; - indent(write, _, x); - } - - if (!buf_empty()) - { - buf_next(); - write(datbuf[tail], lenbuf[tail]); - } - - wrote_something = true; - } - public: - - /** - * @brief Writes out all remaining data from the LineWrapper using @c write. - * Unlike @ref process() this method indents all lines including the first and - * will output a \\n at the end (but only if something has been written). - */ - void flush(IStringWriter& write) - { - if (buf_empty()) - return; - int _ = 0; - indent(write, _, x); - wrote_something = false; - while (!buf_empty()) - write_one_line(write); - write("\n", 1); - } - - /** - * @brief Process, wrap and output the next piece of data. - * - * process() will output at least one line of output. This is not necessarily - * the @c data passed in. It may be data queued from a prior call to process(). - * If the internal buffer is full, more than 1 line will be output. - * - * process() assumes that the a proper amount of indentation has already been - * output. It won't write any further indentation before the 1st line. If - * more than 1 line is written due to buffer constraints, the lines following - * the first will be indented by this method, though. - * - * No \\n is written by this method after the last line that is written. - * - * @param write where to write the data. - * @param data the new chunk of data to write. - * @param len the length of the chunk of data to write. - */ - void process(IStringWriter& write, const char* data, int len) - { - wrote_something = false; - - while (len > 0) - { - if (len <= width) // quick test that works because utf8width <= len (all wide chars have at least 2 bytes) - { - output(write, data, len); - len = 0; - } - else // if (len > width) it's possible (but not guaranteed) that utf8len > width - { - int utf8width = 0; - int maxi = 0; - while (maxi < len && utf8width < width) - { - int charbytes = 1; - unsigned ch = (unsigned char) data[maxi]; - if (ch > 0xC1) // everything <= 0xC1 (yes, even 0xC1 itself) is not a valid UTF-8 start byte - { - // int __builtin_clz (unsigned int x) - // Returns the number of leading 0-bits in x, starting at the most significant bit - unsigned mask = (unsigned) -1 >> __builtin_clz(ch ^ 0xff); - ch = ch & mask; // mask out length bits, we don't verify their correctness - while ((maxi + charbytes < len) && // - (((unsigned char) data[maxi + charbytes] ^ 0x80) <= 0x3F)) // while next byte is continuation byte - { - ch = (ch << 6) ^ (unsigned char) data[maxi + charbytes] ^ 0x80; // add continuation to char code - ++charbytes; - } - // ch is the decoded unicode code point - if (ch >= 0x1100 && isWideChar(ch)) // the test for 0x1100 is here to avoid the function call in the Latin case - { - if (utf8width + 2 > width) - break; - ++utf8width; - } - } - ++utf8width; - maxi += charbytes; - } - - // data[maxi-1] is the last byte of the UTF-8 sequence of the last character that fits - // onto the 1st line. If maxi == len, all characters fit on the line. - - if (maxi == len) - { - output(write, data, len); - len = 0; - } - else // if (maxi < len) at least 1 character (data[maxi] that is) doesn't fit on the line - { - int i; - for (i = maxi; i >= 0; --i) - if (data[i] == ' ') - break; - - if (i >= 0) - { - output(write, data, i); - data += i + 1; - len -= i + 1; - } - else // did not find a space to split at => split before data[maxi] - { // data[maxi] is always the beginning of a character, never a continuation byte - output(write, data, maxi); - data += maxi; - len -= maxi; - } - } - } - } - if (!wrote_something) // if we didn't already write something to make space in the buffer - write_one_line(write); // write at most one line of actual output - } - - /** - * @brief Constructs a LineWrapper that wraps its output to fit into - * screen columns @c x1 (incl.) to @c x2 (excl.). - * - * @c x1 gives the indentation LineWrapper uses if it needs to indent. - */ - LineWrapper(int x1, int x2) : - x(x1), width(x2 - x1), head(0), tail(bufmask) - { - if (width < 2) // because of wide characters we need at least width 2 or the code breaks - width = 2; - } - }; - - /** - * @internal - * @brief This is the implementation that is shared between all printUsage() templates. - * Because all printUsage() templates share this implementation, there is no template bloat. - */ - static void printUsage(IStringWriter& write, const Descriptor usage[], int width = 80, // - int last_column_min_percent = 50, int last_column_own_line_max_percent = 75) - { - if (width < 1) // protect against nonsense values - width = 80; - - if (width > 10000) // protect against overflow in the following computation - width = 10000; - - int last_column_min_width = ((width * last_column_min_percent) + 50) / 100; - int last_column_own_line_max_width = ((width * last_column_own_line_max_percent) + 50) / 100; - if (last_column_own_line_max_width == 0) - last_column_own_line_max_width = 1; - - LinePartIterator part(usage); - while (part.nextTable()) - { - - /***************** Determine column widths *******************************/ - - const int maxcolumns = 8; // 8 columns are enough for everyone - int col_width[maxcolumns]; - int lastcolumn; - int leftwidth; - int overlong_column_threshold = 10000; - do - { - lastcolumn = 0; - for (int i = 0; i < maxcolumns; ++i) - col_width[i] = 0; - - part.restartTable(); - while (part.nextRow()) - { - while (part.next()) - { - if (part.column() < maxcolumns) - { - upmax(lastcolumn, part.column()); - if (part.screenLength() < overlong_column_threshold) - // We don't let rows that don't use table separators (\t or \v) influence - // the width of column 0. This allows the user to interject section headers - // or explanatory paragraphs that do not participate in the table layout. - if (part.column() > 0 || part.line() > 0 || part.data()[part.length()] == '\t' - || part.data()[part.length()] == '\v') - upmax(col_width[part.column()], part.screenLength()); - } - } - } - - /* - * If the last column doesn't fit on the same - * line as the other columns, we can fix that by starting it on its own line. - * However we can't do this for any of the columns 0..lastcolumn-1. - * If their sum exceeds the maximum width we try to fix this by iteratively - * ignoring the widest line parts in the width determination until - * we arrive at a series of column widths that fit into one line. - * The result is a layout where everything is nicely formatted - * except for a few overlong fragments. - * */ - - leftwidth = 0; - overlong_column_threshold = 0; - for (int i = 0; i < lastcolumn; ++i) - { - leftwidth += col_width[i]; - upmax(overlong_column_threshold, col_width[i]); - } - - } while (leftwidth > width); - - /**************** Determine tab stops and last column handling **********************/ - - int tabstop[maxcolumns]; - tabstop[0] = 0; - for (int i = 1; i < maxcolumns; ++i) - tabstop[i] = tabstop[i - 1] + col_width[i - 1]; - - int rightwidth = width - tabstop[lastcolumn]; - bool print_last_column_on_own_line = false; - if (rightwidth < last_column_min_width && // if we don't have the minimum requested width for the last column - ( col_width[lastcolumn] == 0 || // and all last columns are > overlong_column_threshold - rightwidth < col_width[lastcolumn] // or there is at least one last column that requires more than the space available - ) - ) - { - print_last_column_on_own_line = true; - rightwidth = last_column_own_line_max_width; - } - - // If lastcolumn == 0 we must disable print_last_column_on_own_line because - // otherwise 2 copies of the last (and only) column would be output. - // Actually this is just defensive programming. It is currently not - // possible that lastcolumn==0 and print_last_column_on_own_line==true - // at the same time, because lastcolumn==0 => tabstop[lastcolumn] == 0 => - // rightwidth==width => rightwidth>=last_column_min_width (unless someone passes - // a bullshit value >100 for last_column_min_percent) => the above if condition - // is false => print_last_column_on_own_line==false - if (lastcolumn == 0) - print_last_column_on_own_line = false; - - LineWrapper lastColumnLineWrapper(width - rightwidth, width); - LineWrapper interjectionLineWrapper(0, width); - - part.restartTable(); - - /***************** Print out all rows of the table *************************************/ - - while (part.nextRow()) - { - int x = -1; - while (part.next()) - { - if (part.column() > lastcolumn) - continue; // drop excess columns (can happen if lastcolumn == maxcolumns-1) - - if (part.column() == 0) - { - if (x >= 0) - write("\n", 1); - x = 0; - } - - indent(write, x, tabstop[part.column()]); - - if ((part.column() < lastcolumn) - && (part.column() > 0 || part.line() > 0 || part.data()[part.length()] == '\t' - || part.data()[part.length()] == '\v')) - { - write(part.data(), part.length()); - x += part.screenLength(); - } - else // either part.column() == lastcolumn or we are in the special case of - // an interjection that doesn't contain \v or \t - { - // NOTE: This code block is not necessarily executed for - // each line, because some rows may have fewer columns. - - LineWrapper& lineWrapper = (part.column() == 0) ? interjectionLineWrapper : lastColumnLineWrapper; - - if (!print_last_column_on_own_line || part.column() != lastcolumn) - lineWrapper.process(write, part.data(), part.length()); - } - } // while - - if (print_last_column_on_own_line) - { - part.restartRow(); - while (part.next()) - { - if (part.column() == lastcolumn) - { - write("\n", 1); - int _ = 0; - indent(write, _, width - rightwidth); - lastColumnLineWrapper.process(write, part.data(), part.length()); - } - } - } - - write("\n", 1); - lastColumnLineWrapper.flush(write); - interjectionLineWrapper.flush(write); - } - } - } - -} -; - -/** - * @brief Outputs a nicely formatted usage string with support for multi-column formatting - * and line-wrapping. - * - * printUsage() takes the @c help texts of a Descriptor[] array and formats them into - * a usage message, wrapping lines to achieve the desired output width. - * - * Table formatting: - * - * Aside from plain strings which are simply line-wrapped, the usage may contain tables. Tables - * are used to align elements in the output. - * - * @code - * // Without a table. The explanatory texts are not aligned. - * -c, --create |Creates something. - * -k, --kill |Destroys something. - * - * // With table formatting. The explanatory texts are aligned. - * -c, --create |Creates something. - * -k, --kill |Destroys something. - * @endcode - * - * Table formatting removes the need to pad help texts manually with spaces to achieve - * alignment. To create a table, simply insert \\t (tab) characters to separate the cells - * within a row. - * - * @code - * const option::Descriptor usage[] = { - * {..., "-c, --create \tCreates something." }, - * {..., "-k, --kill \tDestroys something." }, ... - * @endcode - * - * Note that you must include the minimum amount of space desired between cells yourself. - * Table formatting will insert further spaces as needed to achieve alignment. - * - * You can insert line breaks within cells by using \\v (vertical tab). - * - * @code - * const option::Descriptor usage[] = { - * {..., "-c,\v--create \tCreates\vsomething." }, - * {..., "-k,\v--kill \tDestroys\vsomething." }, ... - * - * // results in - * - * -c, Creates - * --create something. - * -k, Destroys - * --kill something. - * @endcode - * - * You can mix lines that do not use \\t or \\v with those that do. The plain - * lines will not mess up the table layout. Alignment of the table columns will - * be maintained even across these interjections. - * - * @code - * const option::Descriptor usage[] = { - * {..., "-c, --create \tCreates something." }, - * {..., "----------------------------------" }, - * {..., "-k, --kill \tDestroys something." }, ... - * - * // results in - * - * -c, --create Creates something. - * ---------------------------------- - * -k, --kill Destroys something. - * @endcode - * - * You can have multiple tables within the same usage whose columns are - * aligned independently. Simply insert a dummy Descriptor with @c help==0. - * - * @code - * const option::Descriptor usage[] = { - * {..., "Long options:" }, - * {..., "--very-long-option \tDoes something long." }, - * {..., "--ultra-super-mega-long-option \tTakes forever to complete." }, - * {..., 0 }, // ---------- table break ----------- - * {..., "Short options:" }, - * {..., "-s \tShort." }, - * {..., "-q \tQuick." }, ... - * - * // results in - * - * Long options: - * --very-long-option Does something long. - * --ultra-super-mega-long-option Takes forever to complete. - * Short options: - * -s Short. - * -q Quick. - * - * // Without the table break it would be - * - * Long options: - * --very-long-option Does something long. - * --ultra-super-mega-long-option Takes forever to complete. - * Short options: - * -s Short. - * -q Quick. - * @endcode - * - * Output methods: - * - * Because TheLeanMeanC++Option parser is freestanding, you have to provide the means for - * output in the first argument(s) to printUsage(). Because printUsage() is implemented as - * a set of template functions, you have great flexibility in your choice of output - * method. The following example demonstrates typical uses. Anything that's similar enough - * will work. - * - * @code - * #include // write() - * #include // cout - * #include // ostringstream - * #include // fwrite() - * using namespace std; - * - * void my_write(const char* str, int size) { - * fwrite(str, size, 1, stdout); - * } - * - * struct MyWriter { - * void write(const char* buf, size_t size) const { - * fwrite(str, size, 1, stdout); - * } - * }; - * - * struct MyWriteFunctor { - * void operator()(const char* buf, size_t size) { - * fwrite(str, size, 1, stdout); - * } - * }; - * ... - * printUsage(my_write, usage); // custom write function - * printUsage(MyWriter(), usage); // temporary of a custom class - * MyWriter writer; - * printUsage(writer, usage); // custom class object - * MyWriteFunctor wfunctor; - * printUsage(&wfunctor, usage); // custom functor - * printUsage(write, 1, usage); // write() to file descriptor 1 - * printUsage(cout, usage); // an ostream& - * printUsage(fwrite, stdout, usage); // fwrite() to stdout - * ostringstream sstr; - * printUsage(sstr, usage); // an ostringstream& - * - * @endcode - * - * @par Notes: - * @li the @c write() method of a class that is to be passed as a temporary - * as @c MyWriter() is in the example, must be a @c const method, because - * temporary objects are passed as const reference. This only applies to - * temporary objects that are created and destroyed in the same statement. - * If you create an object like @c writer in the example, this restriction - * does not apply. - * @li a functor like @c MyWriteFunctor in the example must be passed as a pointer. - * This differs from the way functors are passed to e.g. the STL algorithms. - * @li All printUsage() templates are tiny wrappers around a shared non-template implementation. - * So there's no penalty for using different versions in the same program. - * @li printUsage() always interprets Descriptor::help as UTF-8 and always produces UTF-8-encoded - * output. If your system uses a different charset, you must do your own conversion. You - * may also need to change the font of the console to see non-ASCII characters properly. - * This is particularly true for Windows. - * @li @b Security @b warning: Do not insert untrusted strings (such as user-supplied arguments) - * into the usage. printUsage() has no protection against malicious UTF-8 sequences. - * - * @param prn The output method to use. See the examples above. - * @param usage the Descriptor[] array whose @c help texts will be formatted. - * @param width the maximum number of characters per output line. Note that this number is - * in actual characters, not bytes. printUsage() supports UTF-8 in @c help and will - * count multi-byte UTF-8 sequences properly. Asian wide characters are counted - * as 2 characters. - * @param last_column_min_percent (0-100) The minimum percentage of @c width that should be available - * for the last column (which typically contains the textual explanation of an option). - * If less space is available, the last column will be printed on its own line, indented - * according to @c last_column_own_line_max_percent. - * @param last_column_own_line_max_percent (0-100) If the last column is printed on its own line due to - * less than @c last_column_min_percent of the width being available, then only - * @c last_column_own_line_max_percent of the extra line(s) will be used for the - * last column's text. This ensures an indentation. See example below. - * - * @code - * // width=20, last_column_min_percent=50 (i.e. last col. min. width=10) - * --3456789 1234567890 - * 1234567890 - * - * // width=20, last_column_min_percent=75 (i.e. last col. min. width=15) - * // last_column_own_line_max_percent=75 - * --3456789 - * 123456789012345 - * 67890 - * - * // width=20, last_column_min_percent=75 (i.e. last col. min. width=15) - * // last_column_own_line_max_percent=33 (i.e. max. 5) - * --3456789 - * 12345 - * 67890 - * 12345 - * 67890 - * @endcode - */ -template -void printUsage(OStream& prn, const Descriptor usage[], int width = 80, int last_column_min_percent = 50, - int last_column_own_line_max_percent = 75) -{ - PrintUsageImplementation::OStreamWriter write(prn); - PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent); -} - -template -void printUsage(Function* prn, const Descriptor usage[], int width = 80, int last_column_min_percent = 50, - int last_column_own_line_max_percent = 75) -{ - PrintUsageImplementation::FunctionWriter write(prn); - PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent); -} - -template -void printUsage(const Temporary& prn, const Descriptor usage[], int width = 80, int last_column_min_percent = 50, - int last_column_own_line_max_percent = 75) -{ - PrintUsageImplementation::TemporaryWriter write(prn); - PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent); -} - -template -void printUsage(Syscall* prn, int fd, const Descriptor usage[], int width = 80, int last_column_min_percent = 50, - int last_column_own_line_max_percent = 75) -{ - PrintUsageImplementation::SyscallWriter write(prn, fd); - PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent); -} - -template -void printUsage(Function* prn, Stream* stream, const Descriptor usage[], int width = 80, int last_column_min_percent = - 50, - int last_column_own_line_max_percent = 75) -{ - PrintUsageImplementation::StreamWriter write(prn, stream); - PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent); -} - -} -// namespace option - -#endif /* OPTIONPARSER_H_ */ diff --git a/third_party/optionparser-1.4/src/printUsage.h b/third_party/optionparser-1.4/src/printUsage.h deleted file mode 100644 index ebe313c8..00000000 --- a/third_party/optionparser-1.4/src/printUsage.h +++ /dev/null @@ -1,11 +0,0 @@ -/** - * @file - * @brief Dummy file for documentation purposes. - */ - -/** - * @brief @ref option::printUsage() formats the usage message with column alignment and line wrapping. - */ -class UsageMsg{ - // Dummy file to get an entry for printUsage() in Classes. -}; diff --git a/third_party/optionparser-1.4/src/testodr1.cc b/third_party/optionparser-1.4/src/testodr1.cc deleted file mode 100644 index 1ca677ef..00000000 --- a/third_party/optionparser-1.4/src/testodr1.cc +++ /dev/null @@ -1,50 +0,0 @@ -/* Written 2012 by Matthias S. Benkmann - * - * The author hereby waives all copyright and related rights to the contents - * of this example file (testodr1.cc) to the extent possible under the law. - */ - -/** - * @file - * @brief Test for multiple definition errors. - * - * @note - * This program is for developing TLMC++OP. It is neither an example nor a functionality test. - * Do not worry if it doesn't compile or run on your platform. - * - * @ref testodr1.cc and @ref testodr2.cc test optionparser.h for - * violations of the one definition rule, both at compile-time and at - * link-time. IOW, they test if optionparser.h can be included - * multiple times as well as that multiple object files that include - * it can be linked together. - * - */ - -#include "optionparser.h" -#include "optionparser.h" //intentionally included twice - -#include - -using option::Option; -using option::Descriptor; - -extern const Descriptor usage[]; - -extern bool bar(int argc, const char* argv[]) -{ - printUsage(std::fwrite, stdout, usage); - option::Stats stats(usage, argc, argv); - option::Option buffer [stats.buffer_max]; - option::Option options[stats.options_max]; - option::Parser parse(usage, argc, argv, options, buffer); - return parse.error(); -} - -int main() -{ - Descriptor d = usage[0]; - std::printf("%s",d.shortopt); -} - - - diff --git a/third_party/optionparser-1.4/src/testodr2.cc b/third_party/optionparser-1.4/src/testodr2.cc deleted file mode 100644 index 979d3a55..00000000 --- a/third_party/optionparser-1.4/src/testodr2.cc +++ /dev/null @@ -1,39 +0,0 @@ -/* Written 2012 by Matthias S. Benkmann - * - * The author hereby waives all copyright and related rights to the contents - * of this example file (testodr2.cc) to the extent possible under the law. - */ - -/** - * @file - * @brief Test for multiple definition errors. - * @copydoc testodr1.cc - */ - -#include "optionparser.h" - -#include - -using option::Descriptor; -using option::Arg; -enum OptionIndex {CREATE}; -enum OptionType {DISABLE, ENABLE, OTHER}; - -extern const Descriptor usage[] = { - { CREATE, OTHER, - "c", "create", - Arg::None, - "--create\t\t\tTells the program to create something." - } - }; - -extern bool foo(int argc, const char* argv[]) -{ - printUsage(std::fwrite, stdout, usage); - option::Stats stats(usage, argc, argv); - option::Option buffer [stats.buffer_max]; - option::Option options[stats.options_max]; - option::Parser parse(usage, argc, argv, options, buffer); - return parse.error(); -} - diff --git a/third_party/optionparser-1.4/src/testparse.cpp b/third_party/optionparser-1.4/src/testparse.cpp deleted file mode 100644 index 7969166f..00000000 --- a/third_party/optionparser-1.4/src/testparse.cpp +++ /dev/null @@ -1,368 +0,0 @@ -/* Written 2012 by Matthias S. Benkmann - * - * The author hereby waives all copyright and related rights to the contents - * of this example file (testparse.cpp) to the extent possible under the law. - */ - -/** - * @file - * @brief Test program for option::Stats and option::Parser. - * - * @note - * This program is for developing TLMC++OP. It is neither an example nor a functionality test. - * Do not worry if it doesn't compile or run on your platform. - * - */ - -/** - * @mainpage - * @copydetails optionparser.h - */ - -#include -#include - -#include "optionparser.h" - -using option::Option; -using option::Descriptor; -using option::Parser; -using option::Stats; -using option::ArgStatus; - -struct Arg: public option::Arg -{ - static ArgStatus Required(const Option& option, bool) - { - return option.arg == 0 ? option::ARG_ILLEGAL : option::ARG_OK; - } - static ArgStatus Empty(const Option& option, bool) - { - return (option.arg == 0 || option.arg[0] == 0) ? option::ARG_OK : option::ARG_IGNORE; - } -}; - -char* gettext(const char * msgid) -{ - return (char*) msgid; -} - -const Descriptor empty_usage[] = { { 0, 0, 0, 0, 0, 0 } }; - -const Descriptor minimal_usage[] = // - { { 0, 0, "x", "", Arg::None, 0 }, // - { 0, 0, 0, 0, 0, 0 } }; - -const Descriptor optional_usage[] = // - { { 0, 0, "f", "", Arg::Required, 0 }, // - { 0, 0, 0, 0, 0, 0 } }; - -const Descriptor gettext_usage[] = // - { { 0, 0, "f", "", Arg::Required, gettext("This is a test") }, // - { 0, 0, 0, 0, 0, 0 } }; - -enum OptionIndex -{ - UNKNOWN, FOO, VERBOSE, X, ABBREVIATE, EMPTY -}; -enum OptionType -{ - UNUSED = 0, DISABLED = 1, ENABLED = 2 -}; - -const Descriptor multi_usage[] = // - { { UNKNOWN, 0, "", "", Arg::None, 0 }, // UNKNOWN option catch-all - { FOO, ENABLED, "", "enable-foo", Arg::None, 0 }, // FOO enable - { FOO, DISABLED, "", "disable-foo", Arg::None, 0 }, // FOO disable - { VERBOSE, 0, "v", "verbose", Arg::None, 0 }, // VERBOSE (counted option) - { X, 0, "X", "X", Arg::Required, 0 }, // -X, -X , -X=, --X= - { ABBREVIATE, 0, "", "abbreviate-me", Arg::None, 0 }, // ABBREVIATE - { EMPTY, 0, "", "emptyarg", Arg::Empty, 0 }, // EMPTY (ignores arguments that are not "") - { 0, 0, 0, 0, 0, 0 } }; - -const char* empty_args[] = { 0 }; -const char* non_options[] = { "1", "2", "3", (const char*) -1 }; -const char* unknown_option[] = { "--unknown", "nonoption", 0 }; -const char* lone_minus[] = { "-f", "-", "-", 0 }; -const char* lone_doubleminus[] = { "--", 0 }; - -// NOTE: (const char*) -1 is used to cause a segfault should this element be dereferenced. -// 0 is not used here, because the parser explicitly checks for 0 which could mask bugs. -// If a number of arguments >= 0 is passed, the parser is supposed to honor that and never -// dereference an element beyond the last. -const char* multi1[] = - { "--enable-foo", "--unknown1", "-u", "-vX", "xyzzy", "--", "--strangefilename", (const char*) -1 }; -const char* multi2[] = { "-vvXfoo", "-X", "bar", "-X=foobar", "-X", "", "--disable-foo", "-v", (const char*) -1 }; -const char* multi3[] = { "-abbr", "-abb", "--emptyarg", "-verbose", "--emptyarg", "", "--emptyarg=", "nonoption1", - "nonoption2", (const char*) -1 }; - -const char* illegal[] = { "-X", 0 }; -const char* reorder[] = { "-X", "--", "-", "-X", "--", "foo", "-v", "--", "bar", "--", 0 }; -const char* reorder2[] = { "-X", "--", "-", "-X", "--", "-", 0 }; - -int count(const char** args) -{ - for (int c = 0;; ++c) - if (args[c] == (const char*) -1) - return c; -} - -bool eq(const char* s1, const char* s2) -{ - if (s1 == s2) - return true; - - if (s1 == 0 || s2 == 0) - return false; - - while (*s1 != 0 && *s2 != 0) - { - ++s1; - ++s2; - } - - return *s1 == *s2; -} - -int main() -{ - { - Stats stats(empty_usage, -1, empty_args); - stats.add(empty_usage, 0, empty_args); - assert(stats.buffer_max == 1); - assert(stats.options_max == 1); - Option buffer[stats.buffer_max]; - Option options[stats.options_max]; - Parser parse(empty_usage, 99, empty_args, options, buffer); - parse.parse(empty_usage, -1, empty_args, options, buffer); - assert(parse.optionsCount() == 0); - assert(parse.nonOptionsCount() == 0); - assert(!buffer[0]); - assert(!options[0]); - assert(buffer[0].count()==0); - assert(parse.nonOptions()==0); - - stats.add(empty_usage, 3, non_options); - assert(stats.buffer_max == 1); - assert(stats.options_max == 1); - parse.parse(empty_usage, 3, non_options, options, buffer); - assert(parse.optionsCount() == 0); - assert(parse.nonOptionsCount() == 3); - assert(!buffer[0]); - assert(!options[0]); - assert(parse.nonOptions()==&non_options[0]); - - stats.add(minimal_usage, -1, unknown_option); - assert(stats.buffer_max == 1); - assert(stats.options_max == 2); - parse.parse(minimal_usage, -1, unknown_option, options, buffer); - assert(parse.optionsCount() == 0); - assert(parse.nonOptionsCount() == 1); - assert(!buffer[0]); - assert(!options[0]); - assert(parse.nonOptions()==&unknown_option[1]); - } - { - Stats stats(gettext_usage, -1, lone_minus); - Stats stats2; - stats2.add(gettext_usage, -1, lone_minus); - assert(stats.buffer_max == 2); - assert(stats.options_max == 2); - assert(stats2.buffer_max == 2); - assert(stats2.options_max == 2); - Option buffer[stats.buffer_max]; - Option options[stats.options_max]; - Parser parse; - parse.parse(gettext_usage, -1, lone_minus, options, buffer); - assert(parse.optionsCount() == 1); - assert(parse.nonOptionsCount() == 1); - assert(parse.nonOptions()==&lone_minus[2]); - assert(options[0]); - assert(buffer[0]); - assert(options[0].count()==1); - assert(options[0].isFirst()); - assert(options[0].isLast()); - assert(options[0].first() == options[0]); - assert(options[0].last() == options[0]); - assert(options[0].prevwrap() == &options[0]); - assert(options[0].nextwrap() == &options[0]); - assert(options[0].prev() == 0); - assert(options[0].next() == 0); - assert(options[0].desc == &gettext_usage[0]); - assert(eq(options[0].name, "f")); - assert(eq(options[0].arg, "-")); - } - { - Stats stats(optional_usage, -1, lone_minus); - Stats stats2; - stats2.add(optional_usage, -1, lone_minus); - assert(stats.buffer_max == 2); - assert(stats.options_max == 2); - assert(stats2.buffer_max == 2); - assert(stats2.options_max == 2); - Option buffer[stats.buffer_max]; - Option options[stats.options_max]; - Parser parse; - parse.parse(optional_usage, -1, lone_minus, options, buffer); - assert(parse.optionsCount() == 1); - assert(parse.nonOptionsCount() == 1); - assert(parse.nonOptions()==&lone_minus[2]); - assert(options[0]); - assert(buffer[0]); - assert(options[0].count()==1); - assert(options[0].isFirst()); - assert(options[0].isLast()); - assert(options[0].first() == options[0]); - assert(options[0].last() == options[0]); - assert(options[0].prevwrap() == &options[0]); - assert(options[0].nextwrap() == &options[0]); - assert(options[0].prev() == 0); - assert(options[0].next() == 0); - assert(options[0].desc == &optional_usage[0]); - assert(eq(options[0].name, "f")); - assert(eq(options[0].arg, "-")); - } - { - Stats stats; - stats.add(minimal_usage, -1, lone_doubleminus); - assert(stats.buffer_max == 1); - assert(stats.options_max == 2); - Option buffer[stats.buffer_max]; - Option options[stats.options_max]; - Parser parse(minimal_usage, -1, lone_doubleminus, options, buffer); - assert(parse.optionsCount() == 0); - assert(parse.nonOptionsCount() == 0); - assert(!buffer[0]); - assert(!options[0]); - assert(parse.nonOptions()==0); - } - { - Stats stats; - stats.add(multi_usage, count(multi1), multi1, 4, true); - assert(stats.buffer_max == 6); - assert(stats.options_max == 7); - stats.add(multi_usage, count(multi2), multi2, 4, true); - assert(stats.buffer_max == 14); - assert(stats.options_max == 7); - stats.add(multi_usage, count(multi3), multi3, 4, true); - assert(stats.buffer_max == 22); - assert(stats.options_max == 7); - Option buffer[stats.buffer_max]; - Option options[stats.options_max]; - assert(options[FOO].last()->type() == UNUSED); - assert(options[ABBREVIATE].count()==0); - Parser parse; - assert(!parse.error()); - - parse.parse(multi_usage, count(multi1), multi1, options, buffer, 4, true); - assert(!parse.error()); - assert(parse.optionsCount() == 5); - assert(parse.nonOptionsCount() == 1); - assert(eq(parse.nonOptions()[0],"--strangefilename")); - assert(options[FOO].last()->type() == ENABLED); - assert(eq(options[FOO].last()->name, "--enable-foo")); - assert(options[FOO].last()->arg == 0); - assert(options[UNKNOWN].count() == 2); - assert(eq(options[UNKNOWN].first()->name,"--unknown1")); - assert(eq(options[UNKNOWN].last()->name,"u")); - assert(options[UNKNOWN].first()->arg == 0); - assert(options[UNKNOWN].last()->arg == 0); - assert(options[VERBOSE].count()==1); - assert(options[VERBOSE].arg==0); - assert(options[VERBOSE].name[0] == 'v' && options[VERBOSE].namelen == 1); - assert(eq(options[X].arg,"xyzzy")); - assert(eq(options[X].name,"X")); - - parse.parse(multi_usage, count(multi2), multi2, options, buffer, 4, true); - assert(!parse.error()); - assert(parse.optionsCount() == 13); - assert(parse.nonOptionsCount() == 1); - assert(eq(parse.nonOptions()[0],"--strangefilename")); - assert(options[FOO].last()->type() == DISABLED); - assert(options[FOO].last()->arg == 0); - assert(options[UNKNOWN].count() == 2); - assert(eq(options[UNKNOWN].first()->name,"--unknown1")); - assert(eq(options[UNKNOWN].last()->name,"u")); - assert(options[VERBOSE].count()==4); - assert(options[X].count()==5); - const char* Xargs[] = { "xyzzy", "foo", "bar", "foobar", "", "sentinel" }; - const char** Xarg = &Xargs[0]; - for (Option* Xiter = options[X]; Xiter != 0; Xiter = Xiter->next()) - assert(eq(Xiter->arg, *Xarg++)); - - assert(!options[ABBREVIATE]); - parse.parse(multi_usage, count(multi3), multi3, options, buffer, 4, true); - assert(!parse.error()); - assert(parse.optionsCount() == 21); - assert(parse.nonOptionsCount() == 2); - assert(eq(parse.nonOptions()[0],"nonoption1")); - assert(eq(parse.nonOptions()[1],"nonoption2")); - assert(options[ABBREVIATE]); - assert(options[EMPTY].count()==3); - assert(options[EMPTY].first()->arg==0); - assert(eq(options[EMPTY].last()->arg,"")); - assert(eq(options[EMPTY].last()->prev()->arg,"")); - assert(options[FOO].last()->type() == DISABLED); - assert(options[UNKNOWN].count() == 5); - assert(eq(options[UNKNOWN].first()->name,"--unknown1")); - assert(options[UNKNOWN].first()->arg == 0); - assert(eq(options[UNKNOWN].last()->name,"b")); - assert(options[VERBOSE].count()==5); - assert(options[X].count()==5); - Xarg = &Xargs[0]; - for (Option* Xiter = options[X]; Xiter != 0; Xiter = Xiter->next()) - assert(eq(Xiter->arg, *Xarg++)); - - for (Option* opt = buffer[0]; *opt; ++opt) - if (opt->desc->check_arg != Arg::Required && opt->desc->check_arg != Arg::Empty) - assert(opt->arg == 0); - } - { - Option buffer[2]; - Option options[20]; - Parser parse; - assert(!parse.error()); - parse.parse(multi_usage, -1, illegal, options, buffer, 0, false, 2); - assert(parse.error()); - } - { - Stats stats(multi_usage, count(multi3), multi3, 0, true); - const int bufmax = 3; - Option buffer[bufmax]; - Option options[stats.options_max]; - assert(!options[ABBREVIATE]); - Parser parse(multi_usage, count(multi3), multi3, options, buffer, 4, true, bufmax); - assert(!parse.error()); - assert(parse.optionsCount() == bufmax); - assert(parse.nonOptionsCount() == 2); - assert(eq(parse.nonOptions()[0],"nonoption1")); - assert(eq(parse.nonOptions()[1],"nonoption2")); - assert(options[ABBREVIATE]); - assert(options[UNKNOWN].count() == 2); // because of buxmax the 2nd 'b' cannot be stored - assert(options[UNKNOWN].first()->name[0] == 'a' && options[UNKNOWN].first()->namelen == 1); - assert(options[UNKNOWN].first()->arg == 0); - assert(eq(options[UNKNOWN].last()->name,"bb")); - } - { - Stats stats(true, multi_usage, -1, reorder); - Option buffer[stats.buffer_max]; - Option options[stats.options_max]; - Parser parse(true, multi_usage, -1, reorder, options, buffer); - assert(!parse.error()); - assert(parse.optionsCount() == 3); - assert(parse.nonOptionsCount() == 4); - assert(parse.nonOptions() == &reorder[6]); - } - { - Option buffer[10]; - Option options[10]; - Parser parse(true, multi_usage, 666, reorder2, options, buffer, 0, false, 10); - assert(!parse.error()); - assert(parse.optionsCount() == 2); - assert(parse.nonOptionsCount() == 2); - } - - fprintf(stdout, "All tests passed.\n"); - return 0; -} - diff --git a/third_party/optionparser-1.4/src/testprintusage.cpp b/third_party/optionparser-1.4/src/testprintusage.cpp deleted file mode 100644 index f9c0cd08..00000000 --- a/third_party/optionparser-1.4/src/testprintusage.cpp +++ /dev/null @@ -1,167 +0,0 @@ -/* Written 2012 by Matthias S. Benkmann - * - * The author hereby waives all copyright and related rights to the contents - * of this example file (testprintusage.cpp) to the extent possible under the law. - */ - -/** - * @file - * @brief Test program for the option::printUsage() function. - * - * @note - * This program is for developing TLMC++OP. It is neither an example nor a functionality test. - * Do not worry if it doesn't compile or run on your platform. - */ - -#include -#include -#include -#include - -#include "optionparser.h" - -using namespace std; -using option::Descriptor; -using option::Arg; - -const Descriptor test_vtabs[] = { - {0,0,"","",Arg::None, "Cölüümn 1 line ı\vColumn 1 line 2\vColumn 1 line 3 \t\vColumn 2 line 2 \tColumn 3 line 1\v\vColumn 3 line 3 "}, - {0,0,0,0,0,0} -}; - -const Descriptor test_columns[] = { - {0,0,"","",Arg::None, "Column 1 line 1 \t\tColumn 3 line 1\n" - "Column 1 line 2 \tColumn 2 line 2 \tColumn 3 line 2\n" - "Column 1 line 3 \t\tColumn 3 line 3" }, - {0,0,0,0,0,0} -}; - -const Descriptor test_column1[] = { - {0,0,"","",Arg::None, "11 \t21\v22\v23\t 31\nxx" }, - {0,0,0,0,0,0} -}; - - -const Descriptor test_tables[] = { - {0,0,"","",Arg::None,0}, // table break - {0,0,"","",Arg::None,0}, // table break - {0,0,"","",Arg::None, "Each table has its own column widths and is not aligned with other tables."}, - {0,0,"","",Arg::None, "Table 1 Column 1 Line 1 \tTable 1 Column 2 Line 1 \tTable 1 Column 3 Line 1\n" - "Table 1 Col 1 Line 2 \tTable 1 Col 2 Line 2 \tTable 1 Col 3 Line 2" - }, - {0,0,"","",Arg::None, "Table 1 Col 1 Line 3 \tTable 1 Col 2 Line 3 \tTable 1 Column 3 Line 3\n" - "Table 1 Col 1 Line 4 \tTable 1 Column 2 Line 4 \tTable 1 Column 3 Line 4" - }, - {0,0,"","",Arg::None,0}, // table break - {0,0,"","",Arg::None,0}, // table break - {0,0,"","",Arg::None, "This is the only line of table 2." }, - {0,0,"","",Arg::None,0}, // table break - {0,0,"","",Arg::None, "This is the very long 1st line of table 3. It is more than 80 characters in length and therefore needs to be wrapped. In fact it is so long that it needs to be wrapped multiple times to fit into a normal 80 characters terminal.\v" - "This is the very long 2nd line of table 3. It is more than 80 characters in length and therefore needs to be wrapped. In fact it is so long that it needs to be wrapped multiple times to fit into a normal 80 characters terminal.\v" - "This is a reasonably sized line 3 of table 3." - }, - {0,0,"","",Arg::None,0}, // table break - {0,0,"","",Arg::None, "Table 4:\n" - " \tTable 4 C 1 L 1 \tTable 4 C 2 L 1 \tTable 4 C 3 L 1\n" - "\tTable 4 C 1 L 2 \tTable 4 C 2 L 2 \tTable 4 C 3 L 2" - }, - {0,0,"","",Arg::None,0}, // table break - {0,0,"","",Arg::None, "This is the only line of table 5"}, - {0,0,"","",Arg::None,0}, // table break - {0,0,"","",Arg::None, "Table 6 C 1 L 1 \tTable 6 C 2 L 1 \tTable 6 C 3 L 1\n" - "Table 6 C 1 L 2 \tTable 6 C 2 L 2 \tTable 6 C 3 L 2" - }, - {0,0,"","",Arg::None,0 }, // table break - {0,0,"","",Arg::None, "Table 7 Column 1 Line 1 \tTable 7 Column 2 Line 1 \tTable 7 Column 3 Line 1\n" - "Table 7 Column 1 Line 2 \tTable 7 Column 2 Line 2 \tTable 7 Column 3 Line 2\n" - }, - {0,0,0,0,0,0} -}; - -const Descriptor test_nohelp[] = { - {0,0,"","",Arg::None, 0 }, - {0,0,"","",Arg::None, 0 }, - {0,0,"","",Arg::None, 0 }, - {0,0,0,0,0,0} -}; - -const Descriptor test_wide[] = { - {0,0,"","",Arg::None, "Roma\t|x漢" }, - {0,0,"","",Arg::None, "ｶﾀｶﾅ\t|漢字" }, - {0,0,"","",Arg::None, "漢字\t|漢ｶ " }, - {0,0,"","",Arg::None, "漢字\t|ｶﾅ 漢字" }, - {0,0,0,0,0,0} -}; - -const Descriptor test_overlong[] = { - {0,0,"","",Arg::None, "Good \t| Good \t| This is good." }, - {0,0,"","",Arg::None, "Good \t| This is an overlong cell. \t| This is good." }, - {0,0,"","",Arg::None, "Good \t| Good \t| This is good." }, - {0,0,0,0,0,0} -}; - -const Descriptor test_toomanycolumns[] = { - {0,0,"","",Arg::None, "This \ttable \thas \ttoo \tmany \tcolumns. \tThe \tlast \tcolumns \tare \tdiscarded." }, - {0,0,"","",Arg::None, "1\t2\t3\t4\t5\t6\t7\t8\t9\t10\t11" }, - {0,0,0,0,0,0} -}; - -const Descriptor test_ownline[] = { - {0,0,"","",Arg::None, "1234567890AB\vBA0987654321\tStarts on its own line and is indented somewhat.\vThis one, too." }, - {0,0,0,0,0,0} -}; - -const Descriptor test_overflow[] = { - {0,0,"","",Arg::None, "漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字" }, - {0,0,0,0,0,0} -}; - -void stderr_write(const char* str, int size) -{ - fwrite(str, size, 1, stderr); -} - -struct stderr_writer -{ - void write(const char* buf, size_t size) const - { - ::write(2, buf, size); - } -}; - -struct stderr_write_functor -{ - void operator()(const char* buf, size_t size) - { - ::write(2, buf, size); - } -}; - -int main() -{ - fputs("---------------------------------------------------------------\n",stderr); - option::printUsage(stderr_write, test_overflow, 1); - fputs("---------------------------------------------------------------\n",stderr); - option::printUsage(stderr_write, test_vtabs); - fputs("---------------------------------------------------------------\n",stderr); - option::printUsage(stderr_writer(), test_columns); - fputs("---------------------------------------------------------------\n",stderr); - option::printUsage(write, 2, test_column1); - fputs("---------------------------------------------------------------\n",stderr); - option::printUsage(cerr, test_tables); - fputs("---------------------------------------------------------------\n",stderr); - option::printUsage(fwrite, stderr, test_nohelp); - fputs("---------------------------------------------------------------\n",stderr); - ostringstream sst; - option::printUsage(sst, test_wide, 8); - cerr< Date: Mon, 22 Aug 2022 13:56:39 -0500 Subject: [PATCH 2/2] Revert "optionparser1.4->1.7. Makefile.am adjustments to pick up the updated library. Passes all tests." This reverts commit 4e2df3d5f77ddaaa5bcba78714125dae0c806c70. --- src/Makefile.am | 2 +- third_party/Makefile.am | 26 +- third_party/optionparser-1.4/Doxyfile | 1781 +++++++++++ .../optionparser-1.4/DoxygenLayout.xml | 193 ++ third_party/optionparser-1.4/README_ARGC_ARGV | 48 + third_party/optionparser-1.4/src/Makefile | 53 + third_party/optionparser-1.4/src/example.cpp | 56 + .../optionparser-1.4/src/example_arg.cc | 160 + .../optionparser-1.4/src/optionparser.h | 2823 +++++++++++++++++ third_party/optionparser-1.4/src/printUsage.h | 11 + third_party/optionparser-1.4/src/testodr1.cc | 50 + third_party/optionparser-1.4/src/testodr2.cc | 39 + .../optionparser-1.4/src/testparse.cpp | 368 +++ .../optionparser-1.4/src/testprintusage.cpp | 167 + 14 files changed, 5762 insertions(+), 15 deletions(-) create mode 100644 third_party/optionparser-1.4/Doxyfile create mode 100644 third_party/optionparser-1.4/DoxygenLayout.xml create mode 100644 third_party/optionparser-1.4/README_ARGC_ARGV create mode 100644 third_party/optionparser-1.4/src/Makefile create mode 100644 third_party/optionparser-1.4/src/example.cpp create mode 100644 third_party/optionparser-1.4/src/example_arg.cc create mode 100644 third_party/optionparser-1.4/src/optionparser.h create mode 100644 third_party/optionparser-1.4/src/printUsage.h create mode 100644 third_party/optionparser-1.4/src/testodr1.cc create mode 100644 third_party/optionparser-1.4/src/testodr2.cc create mode 100644 third_party/optionparser-1.4/src/testparse.cpp create mode 100644 third_party/optionparser-1.4/src/testprintusage.cpp diff --git a/src/Makefile.am b/src/Makefile.am index b5ad478c..64d5ca27 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -44,7 +44,7 @@ libsrc_la_SOURCES = \ sync_queue_impl_selector.h \ TypeManager.cpp TypeManager.h -libsrc_la_CPPFLAGS = -I $(srcdir)/../third_party/optionparser-1.7/src $(AM_CPPFLAGS) +libsrc_la_CPPFLAGS = -I $(srcdir)/../third_party/optionparser-1.4/src $(AM_CPPFLAGS) libsrc_la_CFLAGS = $(AM_CFLAGS) $(PCRE_CFLAGS) $(PCRE2_CFLAGS) libsrc_la_CXXFLAGS = $(AM_CXXFLAGS) $(PCRE_CFLAGS) $(PCRE2_CFLAGS) libsrc_la_LIBADD = diff --git a/third_party/Makefile.am b/third_party/Makefile.am index e01f798b..18e30303 100644 --- a/third_party/Makefile.am +++ b/third_party/Makefile.am @@ -50,22 +50,20 @@ check_LTLIBRARIES = ### The Lean Mean C++ Option Parser ### -LMCPPOP_RELEASE_NO = 1.7 - # This is a header-only library. We just need to rig things up so it gets distributed. EXTRA_DIST += \ - optionparser-$(LMCPPOP_RELEASE_NO)/DoxygenLayout.xml \ - optionparser-$(LMCPPOP_RELEASE_NO)/README_ARGC_ARGV \ - optionparser-$(LMCPPOP_RELEASE_NO)/src/printUsage.h \ - optionparser-$(LMCPPOP_RELEASE_NO)/src/example.cpp \ - optionparser-$(LMCPPOP_RELEASE_NO)/src/testodr1.cc \ - optionparser-$(LMCPPOP_RELEASE_NO)/src/testprintusage.cpp \ - optionparser-$(LMCPPOP_RELEASE_NO)/src/example_arg.cc \ - optionparser-$(LMCPPOP_RELEASE_NO)/src/testodr2.cc \ - optionparser-$(LMCPPOP_RELEASE_NO)/src/testparse.cpp \ - optionparser-$(LMCPPOP_RELEASE_NO)/src/Makefile \ - optionparser-$(LMCPPOP_RELEASE_NO)/src/optionparser.h \ - optionparser-$(LMCPPOP_RELEASE_NO)/Doxyfile + optionparser-1.4/DoxygenLayout.xml \ + optionparser-1.4/README_ARGC_ARGV \ + optionparser-1.4/src/printUsage.h \ + optionparser-1.4/src/example.cpp \ + optionparser-1.4/src/testodr1.cc \ + optionparser-1.4/src/testprintusage.cpp \ + optionparser-1.4/src/example_arg.cc \ + optionparser-1.4/src/testodr2.cc \ + optionparser-1.4/src/testparse.cpp \ + optionparser-1.4/src/Makefile \ + optionparser-1.4/src/optionparser.h \ + optionparser-1.4/Doxyfile ### ### Google Test diff --git a/third_party/optionparser-1.4/Doxyfile b/third_party/optionparser-1.4/Doxyfile new file mode 100644 index 00000000..02a8f14e --- /dev/null +++ b/third_party/optionparser-1.4/Doxyfile @@ -0,0 +1,1781 @@ +# Doxyfile 1.7.6.1 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. +# +# All text after a hash (#) is considered a comment and will be ignored. +# The format is: +# TAG = value [value, ...] +# For lists items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (" "). + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# http://www.gnu.org/software/libiconv for the list of possible encodings. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or sequence of words) that should +# identify the project. Note that if you do not use Doxywizard you need +# to put quotes around the project name if it contains spaces. + +PROJECT_NAME = "The Lean Mean C++ Option Parser" + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or +# if some version control system is used. + +PROJECT_NUMBER = + +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer +# a quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify an logo or icon that is +# included in the documentation. The maximum height of the logo should not +# exceed 55 pixels and the maximum width should not exceed 200 pixels. +# Doxygen will copy the logo to the output directory. + +PROJECT_LOGO = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location +# where doxygen was started. If left blank the current directory will be used. + +OUTPUT_DIRECTORY = + +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create +# 4096 sub-directories (in 2 levels) under the output directory of each output +# format and will distribute the generated files over these directories. +# Enabling this option can be useful when feeding doxygen a huge amount of +# source files, where putting all generated files in the same directory would +# otherwise cause performance problems for the file system. + +CREATE_SUBDIRS = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, +# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, +# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English +# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, +# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, +# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. + +OUTPUT_LANGUAGE = English + +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). +# Set to NO to disable this. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator +# that is used to form the text in various listings. Each string +# in this list, if found as the leading text of the brief description, will be +# stripped from the text and the result after processing the whole list, is +# used as the annotated text. Otherwise, the brief description is used as-is. +# If left blank, the following values are used ("$name" is automatically +# replaced with the name of the entity): "The $name class" "The $name widget" +# "The $name file" "is" "provides" "specifies" "contains" +# "represents" "a" "an" "the" + +ABBREVIATE_BRIEF = + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief +# description. + +ALWAYS_DETAILED_SEC = YES + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set +# to NO the shortest path that makes the file name unique will be used. + +FULL_PATH_NAMES = YES + +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user-defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the +# path to strip. + +STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of +# the path mentioned in the documentation of a class, which tells +# the reader which header file to include in order to use a class. +# If left blank only the name of the header file containing the class +# definition is used. Otherwise one should specify the include paths that +# are normally passed to the compiler using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful if your file system +# doesn't support long names like on DOS, Mac, or CD-ROM. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like regular Qt-style comments +# (thus requiring an explicit @brief command for a brief description.) + +JAVADOC_AUTOBRIEF = NO + +# If the QT_AUTOBRIEF tag is set to YES then Doxygen will +# interpret the first line (until the first dot) of a Qt-style +# comment as the brief description. If set to NO, the comments +# will behave just like regular Qt-style comments (thus requiring +# an explicit \brief command for a brief description.) + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed +# description. Set this tag to YES if you prefer the old behaviour instead. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it +# re-implements. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce +# a new page for each member. If set to NO, the documentation of a member will +# be part of the file/class/namespace that contains it. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# Doxygen uses this value to replace tabs by spaces in code fragments. + +TAB_SIZE = 8 + +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# will result in a user-defined paragraph with heading "Side Effects:". +# You can put \n's in the value part of an alias to insert newlines. + +ALIASES = + +# This tag can be used to specify a number of word-keyword mappings (TCL only). +# A mapping has the form "name=value". For example adding +# "class=itcl::class" will allow you to use the command class in the +# itcl::class meaning. + +TCL_SUBST = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C +# sources only. Doxygen will then generate output that is more tailored for C. +# For instance, some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = NO + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java +# sources only. Doxygen will then generate output that is more tailored for +# Java. For instance, namespaces will be presented as packages, qualified +# scopes will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources only. Doxygen will then generate output that is more tailored for +# Fortran. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for +# VHDL. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given extension. +# Doxygen has a built-in mapping, but you can override or extend it using this +# tag. The format is ext=language, where ext is a file extension, and language +# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, +# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make +# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C +# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions +# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. + +EXTENSION_MAPPING = + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should +# set this tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. +# func(std::string) {}). This also makes the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. +# Doxygen will parse them like normal C++ but will assume all classes use public +# instead of private inheritance when no explicit protection keyword is present. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate getter +# and setter methods for a property. Setting this option to YES (the default) +# will make doxygen replace the get and set methods by a property in the +# documentation. This will only work if the methods are indeed getting or +# setting a simple type. If this is not the case, or you want to show the +# methods anyway, you should set this option to NO. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES (the default) to allow class member groups of +# the same type (for instance a group of public functions) to be put as a +# subgroup of that type (e.g. under the Public Functions section). Set it to +# NO to prevent subgrouping. Alternatively, this can be done per class using +# the \nosubgrouping command. + +SUBGROUPING = YES + +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and +# unions are shown inside the group in which they are included (e.g. using +# @ingroup) instead of on a separate page (for HTML and Man pages) or +# section (for LaTeX and RTF). + +INLINE_GROUPED_CLASSES = NO + +# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and +# unions with only public data fields will be shown inline in the documentation +# of the scope in which they are defined (i.e. file, namespace, or group +# documentation), provided this scope is documented. If set to NO (the default), +# structs, classes, and unions are shown on a separate page (for HTML and Man +# pages) or section (for LaTeX and RTF). + +INLINE_SIMPLE_STRUCTS = NO + +# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum +# is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically +# be useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. + +TYPEDEF_HIDES_STRUCT = NO + +# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to +# determine which symbols to keep in memory and which to flush to disk. +# When the cache is full, less often used symbols will be written to disk. +# For small to medium size projects (<1000 input files) the default value is +# probably good enough. For larger projects a too small cache size can cause +# doxygen to be busy swapping symbols to and from disk most of the time +# causing a significant performance penalty. +# If the system has enough physical memory increasing the cache will improve the +# performance by keeping more symbols in memory. Note that the value works on +# a logarithmic scale so increasing the size by one will roughly double the +# memory usage. The cache size is given by this formula: +# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, +# corresponding to a cache size of 2^16 = 65536 symbols. + +SYMBOL_CACHE_SIZE = 0 + +# Similar to the SYMBOL_CACHE_SIZE the size of the symbol lookup cache can be +# set using LOOKUP_CACHE_SIZE. This cache is used to resolve symbols given +# their name and scope. Since this can be an expensive process and often the +# same symbol appear multiple times in the code, doxygen keeps a cache of +# pre-resolved symbols. If the cache is too small doxygen will become slower. +# If the cache is too large, memory is wasted. The cache size is given by this +# formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range is 0..9, the default is 0, +# corresponding to a cache size of 2^16 = 65536 symbols. + +LOOKUP_CACHE_SIZE = 0 + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = NO + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + +EXTRACT_PRIVATE = YES + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + +EXTRACT_STATIC = NO + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = NO + +# This flag is only useful for Objective-C code. When set to YES local +# methods, which are defined in the implementation section but not in +# the interface are included in the documentation. +# If set to NO (the default) only methods in the interface are included. + +EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base +# name of the file that contains the anonymous namespace. By default +# anonymous namespaces are hidden. + +EXTRACT_ANON_NSPACES = YES + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. +# This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_MEMBERS = YES + +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these classes will be included in the various +# overviews. This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_CLASSES = YES + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the +# documentation. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any +# documentation blocks found inside the body of a function. +# If set to NO (the default) these blocks will be appended to the +# function's detailed documentation block. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. +# Set it to YES to include the internal documentation. + +INTERNAL_DOCS = YES + +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the +# documentation. If set to YES the scope will be hidden. + +HIDE_SCOPE_NAMES = YES + +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put a list of the files that are included by a file in the documentation +# of that file. + +SHOW_INCLUDE_FILES = NO + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen +# will list include files with double quotes in the documentation +# rather than with sharp brackets. + +FORCE_LOCAL_INCLUDES = YES + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# is inserted in the documentation for inline members. + +INLINE_INFO = NO + +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in +# declaration order. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the +# brief documentation of file, namespace and class members alphabetically +# by member name. If set to NO (the default) the members will appear in +# declaration order. + +SORT_BRIEF_DOCS = NO + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen +# will sort the (brief and detailed) documentation of class members so that +# constructors and destructors are listed first. If set to NO (the default) +# the constructors will appear in the respective orders defined by +# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. +# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO +# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the +# hierarchy of group names into alphabetical order. If set to NO (the default) +# the group names will appear in their defined order. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be +# sorted by fully-qualified names, including namespaces. If set to +# NO (the default), the class list will be sorted only by class name, +# not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the +# alphabetical list. + +SORT_BY_SCOPE_NAME = NO + +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to +# do proper type resolution of all parameters of a function it will reject a +# match between the prototype and the implementation of a member function even +# if there is only one candidate or it is obvious which candidate to choose +# by doing a simple string match. By disabling STRICT_PROTO_MATCHING doxygen +# will still accept a match between prototype and implementation in such cases. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo +# commands in the documentation. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test +# commands in the documentation. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug +# commands in the documentation. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting +# \deprecated commands in the documentation. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional +# documentation sections, marked by \if sectionname ... \endif. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or macro consists of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and macros in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the +# list will mention the files that were used to generate the documentation. + +SHOW_USED_FILES = YES + +# If the sources in your project are distributed over multiple directories +# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy +# in the documentation. The default is NO. + +SHOW_DIRECTORIES = NO + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. +# This will remove the Files entry from the Quick Index and from the +# Folder Tree View (if specified). The default is YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the +# Namespaces page. +# This will remove the Namespaces entry from the Quick Index +# and from the Folder Tree View (if specified). The default is YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command , where is the value of +# the FILE_VERSION_FILTER tag, and is the name of an input file +# provided by doxygen. Whatever the program writes to standard output +# is used as the file version. See the manual for examples. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. The create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. +# You can optionally specify a file name after the option, if omitted +# DoxygenLayout.xml will be used as the name of the layout file. + +LAYOUT_FILE = DoxygenLayout.xml + +# The CITE_BIB_FILES tag can be used to specify one or more bib files +# containing the references data. This must be a list of .bib files. The +# .bib extension is automatically appended if omitted. Using this command +# requires the bibtex tool to be installed. See also +# http://en.wikipedia.org/wiki/BibTeX for more info. For LaTeX the style +# of the bibliography can be controlled using LATEX_BIB_STYLE. To use this +# feature you need bibtex and perl available in the search path. + +CITE_BIB_FILES = + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated +# by doxygen. Possible values are YES and NO. If left blank NO is used. + +QUIET = YES + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank +# NO is used. + +WARNINGS = YES + +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# automatically be disabled. + +WARN_IF_UNDOCUMENTED = YES + +# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some +# parameters in a documented function, or documenting parameters that +# don't exist or using markup commands wrongly. + +WARN_IF_DOC_ERROR = YES + +# The WARN_NO_PARAMDOC option can be enabled to get warnings for +# functions that are documented, but have no documentation for their parameters +# or return value. If set to NO (the default) doxygen will only warn about +# wrong or incomplete parameter documentation, but not about the absence of +# documentation. + +WARN_NO_PARAMDOC = NO + +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. Optionally the format may contain +# $version, which will be replaced by the version of the file (if it could +# be obtained via FILE_VERSION_FILTER) + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written +# to stderr. + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = src/ + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is +# also the default input encoding. Doxygen uses libiconv (or the iconv built +# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for +# the list of possible encodings. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh +# *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py +# *.f90 *.f *.for *.vhd *.vhdl + +FILE_PATTERNS = + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = NO + +# The EXCLUDE tag can be used to specify files and/or directories that should be +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. +# Note that relative paths are relative to the directory from which doxygen is +# run. + +EXCLUDE = + +# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded +# from the input. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. Note that the wildcards are matched +# against the file with absolute path, so to exclude all test directories +# for example use the pattern */test/* + +EXCLUDE_PATTERNS = + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test + +EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see +# the \include command). + +EXAMPLE_PATH = src/ + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank all files are included. + +EXAMPLE_PATTERNS = example* + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. +# Possible values are YES and NO. If left blank NO is used. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see +# the \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command , where +# is the value of the INPUT_FILTER tag, and is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. +# If FILTER_PATTERNS is specified, this tag will be +# ignored. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. +# Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. +# The filters are a list of the form: +# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further +# info on how filters are used. If FILTER_PATTERNS is empty or if +# non of the patterns match the file name, INPUT_FILTER is applied. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source +# files to browse (i.e. when SOURCE_BROWSER is set to YES). + +FILTER_SOURCE_FILES = NO + +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) +# and it is also possible to disable source filtering for a specific pattern +# using *.ext= (so without naming a filter). This option only has effect when +# FILTER_SOURCE_FILES is enabled. + +FILTER_SOURCE_PATTERNS = + +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. +# Note: To get rid of all source code in the generated output, make sure also +# VERBATIM_HEADERS is set to NO. + +SOURCE_BROWSER = YES + +# Setting the INLINE_SOURCES tag to YES will include the body +# of functions and classes directly in the documentation. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code +# fragments. Normal C and C++ comments will always remain visible. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES +# then for each documented function all documented +# functions referencing it will be listed. + +REFERENCED_BY_RELATION = NO + +# If the REFERENCES_RELATION tag is set to YES +# then for each documented function all documented entities +# called/used by that function will be listed. + +REFERENCES_RELATION = NO + +# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) +# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from +# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will +# link to the source code. +# Otherwise they will link to the documentation. + +REFERENCES_LINK_SOURCE = YES + +# If the USE_HTAGS tag is set to YES then the references to source code +# will point to the HTML generated by the htags(1) tool instead of doxygen +# built-in source browser. The htags tool is part of GNU's global source +# tagging system (see http://www.gnu.org/software/global/global.html). You +# will need version 4.8.6 or higher. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for +# which an include is specified. Set to NO to disable this. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project +# contains a lot of classes, structs, unions or interfaces. + +ALPHABETICAL_INDEX = NO + +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# in which this list will be split (can be a number in the range [1..20]) + +COLS_IN_ALPHA_INDEX = 5 + +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# should be ignored while generating the index headers. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# generate HTML output. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `html' will be used as the default path. + +HTML_OUTPUT = html-dev + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a +# standard header. Note that when using a custom header you are responsible +# for the proper inclusion of any scripts and style sheets that doxygen +# needs, which is dependent on the configuration options used. +# It is advised to generate a default header using "doxygen -w html +# header.html footer.html stylesheet.css YourConfigFile" and then modify +# that header. Note that the header is subject to change so you typically +# have to redo this when upgrading to a newer version of doxygen or when +# changing the value of configuration settings such as GENERATE_TREEVIEW! + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a +# standard footer. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If the tag is left blank doxygen +# will generate a default style sheet. Note that doxygen will try to copy +# the style sheet file to the HTML output directory, so don't put your own +# style sheet in the HTML output directory as well, or it will be erased! + +HTML_STYLESHEET = + +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath$ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that +# the files will be copied as-is; there are no commands or markers available. + +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. +# Doxygen will adjust the colors in the style sheet and background images +# according to this color. Hue is specified as an angle on a colorwheel, +# see http://en.wikipedia.org/wiki/Hue for more information. +# For instance the value 0 represents red, 60 is yellow, 120 is green, +# 180 is cyan, 240 is blue, 300 purple, and 360 is red again. +# The allowed range is 0 to 359. + +HTML_COLORSTYLE_HUE = 120 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of +# the colors in the HTML output. For a value of 0 the output will use +# grayscales only. A value of 255 will produce the most vivid colors. + +HTML_COLORSTYLE_SAT = 150 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to +# the luminance component of the colors in the HTML output. Values below +# 100 gradually make the output lighter, whereas values above 100 make +# the output darker. The value divided by 100 is the actual gamma applied, +# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, +# and 100 does not change the gamma. + +HTML_COLORSTYLE_GAMMA = 170 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting +# this to NO can help when comparing the output of multiple runs. + +HTML_TIMESTAMP = YES + +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, +# files or namespaces will be aligned in HTML using tables. If set to +# NO a bullet list will be used. + +HTML_ALIGN_MEMBERS = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. For this to work a browser that supports +# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox +# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). + +HTML_DYNAMIC_SECTIONS = NO + +# If the GENERATE_DOCSET tag is set to YES, additional index files +# will be generated that can be used as input for Apple's Xcode 3 +# integrated development environment, introduced with OSX 10.5 (Leopard). +# To create a documentation set, doxygen will generate a Makefile in the +# HTML output directory. Running make will produce the docset in that +# directory and running "make install" will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find +# it at startup. +# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. + +GENERATE_DOCSET = NO + +# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the +# feed. A documentation feed provides an umbrella under which multiple +# documentation sets from a single provider (such as a company or product suite) +# can be grouped. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that +# should uniquely identify the documentation set bundle. This should be a +# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen +# will append .docset to the name. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) +# of the generated HTML documentation. + +GENERATE_HTMLHELP = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be +# written to the html output directory. + +CHM_FILE = + +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run +# the HTML help compiler on the generated index.hhp. + +HHC_LOCATION = + +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that +# it should be included in the master .chm file (NO). + +GENERATE_CHI = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING +# is used to encode HtmlHelp index (hhk), content (hhc) and project file +# content. + +CHM_INDEX_ENCODING = + +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a +# normal table of contents (NO) in the .chm file. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members +# to the contents of the HTML help documentation and to the tree view. + +TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated +# that can be used as input for Qt's qhelpgenerator to generate a +# Qt Compressed Help (.qch) of the generated HTML documentation. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can +# be used to specify the file name of the resulting .qch file. +# The path specified is relative to the HTML output folder. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#namespace + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#virtual-folders + +QHP_VIRTUAL_FOLDER = doc + +# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to +# add. For more information please see +# http://doc.trolltech.com/qthelpproject.html#custom-filters + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see +# +# Qt Help Project / Custom Filters. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's +# filter section matches. +# +# Qt Help Project / Filter Attributes. + +QHP_SECT_FILTER_ATTRS = + +# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can +# be used to specify the location of Qt's qhelpgenerator. +# If non-empty doxygen will try to run qhelpgenerator on the generated +# .qhp file. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files +# will be generated, which together with the HTML files, form an Eclipse help +# plugin. To install this plugin and make it available under the help contents +# menu in Eclipse, the contents of the directory containing the HTML and XML +# files needs to be copied into the plugins directory of eclipse. The name of +# the directory within the plugins directory should be the same as +# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before +# the help appears. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have +# this name. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) +# at top of each HTML page. The value NO (the default) enables the index and +# the value YES disables it. Since the tabs have the same information as the +# navigation tree you can set this option to NO if you already set +# GENERATE_TREEVIEW to YES. + +DISABLE_INDEX = NO + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. +# If the tag value is set to YES, a side panel will be generated +# containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). +# Windows users are probably better off using the HTML help feature. +# Since the tree basically has the same information as the tab index you +# could consider to set DISABLE_INDEX to NO when enabling this option. + +GENERATE_TREEVIEW = NO + +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values +# (range [0,1..20]) that doxygen will group on one line in the generated HTML +# documentation. Note that a value of 0 will completely suppress the enum +# values from appearing in the overview section. + +ENUM_VALUES_PER_LINE = 4 + +# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, +# and Class Hierarchy pages using a tree view instead of an ordered list. + +USE_INLINE_TREES = NO + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree +# is shown. + +TREEVIEW_WIDTH = 250 + +# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open +# links to external symbols imported via tag files in a separate window. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of Latex formulas included +# as images in the HTML documentation. The default is 10. Note that +# when you change the font size after a successful doxygen run you need +# to manually remove any form_*.png images from the HTML output directory +# to force them to be regenerated. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are +# not supported properly for IE 6.0, but are supported on all modern browsers. +# Note that when changing this option you need to delete any form_*.png files +# in the HTML output before the changes have effect. + +FORMULA_TRANSPARENT = YES + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax +# (see http://www.mathjax.org) which uses client side Javascript for the +# rendering instead of using prerendered bitmaps. Use this if you do not +# have LaTeX installed or if you want to formulas look prettier in the HTML +# output. When enabled you also need to install MathJax separately and +# configure the path to it using the MATHJAX_RELPATH option. + +USE_MATHJAX = NO + +# When MathJax is enabled you need to specify the location relative to the +# HTML output directory using the MATHJAX_RELPATH option. The destination +# directory should contain the MathJax.js script. For instance, if the mathjax +# directory is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to the +# mathjax.org site, so you can quickly see the result without installing +# MathJax, but it is strongly recommended to install a local copy of MathJax +# before deployment. + +MATHJAX_RELPATH = http://www.mathjax.org/mathjax + +# The MATHJAX_EXTENSIONS tag can be used to specify one or MathJax extension +# names that should be enabled during MathJax rendering. + +MATHJAX_EXTENSIONS = + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box +# for the HTML output. The underlying search engine uses javascript +# and DHTML and should work on any modern browser. Note that when using +# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets +# (GENERATE_DOCSET) there is already a search function so this one should +# typically be disabled. For large projects the javascript based search engine +# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. + +SEARCHENGINE = YES + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be +# implemented using a PHP enabled web server instead of at the web client +# using Javascript. Doxygen will generate the search PHP script and index +# file to put on the web server. The advantage of the server +# based approach is that it scales better to large projects and allows +# full text search. The disadvantages are that it is more difficult to setup +# and does not have live searching capabilities. + +SERVER_BASED_SEARCH = NO + +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `latex' will be used as the default path. + +LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. If left blank `latex' will be used as the default command name. +# Note that when enabling USE_PDFLATEX this option is only used for +# generating bitmaps for formulas in the HTML output, but not in the +# Makefile that is written to the output directory. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, letter, legal and +# executive. If left blank a4wide will be used. + +PAPER_TYPE = a4 + +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# packages that should be included in the LaTeX output. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a +# standard header. Notice: only use this tag if you know what you are doing! + +LATEX_HEADER = + +# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for +# the generated latex document. The footer should contain everything after +# the last chapter. If it is left blank doxygen will generate a +# standard footer. Notice: only use this tag if you know what you are doing! + +LATEX_FOOTER = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references +# This makes the output suitable for online browsing using a pdf viewer. + +PDF_HYPERLINKS = YES + +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a +# higher quality PDF documentation. + +USE_PDFLATEX = YES + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. +# This option is also used when generating formulas in HTML. + +LATEX_BATCHMODE = NO + +# If LATEX_HIDE_INDICES is set to YES then doxygen will not +# include the index chapters (such as File Index, Compound Index, etc.) +# in the output. + +LATEX_HIDE_INDICES = NO + +# If LATEX_SOURCE_CODE is set to YES then doxygen will include +# source code with syntax highlighting in the LaTeX output. +# Note that which sources are shown also depends on other settings +# such as SOURCE_BROWSER. + +LATEX_SOURCE_CODE = NO + +# The LATEX_BIB_STYLE tag can be used to specify the style to use for the +# bibliography, e.g. plainnat, or ieeetr. The default style is "plain". See +# http://en.wikipedia.org/wiki/BibTeX for more info. + +LATEX_BIB_STYLE = plain + +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimized for Word 97 and may not look very pretty with +# other RTF readers or editors. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `rtf' will be used as the default path. + +RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. +# Note: wordpad (write) and others do not support links. + +RTF_HYPERLINKS = NO + +# Load style sheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an rtf document. +# Syntax is similar to doxygen's config file. + +RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# generate man pages + +GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `man' will be used as the default path. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to +# the generated man pages (default is the subroutine's section .3) + +MAN_EXTENSION = .3 + +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command +# would be unable to find the correct page. The default is NO. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of +# the code including all documentation. + +GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `xml' will be used as the default path. + +XML_OUTPUT = xml + +# The XML_SCHEMA tag can be used to specify an XML schema, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_SCHEMA = + +# The XML_DTD tag can be used to specify an XML DTD, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_DTD = + +# If the XML_PROGRAMLISTING tag is set to YES Doxygen will +# dump the program listings (including syntax highlighting +# and cross-referencing information) to the XML output. Note that +# enabling this will significantly increase the size of the XML output. + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES Doxygen will +# generate a Perl module file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the +# moment. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES Doxygen will generate +# the necessary Makefile rules, Perl scripts and LaTeX code to be able +# to generate PDF and DVI output from the Perl module output. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be +# nicely formatted so it can be parsed by a human reader. +# This is useful +# if you want to understand what is going on. +# On the other hand, if this +# tag is set to NO the size of the Perl module output will be much smaller +# and Perl will parse it just the same. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file +# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. +# This is useful so different doxyrules.make files included by the same +# Makefile don't overwrite each other's variables. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include +# files. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = NO + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_DEFINED tags. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# pointed to by INCLUDE_PATH will be searched when a #include is found. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will +# be used. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. To prevent a macro definition from being +# undefined via #undef or recursively expanded use the := operator +# instead of the = operator. + +PREDEFINED = + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. +# Use the PREDEFINED tag if you want to use a different macro definition that +# overrules the definition found in the source code. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all references to function-like macros +# that are alone on a line, have an all uppercase name, and do not end with a +# semicolon, because these will confuse the parser if not removed. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES option can be used to specify one or more tagfiles. +# Optionally an initial location of the external documentation +# can be added for each tagfile. The format of a tag file without +# this location is as follows: +# +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where "loc1" and "loc2" can be relative or absolute paths or +# URLs. If a location is present for each tag, the installdox tool +# does not have to be run to correct the links. +# Note that each tag file must have a unique name +# (where the name does NOT include the path) +# If a tag file is not located in the directory in which doxygen +# is run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# a tag file that is based on the input files it reads. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes +# will be listed. + +ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of `which perl'). + +PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base +# or super classes. Setting the tag to NO turns the diagrams off. Note that +# this option also works with HAVE_DOT disabled, but it is recommended to +# install and use dot, since it yields more powerful graphs. + +CLASS_DIAGRAMS = YES + +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see +# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the +# default search path. + +MSCGEN_PATH = + +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = NO + +# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is +# allowed to run in parallel. When set to 0 (the default) doxygen will +# base this on the number of processors available in the system. You can set it +# explicitly to a value larger than 0 to get control over the balance +# between CPU load and processing speed. + +DOT_NUM_THREADS = 0 + +# By default doxygen will use the Helvetica font for all dot files that +# doxygen generates. When you want a differently looking font you can specify +# the font name using DOT_FONTNAME. You need to make sure dot is able to find +# the font, which can be done by putting it in a standard location or by setting +# the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the +# directory containing the font. + +DOT_FONTNAME = Helvetica + +# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. +# The default size is 10pt. + +DOT_FONTSIZE = 10 + +# By default doxygen will tell dot to use the Helvetica font. +# If you specify a different font using DOT_FONTNAME you can use DOT_FONTPATH to +# set the path where dot can find it. + +DOT_FONTPATH = + +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the +# CLASS_DIAGRAMS tag to NO. + +CLASS_GRAPH = NO + +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and +# class references variables) of the class with other documented classes. + +COLLABORATION_GRAPH = NO + +# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for groups, showing the direct groups dependencies + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. + +UML_LOOK = NO + +# If set to YES, the inheritance and collaboration graphs will show the +# relations between templates and their instances. + +TEMPLATE_RELATIONS = NO + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with +# other documented files. + +INCLUDE_GRAPH = YES + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or +# indirectly include this file. + +INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH and HAVE_DOT options are set to YES then +# doxygen will generate a call dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable call graphs +# for selected functions only using the \callgraph command. + +CALL_GRAPH = NO + +# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then +# doxygen will generate a caller dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable caller +# graphs for selected functions only using the \callergraph command. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# will generate a graphical hierarchy of all classes instead of a textual one. + +GRAPHICAL_HIERARCHY = YES + +# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES +# then doxygen will show the dependencies a directory has on other directories +# in a graphical way. The dependency relations are determined by the #include +# relations between the files in the directories. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are svg, png, jpg, or gif. +# If left blank png will be used. If you choose svg you need to set +# HTML_FILE_EXTENSION to xhtml in order to make the SVG files +# visible in IE 9+ (other browsers do not have this requirement). + +DOT_IMAGE_FORMAT = png + +# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to +# enable generation of interactive SVG images that allow zooming and panning. +# Note that this requires a modern browser other than Internet Explorer. +# Tested and working are Firefox, Chrome, Safari, and Opera. For IE 9+ you +# need to set HTML_FILE_EXTENSION to xhtml in order to make the SVG files +# visible. Older versions of IE do not have SVG support. + +INTERACTIVE_SVG = NO + +# The tag DOT_PATH can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. + +DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the +# \dotfile command). + +DOTFILE_DIRS = + +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the +# \mscfile command). + +MSCFILE_DIRS = + +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of +# nodes that will be shown in the graph. If the number of nodes in a graph +# becomes larger than this value, doxygen will truncate the graph, which is +# visualized by representing a node as a red box. Note that doxygen if the +# number of direct children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note +# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. + +DOT_GRAPH_MAX_NODES = 50 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the +# graphs generated by dot. A depth value of 3 means that only nodes reachable +# from the root by following a path via at most 3 edges will be shown. Nodes +# that lay further from the root node will be omitted. Note that setting this +# option to 1 or 2 may greatly reduce the computation time needed for large +# code bases. Also note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. + +MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not +# seem to support this out of the box. Warning: Depending on the platform used, +# enabling this option may lead to badly anti-aliased labels on the edges of +# a graph (i.e. they become hard to read). + +DOT_TRANSPARENT = NO + +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) +# support this, this feature is disabled by default. + +DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and +# arrows in the dot generated graphs. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermediate dot files that are used to generate +# the various graphs. + +DOT_CLEANUP = YES diff --git a/third_party/optionparser-1.4/DoxygenLayout.xml b/third_party/optionparser-1.4/DoxygenLayout.xml new file mode 100644 index 00000000..474cc004 --- /dev/null +++ b/third_party/optionparser-1.4/DoxygenLayout.xml @@ -0,0 +1,193 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/third_party/optionparser-1.4/README_ARGC_ARGV b/third_party/optionparser-1.4/README_ARGC_ARGV new file mode 100644 index 00000000..c134cfa8 --- /dev/null +++ b/third_party/optionparser-1.4/README_ARGC_ARGV @@ -0,0 +1,48 @@ +POSIX Guidelines for command line arguments + +http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html + +---------------------------------------------- + +From the C standard: + +5.1.2.2.1 Program startup + +The function called at program startup is named main. The implementation declares no +prototype for this function. It shall be defined with a return type of int and with no +parameters: + + int main(void) { /* ... */ } + +or with two parameters (referred to here as argc and argv, though any names may be +used, as they are local to the function in which they are declared): + + int main(int argc, char *argv[]) { /* ... */ } + +or equivalent; or in some other implementation-defined manner. + +If they are declared, the parameters to the main function shall obey the following +constraints: + +— The value of argc shall be nonnegative. + +— argv[argc] shall be a null pointer. + +— If the value of argc is greater than zero, the array members argv[0] through + argv[argc-1] inclusive shall contain pointers to strings, which are given + implementation-defined values by the host environment prior to program startup. + The intent is to supply to the program information determined prior to program + startup from elsewhere in the hosted environment. If the host environment is + not capable of supplying strings with letters in both uppercase and lowercase, + the implementation shall ensure that the strings are received in lowercase. + +— If the value of argc is greater than zero, the string pointed to by argv[0] + represents the program name; argv[0][0] shall be the null character if the + program name is not available from the host environment. If the value of argc is + greater than one, the strings pointed to by argv[1] through argv[argc-1] + represent the program parameters. + +— The parameters argc and argv and the strings pointed to by the argv array shall + be modifiable by the program, and retain their last-stored values between program + startup and program termination. + diff --git a/third_party/optionparser-1.4/src/Makefile b/third_party/optionparser-1.4/src/Makefile new file mode 100644 index 00000000..2447e03b --- /dev/null +++ b/third_party/optionparser-1.4/src/Makefile @@ -0,0 +1,53 @@ +CXX=g++ +CXXFLAGS=-W -Wall -g -fmessage-length=0 +CCFLAGS=$(CXXFLAGS) -fno-exceptions -fno-rtti -nodefaultlibs +OPTIMIZE=-Os -fomit-frame-pointer +#OPTIMIZE=-O0 +LD=gcc # gcc automatically picks the correct crt*.o and helper libraries to link +VERSION=1.4 +PACKAGEDIR=optionparser-$(VERSION) +TARBALL=../$(PACKAGEDIR).tar.gz + +all: example_arg testparse testprintusage testodr example doc + +# .cpp files depend on the C++ standard lib +%: %.cpp optionparser.h + $(CXX) $(CXXFLAGS) $(OPTIMIZE) -o $@ $< + +# .cc files depend only on libc +%.o: %.cc optionparser.h + $(CXX) $(CCFLAGS) $(OPTIMIZE) -c $< + +%: %.cc optionparser.h + $(CXX) $(CCFLAGS) $(OPTIMIZE) -lc -o $@ $< + +testprintusage: testprintusage.cpp optionparser.h + $(CXX) $(CXXFLAGS) $(OPTIMIZE) -Wno-unused-result -o $@ $< + +# testodr needs to be linked in a separate step rather than +# just passing both .cpp files to g++, because only this way +# can we be sure that duplicate definitions cause an error message. +testodr: testodr1.o testodr2.o + $(LD) -lc -o $@ $^ + +doc: + cd .. && doxygen + cd .. && cat Doxyfile | sed '/^INTERNAL_DOCS/s/YES/NO/;/^HTML_OUTPUT/s/-dev//' | doxygen - + +clean: + rm -f testodr testodr1.o testodr2.o example.o example testprintusage testparse example_arg + rm -rf ../html ../html-dev $(PACKAGEDIR) $(TARBALL) + rm -f *~ ../*~ + +package: + rm -rf $(PACKAGEDIR) + mkdir -p $(PACKAGEDIR)/src + cp ../Doxyfile ../DoxygenLayout.xml ../README_ARGC_ARGV $(PACKAGEDIR) + cp Makefile example.cpp example_arg.cc optionparser.h \ + testodr1.cc testodr2.cc testparse.cpp testprintusage.cpp \ + printUsage.h $(PACKAGEDIR)/src + tar --owner=0 --group=0 -czf $(TARBALL) $(PACKAGEDIR) + +upload: all package + cd .. && scp -r src/optionparser.h html/* optionparser-frs:/home/project-web/optionparser/htdocs + scp $(TARBALL) optionparser-frs:/home/frs/project/o/op/optionparser diff --git a/third_party/optionparser-1.4/src/example.cpp b/third_party/optionparser-1.4/src/example.cpp new file mode 100644 index 00000000..d4dfd1df --- /dev/null +++ b/third_party/optionparser-1.4/src/example.cpp @@ -0,0 +1,56 @@ +/* Written 2012 by Matthias S. Benkmann + * + * The author hereby waives all copyright and related rights to the contents + * of this example file (example.cpp) to the extent possible under the law. + */ + +/** + * @file + * @brief Small demo of The Lean Mean C++ Option Parser. + * + * @include example.cpp + */ + +#include +#include +#include +#include "optionparser.h" + +enum optionIndex { UNKNOWN, HELP, PLUS }; +const option::Descriptor usage[] = +{ + {UNKNOWN, 0, "", "",option::Arg::None, "USAGE: example [options]\n\n" + "Options:" }, + {HELP, 0,"", "help",option::Arg::None, " --help \tPrint usage and exit." }, + {PLUS, 0,"p","plus",option::Arg::None, " --plus, -p \tIncrement count." }, + {UNKNOWN, 0, "", "",option::Arg::None, "\nExamples:\n" + " example --unknown -- --this_is_no_option\n" + " example -unk --plus -ppp file1 file2\n" }, + {0,0,0,0,0,0} +}; + +int main(int argc, char* argv[]) +{ + argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present + option::Stats stats(usage, argc, argv); + std::vector options(stats.options_max); + std::vector buffer(stats.buffer_max); + option::Parser parse(usage, argc, argv, &options[0], &buffer[0]); + + if (parse.error()) + return 1; + + if (options[HELP] || argc == 0) { + option::printUsage(std::cout, usage); + return 0; + } + + std::cout << "--plus count: " << + options[PLUS].count() << "\n"; + + for (option::Option* opt = options[UNKNOWN]; opt; opt = opt->next()) + std::cout << "Unknown option: " << std::string(opt->name,opt->namelen) << "\n"; + + for (int i = 0; i < parse.nonOptionsCount(); ++i) + std::cout << "Non-option #" << i << ": " << parse.nonOption(i) << "\n"; +} diff --git a/third_party/optionparser-1.4/src/example_arg.cc b/third_party/optionparser-1.4/src/example_arg.cc new file mode 100644 index 00000000..82886f9a --- /dev/null +++ b/third_party/optionparser-1.4/src/example_arg.cc @@ -0,0 +1,160 @@ +/* Written 2012 by Matthias S. Benkmann + * + * The author hereby waives all copyright and related rights to the contents + * of this example file (example_arg.cc) to the extent possible under the law. + */ + +/** + * @file + * @brief Demonstrates handling various types of option arguments (required, numeric,...) with + no dependency on the C++ standard library (only C lib). + * + * @include example_arg.cc + */ + +#include +#include +#include "optionparser.h" + +struct Arg: public option::Arg +{ + static void printError(const char* msg1, const option::Option& opt, const char* msg2) + { + fprintf(stderr, "%s", msg1); + fwrite(opt.name, opt.namelen, 1, stderr); + fprintf(stderr, "%s", msg2); + } + + static option::ArgStatus Unknown(const option::Option& option, bool msg) + { + if (msg) printError("Unknown option '", option, "'\n"); + return option::ARG_ILLEGAL; + } + + static option::ArgStatus Required(const option::Option& option, bool msg) + { + if (option.arg != 0) + return option::ARG_OK; + + if (msg) printError("Option '", option, "' requires an argument\n"); + return option::ARG_ILLEGAL; + } + + static option::ArgStatus NonEmpty(const option::Option& option, bool msg) + { + if (option.arg != 0 && option.arg[0] != 0) + return option::ARG_OK; + + if (msg) printError("Option '", option, "' requires a non-empty argument\n"); + return option::ARG_ILLEGAL; + } + + static option::ArgStatus Numeric(const option::Option& option, bool msg) + { + char* endptr = 0; + if (option.arg != 0 && strtol(option.arg, &endptr, 10)){}; + if (endptr != option.arg && *endptr == 0) + return option::ARG_OK; + + if (msg) printError("Option '", option, "' requires a numeric argument\n"); + return option::ARG_ILLEGAL; + } +}; + +enum optionIndex { UNKNOWN, HELP, OPTIONAL, REQUIRED, NUMERIC, NONEMPTY }; +const option::Descriptor usage[] = { +{ UNKNOWN, 0,"", "", Arg::Unknown, "USAGE: example_arg [options]\n\n" + "Options:" }, +{ HELP, 0,"", "help", Arg::None, " \t--help \tPrint usage and exit." }, +{ OPTIONAL,0,"o","optional",Arg::Optional," -o[], \t--optional[=]" + " \tTakes an argument but is happy without one." }, +{ REQUIRED,0,"r","required",Arg::Required," -r , \t--required= \tMust have an argument." }, +{ NUMERIC, 0,"n","numeric", Arg::Numeric, " -n , \t--numeric= \tRequires a number as argument." }, +{ NONEMPTY,0,"1","nonempty",Arg::NonEmpty," -1 , \t--nonempty=" + " \tCan NOT take the empty string as argument." }, +{ UNKNOWN, 0,"", "", Arg::None, + "\nExamples:\n" + " example_arg --unknown -o -n10 \n" + " example_arg -o -n10 file1 file2 \n" + " example_arg -nfoo file1 file2 \n" + " example_arg --optional -- file1 file2 \n" + " example_arg --optional file1 file2 \n" + " example_arg --optional=file1 file2 \n" + " example_arg --optional= file1 file2 \n" + " example_arg -o file1 file2 \n" + " example_arg -ofile1 file2 \n" + " example_arg -unk file1 file2 \n" + " example_arg -r -- file1 \n" + " example_arg -r file1 \n" + " example_arg --required \n" + " example_arg --required=file1 \n" + " example_arg --nonempty= file1 \n" + " example_arg --nonempty=foo --numeric=999 --optional=bla file1 \n" + " example_arg -1foo \n" + " example_arg -1 -- \n" + " example_arg -1 \"\" \n" +}, +{ 0, 0, 0, 0, 0, 0 } }; + +int main(int argc, char* argv[]) +{ + argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present + option::Stats stats(usage, argc, argv); + +#ifdef __GNUC__ + // GCC supports C99 VLAs for C++ with proper constructor calls. + option::Option options[stats.options_max], buffer[stats.buffer_max]; +#else + // use calloc() to allocate 0-initialized memory. It's not the same + // as properly constructed elements, but good enough. Obviously in an + // ordinary C++ program you'd use new[], but this file demonstrates that + // TLMC++OP can be used without any dependency on the C++ standard library. + option::Option* options = (option::Option*)calloc(stats.options_max, sizeof(option::Option)); + option::Option* buffer = (option::Option*)calloc(stats.buffer_max, sizeof(option::Option)); +#endif + + option::Parser parse(usage, argc, argv, options, buffer); + + if (parse.error()) + return 1; + + if (options[HELP] || argc == 0) + { + int columns = getenv("COLUMNS")? atoi(getenv("COLUMNS")) : 80; + option::printUsage(fwrite, stdout, usage, columns); + return 0; + } + + for (int i = 0; i < parse.optionsCount(); ++i) + { + option::Option& opt = buffer[i]; + fprintf(stdout, "Argument #%d is ", i); + switch (opt.index()) + { + case HELP: + // not possible, because handled further above and exits the program + case OPTIONAL: + if (opt.arg) + fprintf(stdout, "--optional with optional argument '%s'\n", opt.arg); + else + fprintf(stdout, "--optional without the optional argument\n"); + break; + case REQUIRED: + fprintf(stdout, "--required with argument '%s'\n", opt.arg); + break; + case NUMERIC: + fprintf(stdout, "--numeric with argument '%s'\n", opt.arg); + break; + case NONEMPTY: + fprintf(stdout, "--nonempty with argument '%s'\n", opt.arg); + break; + case UNKNOWN: + // not possible because Arg::Unknown returns ARG_ILLEGAL + // which aborts the parse with an error + break; + } + } + + for (int i = 0; i < parse.nonOptionsCount(); ++i) + fprintf(stdout, "Non-option argument #%d is %s\n", i, parse.nonOption(i)); +} diff --git a/third_party/optionparser-1.4/src/optionparser.h b/third_party/optionparser-1.4/src/optionparser.h new file mode 100644 index 00000000..d43b7dfe --- /dev/null +++ b/third_party/optionparser-1.4/src/optionparser.h @@ -0,0 +1,2823 @@ +/* + * The Lean Mean C++ Option Parser + * + * Copyright (C) 2012 Matthias S. Benkmann + * + * The "Software" in the following 2 paragraphs refers to this file containing + * the code to The Lean Mean C++ Option Parser. + * The "Software" does NOT refer to any other files which you + * may have received alongside this file (e.g. as part of a larger project that + * incorporates The Lean Mean C++ Option Parser). + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this 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. + */ + +/* + * NOTE: It is recommended that you read the processed HTML doxygen documentation + * rather than this source. If you don't know doxygen, it's like javadoc for C++. + * If you don't want to install doxygen you can find a copy of the processed + * documentation at + * + * http://optionparser.sourceforge.net/ + * + */ + +/** + * @file + * + * @brief This is the only file required to use The Lean Mean C++ Option Parser. + * Just \#include it and you're set. + * + * The Lean Mean C++ Option Parser handles the program's command line arguments + * (argc, argv). + * It supports the short and long option formats of getopt(), getopt_long() + * and getopt_long_only() but has a more convenient interface. + * The following features set it apart from other option parsers: + * + * @par Highlights: + *
    + *
  • It is a header-only library. Just \#include "optionparser.h" and you're set. + *
  • It is freestanding. There are no dependencies whatsoever, not even the + * C or C++ standard library. + *
  • It has a usage message formatter that supports column alignment and + * line wrapping. This aids localization because it adapts to + * translated strings that are shorter or longer (even if they contain + * Asian wide characters). + *
  • Unlike getopt() and derivatives it doesn't force you to loop through + * options sequentially. Instead you can access options directly like this: + *
      + *
    • Test for presence of a switch in the argument vector: + * @code if ( options[QUIET] ) ... @endcode + *
    • Evaluate --enable-foo/--disable-foo pair where the last one used wins: + * @code if ( options[FOO].last()->type() == DISABLE ) ... @endcode + *
    • Cumulative option (-v verbose, -vv more verbose, -vvv even more verbose): + * @code int verbosity = options[VERBOSE].count(); @endcode + *
    • Iterate over all --file=<fname> arguments: + * @code for (Option* opt = options[FILE]; opt; opt = opt->next()) + * fname = opt->arg; ... @endcode + *
    • If you really want to, you can still process all arguments in order: + * @code + * for (int i = 0; i < p.optionsCount(); ++i) { + * Option& opt = buffer[i]; + * switch(opt.index()) { + * case HELP: ... + * case VERBOSE: ... + * case FILE: fname = opt.arg; ... + * case UNKNOWN: ... + * @endcode + *
    + *
@n + * Despite these features the code size remains tiny. + * It is smaller than uClibc's GNU getopt() and just a + * couple 100 bytes larger than uClibc's SUSv3 getopt(). @n + * (This does not include the usage formatter, of course. But you don't have to use that.) + * + * @par Download: + * Tarball with examples and test programs: + * optionparser-1.4.tar.gz @n + * Just the header (this is all you really need): + * optionparser.h + * + * @par Changelog: + * Version 1.4: Fixed 2 printUsage() bugs that messed up output with small COLUMNS values @n + * Version 1.3: Compatible with Microsoft Visual C++. @n + * Version 1.2: Added @ref option::Option::namelen "Option::namelen" and removed the extraction + * of short option characters into a special buffer. @n + * Changed @ref option::Arg::Optional "Arg::Optional" to accept arguments if they are attached + * rather than separate. This is what GNU getopt() does and how POSIX recommends + * utilities should interpret their arguments.@n + * Version 1.1: Optional mode with argument reordering as done by GNU getopt(), so that + * options and non-options can be mixed. See + * @ref option::Parser::parse() "Parser::parse()". + * + * @par Feedback: + * Send questions, bug reports, feature requests etc. to: optionparser-feedback (a) lists.sourceforge.net + * @htmlonly @endhtmlonly + * + * + * @par Example program: + * (Note: @c option::* identifiers are links that take you to their documentation.) + * @code + * #error EXAMPLE SHORTENED FOR READABILITY. BETTER EXAMPLES ARE IN THE .TAR.GZ! + * #include + * #include "optionparser.h" + * + * enum optionIndex { UNKNOWN, HELP, PLUS }; + * const option::Descriptor usage[] = + * { + * {UNKNOWN, 0,"" , "" ,option::Arg::None, "USAGE: example [options]\n\n" + * "Options:" }, + * {HELP, 0,"" , "help",option::Arg::None, " --help \tPrint usage and exit." }, + * {PLUS, 0,"p", "plus",option::Arg::None, " --plus, -p \tIncrement count." }, + * {UNKNOWN, 0,"" , "" ,option::Arg::None, "\nExamples:\n" + * " example --unknown -- --this_is_no_option\n" + * " example -unk --plus -ppp file1 file2\n" }, + * {0,0,0,0,0,0} + * }; + * + * int main(int argc, char* argv[]) + * { + * argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present + * option::Stats stats(usage, argc, argv); + * option::Option options[stats.options_max], buffer[stats.buffer_max]; + * option::Parser parse(usage, argc, argv, options, buffer); + * + * if (parse.error()) + * return 1; + * + * if (options[HELP] || argc == 0) { + * option::printUsage(std::cout, usage); + * return 0; + * } + * + * std::cout << "--plus count: " << + * options[PLUS].count() << "\n"; + * + * for (option::Option* opt = options[UNKNOWN]; opt; opt = opt->next()) + * std::cout << "Unknown option: " << opt->name << "\n"; + * + * for (int i = 0; i < parse.nonOptionsCount(); ++i) + * std::cout << "Non-option #" << i << ": " << parse.nonOption(i) << "\n"; + * } + * @endcode + * + * @par Option syntax: + * @li The Lean Mean C++ Option Parser follows POSIX getopt() conventions and supports + * GNU-style getopt_long() long options as well as Perl-style single-minus + * long options (getopt_long_only()). + * @li short options have the format @c -X where @c X is any character that fits in a char. + * @li short options can be grouped, i.e. -X -Y is equivalent to @c -XY. + * @li a short option may take an argument either separate (-X foo) or + * attached (@c -Xfoo). You can make the parser accept the additional format @c -X=foo by + * registering @c X as a long option (in addition to being a short option) and + * enabling single-minus long options. + * @li an argument-taking short option may be grouped if it is the last in the group, e.g. + * @c -ABCXfoo or -ABCX foo (@c foo is the argument to the @c -X option). + * @li a lone minus character @c '-' is not treated as an option. It is customarily used where + * a file name is expected to refer to stdin or stdout. + * @li long options have the format @c --option-name. + * @li the option-name of a long option can be anything and include any characters. + * Even @c = characters will work, but don't do that. + * @li [optional] long options may be abbreviated as long as the abbreviation is unambiguous. + * You can set a minimum length for abbreviations. + * @li [optional] long options may begin with a single minus. The double minus form is always + * accepted, too. + * @li a long option may take an argument either separate ( --option arg ) or + * attached ( --option=arg ). In the attached form the equals sign is mandatory. + * @li an empty string can be passed as an attached long option argument: --option-name= . + * Note the distinction between an empty string as argument and no argument at all. + * @li an empty string is permitted as separate argument to both long and short options. + * @li Arguments to both short and long options may start with a @c '-' character. E.g. + * -X-X , -X -X or --long-X=-X . If @c -X + * and @c --long-X take an argument, that argument will be @c "-X" in all 3 cases. + * @li If using the built-in @ref option::Arg::Optional "Arg::Optional", optional arguments must + * be attached. + * @li the special option @c -- (i.e. without a name) terminates the list of + * options. Everything that follows is a non-option argument, even if it starts with + * a @c '-' character. The @c -- itself will not appear in the parse results. + * @li the first argument that doesn't start with @c '-' or @c '--' and does not belong to + * a preceding argument-taking option, will terminate the option list and is the + * first non-option argument. All following command line arguments are treated as + * non-option arguments, even if they start with @c '-' . @n + * NOTE: This behaviour is mandated by POSIX, but GNU getopt() only honours this if it is + * explicitly requested (e.g. by setting POSIXLY_CORRECT). @n + * You can enable the GNU behaviour by passing @c true as first argument to + * e.g. @ref option::Parser::parse() "Parser::parse()". + * @li Arguments that look like options (i.e. @c '-' followed by at least 1 character) but + * aren't, are NOT treated as non-option arguments. They are treated as unknown options and + * are collected into a list of unknown options for error reporting. @n + * This means that in order to pass a first non-option + * argument beginning with the minus character it is required to use the + * @c -- special option, e.g. + * @code + * program -x -- --strange-filename + * @endcode + * In this example, @c --strange-filename is a non-option argument. If the @c -- + * were omitted, it would be treated as an unknown option. @n + * See @ref option::Descriptor::longopt for information on how to collect unknown options. + * + */ + +#ifndef OPTIONPARSER_H_ +#define OPTIONPARSER_H_ + +/** @brief The namespace of The Lean Mean C++ Option Parser. */ +namespace option +{ + +#ifdef _MSC_VER +#include +#pragma intrinsic(_BitScanReverse) +struct MSC_Builtin_CLZ +{ + static int builtin_clz(unsigned x) + { + unsigned long index; + _BitScanReverse(&index, x); + return 32-index; // int is always 32bit on Windows, even for target x64 + } +}; +#define __builtin_clz(x) MSC_Builtin_CLZ::builtin_clz(x) +#endif + +class Option; + +/** + * @brief Possible results when checking if an argument is valid for a certain option. + * + * In the case that no argument is provided for an option that takes an + * optional argument, return codes @c ARG_OK and @c ARG_IGNORE are equivalent. + */ +enum ArgStatus +{ + //! The option does not take an argument. + ARG_NONE, + //! The argument is acceptable for the option. + ARG_OK, + //! The argument is not acceptable but that's non-fatal because the option's argument is optional. + ARG_IGNORE, + //! The argument is not acceptable and that's fatal. + ARG_ILLEGAL +}; + +/** + * @brief Signature of functions that check if an argument is valid for a certain type of option. + * + * Every Option has such a function assigned in its Descriptor. + * @code + * Descriptor usage[] = { {UNKNOWN, 0, "", "", Arg::None, ""}, ... }; + * @endcode + * + * A CheckArg function has the following signature: + * @code ArgStatus CheckArg(const Option& option, bool msg); @endcode + * + * It is used to check if a potential argument would be acceptable for the option. + * It will even be called if there is no argument. In that case @c option.arg will be @c NULL. + * + * If @c msg is @c true and the function determines that an argument is not acceptable and + * that this is a fatal error, it should output a message to the user before + * returning @ref ARG_ILLEGAL. If @c msg is @c false the function should remain silent (or you + * will get duplicate messages). + * + * See @ref ArgStatus for the meaning of the return values. + * + * While you can provide your own functions, + * often the following pre-defined checks (which never return @ref ARG_ILLEGAL) will suffice: + * + * @li @c Arg::None @copybrief Arg::None + * @li @c Arg::Optional @copybrief Arg::Optional + * + */ +typedef ArgStatus (*CheckArg)(const Option& option, bool msg); + +/** + * @brief Describes an option, its help text (usage) and how it should be parsed. + * + * The main input when constructing an option::Parser is an array of Descriptors. + + * @par Example: + * @code + * enum OptionIndex {CREATE, ...}; + * enum OptionType {DISABLE, ENABLE, OTHER}; + * + * const option::Descriptor usage[] = { + * { CREATE, // index + * OTHER, // type + * "c", // shortopt + * "create", // longopt + * Arg::None, // check_arg + * "--create Tells the program to create something." // help + * } + * , ... + * }; + * @endcode + */ +struct Descriptor +{ + /** + * @brief Index of this option's linked list in the array filled in by the parser. + * + * Command line options whose Descriptors have the same index will end up in the same + * linked list in the order in which they appear on the command line. If you have + * multiple long option aliases that refer to the same option, give their descriptors + * the same @c index. + * + * If you have options that mean exactly opposite things + * (e.g. @c --enable-foo and @c --disable-foo ), you should also give them the same + * @c index, but distinguish them through different values for @ref type. + * That way they end up in the same list and you can just take the last element of the + * list and use its type. This way you get the usual behaviour where switches later + * on the command line override earlier ones without having to code it manually. + * + * @par Tip: + * Use an enum rather than plain ints for better readability, as shown in the example + * at Descriptor. + */ + const unsigned index; + + /** + * @brief Used to distinguish between options with the same @ref index. + * See @ref index for details. + * + * It is recommended that you use an enum rather than a plain int to make your + * code more readable. + */ + const int type; + + /** + * @brief Each char in this string will be accepted as a short option character. + * + * The string must not include the minus character @c '-' or you'll get undefined + * behaviour. + * + * If this Descriptor should not have short option characters, use the empty + * string "". NULL is not permitted here! + * + * See @ref longopt for more information. + */ + const char* const shortopt; + + /** + * @brief The long option name (without the leading @c -- ). + * + * If this Descriptor should not have a long option name, use the empty + * string "". NULL is not permitted here! + * + * While @ref shortopt allows multiple short option characters, each + * Descriptor can have only a single long option name. If you have multiple + * long option names referring to the same option use separate Descriptors + * that have the same @ref index and @ref type. You may repeat + * short option characters in such an alias Descriptor but there's no need to. + * + * @par Dummy Descriptors: + * You can use dummy Descriptors with an + * empty string for both @ref shortopt and @ref longopt to add text to + * the usage that is not related to a specific option. See @ref help. + * The first dummy Descriptor will be used for unknown options (see below). + * + * @par Unknown Option Descriptor: + * The first dummy Descriptor in the list of Descriptors, + * whose @ref shortopt and @ref longopt are both the empty string, will be used + * as the Descriptor for unknown options. An unknown option is a string in + * the argument vector that is not a lone minus @c '-' but starts with a minus + * character and does not match any Descriptor's @ref shortopt or @ref longopt. @n + * Note that the dummy descriptor's @ref check_arg function @e will be called and + * its return value will be evaluated as usual. I.e. if it returns @ref ARG_ILLEGAL + * the parsing will be aborted with Parser::error()==true. @n + * if @c check_arg does not return @ref ARG_ILLEGAL the descriptor's + * @ref index @e will be used to pick the linked list into which + * to put the unknown option. @n + * If there is no dummy descriptor, unknown options will be dropped silently. + * + */ + const char* const longopt; + + /** + * @brief For each option that matches @ref shortopt or @ref longopt this function + * will be called to check a potential argument to the option. + * + * This function will be called even if there is no potential argument. In that case + * it will be passed @c NULL as @c arg parameter. Do not confuse this with the empty + * string. + * + * See @ref CheckArg for more information. + */ + const CheckArg check_arg; + + /** + * @brief The usage text associated with the options in this Descriptor. + * + * You can use option::printUsage() to format your usage message based on + * the @c help texts. You can use dummy Descriptors where + * @ref shortopt and @ref longopt are both the empty string to add text to + * the usage that is not related to a specific option. + * + * See option::printUsage() for special formatting characters you can use in + * @c help to get a column layout. + * + * @attention + * Must be UTF-8-encoded. If your compiler supports C++11 you can use the "u8" + * prefix to make sure string literals are properly encoded. + */ + const char* help; +}; + +/** + * @brief A parsed option from the command line together with its argument if it has one. + * + * The Parser chains all parsed options with the same Descriptor::index together + * to form a linked list. This allows you to easily implement all of the common ways + * of handling repeated options and enable/disable pairs. + * + * @li Test for presence of a switch in the argument vector: + * @code if ( options[QUIET] ) ... @endcode + * @li Evaluate --enable-foo/--disable-foo pair where the last one used wins: + * @code if ( options[FOO].last()->type() == DISABLE ) ... @endcode + * @li Cumulative option (-v verbose, -vv more verbose, -vvv even more verbose): + * @code int verbosity = options[VERBOSE].count(); @endcode + * @li Iterate over all --file=<fname> arguments: + * @code for (Option* opt = options[FILE]; opt; opt = opt->next()) + * fname = opt->arg; ... @endcode + */ +class Option +{ + Option* next_; + Option* prev_; +public: + /** + * @brief Pointer to this Option's Descriptor. + * + * Remember that the first dummy descriptor (see @ref Descriptor::longopt) is used + * for unknown options. + * + * @attention + * @c desc==NULL signals that this Option is unused. This is the default state of + * elements in the result array. You don't need to test @c desc explicitly. You + * can simply write something like this: + * @code + * if (options[CREATE]) + * { + * ... + * } + * @endcode + * This works because of operator const Option*() . + */ + const Descriptor* desc; + + /** + * @brief The name of the option as used on the command line. + * + * The main purpose of this string is to be presented to the user in messages. + * + * In the case of a long option, this is the actual @c argv pointer, i.e. the first + * character is a '-'. In the case of a short option this points to the option + * character within the @c argv string. + * + * Note that in the case of a short option group or an attached option argument, this + * string will contain additional characters following the actual name. Use @ref namelen + * to filter out the actual option name only. + * + */ + const char* name; + + /** + * @brief Pointer to this Option's argument (if any). + * + * NULL if this option has no argument. Do not confuse this with the empty string which + * is a valid argument. + */ + const char* arg; + + /** + * @brief The length of the option @ref name. + * + * Because @ref name points into the actual @c argv string, the option name may be + * followed by more characters (e.g. other short options in the same short option group). + * This value is the number of bytes (not characters!) that are part of the actual name. + * + * For a short option, this length is always 1. For a long option this length is always + * at least 2 if single minus long options are permitted and at least 3 if they are disabled. + * + * @note + * In the pathological case of a minus within a short option group (e.g. @c -xf-z), this + * length is incorrect, because this case will be misinterpreted as a long option and the + * name will therefore extend to the string's 0-terminator or a following '=" character + * if there is one. This is irrelevant for most uses of @ref name and @c namelen. If you + * really need to distinguish the case of a long and a short option, compare @ref name to + * the @c argv pointers. A long option's @c name is always identical to one of them, + * whereas a short option's is never. + */ + int namelen; + + /** + * @brief Returns Descriptor::type of this Option's Descriptor, or 0 if this Option + * is invalid (unused). + * + * Because this method (and last(), too) can be used even on unused Options with desc==0, you can (provided + * you arrange your types properly) switch on type() without testing validity first. + * @code + * enum OptionType { UNUSED=0, DISABLED=0, ENABLED=1 }; + * enum OptionIndex { FOO }; + * const Descriptor usage[] = { + * { FOO, ENABLED, "", "enable-foo", Arg::None, 0 }, + * { FOO, DISABLED, "", "disable-foo", Arg::None, 0 }, + * { 0, 0, 0, 0, 0, 0 } }; + * ... + * switch(options[FOO].last()->type()) // no validity check required! + * { + * case ENABLED: ... + * case DISABLED: ... // UNUSED==DISABLED ! + * } + * @endcode + */ + int type() const + { + return desc == 0 ? 0 : desc->type; + } + + /** + * @brief Returns Descriptor::index of this Option's Descriptor, or -1 if this Option + * is invalid (unused). + */ + int index() const + { + return desc == 0 ? -1 : (int)desc->index; + } + + /** + * @brief Returns the number of times this Option (or others with the same Descriptor::index) + * occurs in the argument vector. + * + * This corresponds to the number of elements in the linked list this Option is part of. + * It doesn't matter on which element you call count(). The return value is always the same. + * + * Use this to implement cumulative options, such as -v, -vv, -vvv for + * different verbosity levels. + * + * Returns 0 when called for an unused/invalid option. + */ + int count() + { + int c = (desc == 0 ? 0 : 1); + Option* p = first(); + while (!p->isLast()) + { + ++c; + p = p->next_; + }; + return c; + } + + /** + * @brief Returns true iff this is the first element of the linked list. + * + * The first element in the linked list is the first option on the command line + * that has the respective Descriptor::index value. + * + * Returns true for an unused/invalid option. + */ + bool isFirst() const + { + return isTagged(prev_); + } + + /** + * @brief Returns true iff this is the last element of the linked list. + * + * The last element in the linked list is the last option on the command line + * that has the respective Descriptor::index value. + * + * Returns true for an unused/invalid option. + */ + bool isLast() const + { + return isTagged(next_); + } + + /** + * @brief Returns a pointer to the first element of the linked list. + * + * Use this when you want the first occurrence of an option on the command line to + * take precedence. Note that this is not the way most programs handle options. + * You should probably be using last() instead. + * + * @note + * This method may be called on an unused/invalid option and will return a pointer to the + * option itself. + */ + Option* first() + { + Option* p = this; + while (!p->isFirst()) + p = p->prev_; + return p; + } + + /** + * @brief Returns a pointer to the last element of the linked list. + * + * Use this when you want the last occurrence of an option on the command line to + * take precedence. This is the most common way of handling conflicting options. + * + * @note + * This method may be called on an unused/invalid option and will return a pointer to the + * option itself. + * + * @par Tip: + * If you have options with opposite meanings (e.g. @c --enable-foo and @c --disable-foo), you + * can assign them the same Descriptor::index to get them into the same list. Distinguish them by + * Descriptor::type and all you have to do is check last()->type() to get + * the state listed last on the command line. + */ + Option* last() + { + return first()->prevwrap(); + } + + /** + * @brief Returns a pointer to the previous element of the linked list or NULL if + * called on first(). + * + * If called on first() this method returns NULL. Otherwise it will return the + * option with the same Descriptor::index that precedes this option on the command + * line. + */ + Option* prev() + { + return isFirst() ? 0 : prev_; + } + + /** + * @brief Returns a pointer to the previous element of the linked list with wrap-around from + * first() to last(). + * + * If called on first() this method returns last(). Otherwise it will return the + * option with the same Descriptor::index that precedes this option on the command + * line. + */ + Option* prevwrap() + { + return untag(prev_); + } + + /** + * @brief Returns a pointer to the next element of the linked list or NULL if called + * on last(). + * + * If called on last() this method returns NULL. Otherwise it will return the + * option with the same Descriptor::index that follows this option on the command + * line. + */ + Option* next() + { + return isLast() ? 0 : next_; + } + + /** + * @brief Returns a pointer to the next element of the linked list with wrap-around from + * last() to first(). + * + * If called on last() this method returns first(). Otherwise it will return the + * option with the same Descriptor::index that follows this option on the command + * line. + */ + Option* nextwrap() + { + return untag(next_); + } + + /** + * @brief Makes @c new_last the new last() by chaining it into the list after last(). + * + * It doesn't matter which element you call append() on. The new element will always + * be appended to last(). + * + * @attention + * @c new_last must not yet be part of a list, or that list will become corrupted, because + * this method does not unchain @c new_last from an existing list. + */ + void append(Option* new_last) + { + Option* p = last(); + Option* f = first(); + p->next_ = new_last; + new_last->prev_ = p; + new_last->next_ = tag(f); + f->prev_ = tag(new_last); + } + + /** + * @brief Casts from Option to const Option* but only if this Option is valid. + * + * If this Option is valid (i.e. @c desc!=NULL), returns this. + * Otherwise returns NULL. This allows testing an Option directly + * in an if-clause to see if it is used: + * @code + * if (options[CREATE]) + * { + * ... + * } + * @endcode + * It also allows you to write loops like this: + * @code for (Option* opt = options[FILE]; opt; opt = opt->next()) + * fname = opt->arg; ... @endcode + */ + operator const Option*() const + { + return desc ? this : 0; + } + + /** + * @brief Casts from Option to Option* but only if this Option is valid. + * + * If this Option is valid (i.e. @c desc!=NULL), returns this. + * Otherwise returns NULL. This allows testing an Option directly + * in an if-clause to see if it is used: + * @code + * if (options[CREATE]) + * { + * ... + * } + * @endcode + * It also allows you to write loops like this: + * @code for (Option* opt = options[FILE]; opt; opt = opt->next()) + * fname = opt->arg; ... @endcode + */ + operator Option*() + { + return desc ? this : 0; + } + + /** + * @brief Creates a new Option that is a one-element linked list and has NULL + * @ref desc, @ref name, @ref arg and @ref namelen. + */ + Option() : + desc(0), name(0), arg(0), namelen(0) + { + prev_ = tag(this); + next_ = tag(this); + } + + /** + * @brief Creates a new Option that is a one-element linked list and has the given + * values for @ref desc, @ref name and @ref arg. + * + * If @c name_ points at a character other than '-' it will be assumed to refer to a + * short option and @ref namelen will be set to 1. Otherwise the length will extend to + * the first '=' character or the string's 0-terminator. + */ + Option(const Descriptor* desc_, const char* name_, const char* arg_) + { + init(desc_, name_, arg_); + } + + /** + * @brief Makes @c *this a copy of @c orig except for the linked list pointers. + * + * After this operation @c *this will be a one-element linked list. + */ + void operator=(const Option& orig) + { + init(orig.desc, orig.name, orig.arg); + } + + /** + * @brief Makes @c *this a copy of @c orig except for the linked list pointers. + * + * After this operation @c *this will be a one-element linked list. + */ + Option(const Option& orig) + { + init(orig.desc, orig.name, orig.arg); + } + +private: + /** + * @internal + * @brief Sets the fields of this Option to the given values (extracting @c name if necessary). + * + * If @c name_ points at a character other than '-' it will be assumed to refer to a + * short option and @ref namelen will be set to 1. Otherwise the length will extend to + * the first '=' character or the string's 0-terminator. + */ + void init(const Descriptor* desc_, const char* name_, const char* arg_) + { + desc = desc_; + name = name_; + arg = arg_; + prev_ = tag(this); + next_ = tag(this); + namelen = 0; + if (name == 0) + return; + namelen = 1; + if (name[0] != '-') + return; + while (name[namelen] != 0 && name[namelen] != '=') + ++namelen; + } + + static Option* tag(Option* ptr) + { + return (Option*) ((unsigned long long) ptr | 1); + } + + static Option* untag(Option* ptr) + { + return (Option*) ((unsigned long long) ptr & ~1ull); + } + + static bool isTagged(Option* ptr) + { + return ((unsigned long long) ptr & 1); + } +}; + +/** + * @brief Functions for checking the validity of option arguments. + * + * @copydetails CheckArg + * + * The following example code + * can serve as starting place for writing your own more complex CheckArg functions: + * @code + * struct Arg: public option::Arg + * { + * static void printError(const char* msg1, const option::Option& opt, const char* msg2) + * { + * fprintf(stderr, "ERROR: %s", msg1); + * fwrite(opt.name, opt.namelen, 1, stderr); + * fprintf(stderr, "%s", msg2); + * } + * + * static option::ArgStatus Unknown(const option::Option& option, bool msg) + * { + * if (msg) printError("Unknown option '", option, "'\n"); + * return option::ARG_ILLEGAL; + * } + * + * static option::ArgStatus Required(const option::Option& option, bool msg) + * { + * if (option.arg != 0) + * return option::ARG_OK; + * + * if (msg) printError("Option '", option, "' requires an argument\n"); + * return option::ARG_ILLEGAL; + * } + * + * static option::ArgStatus NonEmpty(const option::Option& option, bool msg) + * { + * if (option.arg != 0 && option.arg[0] != 0) + * return option::ARG_OK; + * + * if (msg) printError("Option '", option, "' requires a non-empty argument\n"); + * return option::ARG_ILLEGAL; + * } + * + * static option::ArgStatus Numeric(const option::Option& option, bool msg) + * { + * char* endptr = 0; + * if (option.arg != 0 && strtol(option.arg, &endptr, 10)){}; + * if (endptr != option.arg && *endptr == 0) + * return option::ARG_OK; + * + * if (msg) printError("Option '", option, "' requires a numeric argument\n"); + * return option::ARG_ILLEGAL; + * } + * }; + * @endcode + */ +struct Arg +{ + //! @brief For options that don't take an argument: Returns ARG_NONE. + static ArgStatus None(const Option&, bool) + { + return ARG_NONE; + } + + //! @brief Returns ARG_OK if the argument is attached and ARG_IGNORE otherwise. + static ArgStatus Optional(const Option& option, bool) + { + if (option.arg && option.name[option.namelen] != 0) + return ARG_OK; + else + return ARG_IGNORE; + } +}; + +/** + * @brief Determines the minimum lengths of the buffer and options arrays used for Parser. + * + * Because Parser doesn't use dynamic memory its output arrays have to be pre-allocated. + * If you don't want to use fixed size arrays (which may turn out too small, causing + * command line arguments to be dropped), you can use Stats to determine the correct sizes. + * Stats work cumulative. You can first pass in your default options and then the real + * options and afterwards the counts will reflect the union. + */ +struct Stats +{ + /** + * @brief Number of elements needed for a @c buffer[] array to be used for + * @ref Parser::parse() "parsing" the same argument vectors that were fed + * into this Stats object. + * + * @note + * This number is always 1 greater than the actual number needed, to give + * you a sentinel element. + */ + unsigned buffer_max; + + /** + * @brief Number of elements needed for an @c options[] array to be used for + * @ref Parser::parse() "parsing" the same argument vectors that were fed + * into this Stats object. + * + * @note + * @li This number is always 1 greater than the actual number needed, to give + * you a sentinel element. + * @li This number depends only on the @c usage, not the argument vectors, because + * the @c options array needs exactly one slot for each possible Descriptor::index. + */ + unsigned options_max; + + /** + * @brief Creates a Stats object with counts set to 1 (for the sentinel element). + */ + Stats() : + buffer_max(1), options_max(1) // 1 more than necessary as sentinel + { + } + + /** + * @brief Creates a new Stats object and immediately updates it for the + * given @c usage and argument vector. You may pass 0 for @c argc and/or @c argv, + * if you just want to update @ref options_max. + * + * @note + * The calls to Stats methods must match the later calls to Parser methods. + * See Parser::parse() for the meaning of the arguments. + */ + Stats(bool gnu, const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, // + bool single_minus_longopt = false) : + buffer_max(1), options_max(1) // 1 more than necessary as sentinel + { + add(gnu, usage, argc, argv, min_abbr_len, single_minus_longopt); + } + + //! @brief Stats(...) with non-const argv. + Stats(bool gnu, const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, // + bool single_minus_longopt = false) : + buffer_max(1), options_max(1) // 1 more than necessary as sentinel + { + add(gnu, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt); + } + + //! @brief POSIX Stats(...) (gnu==false). + Stats(const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, // + bool single_minus_longopt = false) : + buffer_max(1), options_max(1) // 1 more than necessary as sentinel + { + add(false, usage, argc, argv, min_abbr_len, single_minus_longopt); + } + + //! @brief POSIX Stats(...) (gnu==false) with non-const argv. + Stats(const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, // + bool single_minus_longopt = false) : + buffer_max(1), options_max(1) // 1 more than necessary as sentinel + { + add(false, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt); + } + + /** + * @brief Updates this Stats object for the + * given @c usage and argument vector. You may pass 0 for @c argc and/or @c argv, + * if you just want to update @ref options_max. + * + * @note + * The calls to Stats methods must match the later calls to Parser methods. + * See Parser::parse() for the meaning of the arguments. + */ + void add(bool gnu, const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, // + bool single_minus_longopt = false); + + //! @brief add() with non-const argv. + void add(bool gnu, const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, // + bool single_minus_longopt = false) + { + add(gnu, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt); + } + + //! @brief POSIX add() (gnu==false). + void add(const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, // + bool single_minus_longopt = false) + { + add(false, usage, argc, argv, min_abbr_len, single_minus_longopt); + } + + //! @brief POSIX add() (gnu==false) with non-const argv. + void add(const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, // + bool single_minus_longopt = false) + { + add(false, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt); + } +private: + class CountOptionsAction; +}; + +/** + * @brief Checks argument vectors for validity and parses them into data + * structures that are easier to work with. + * + * @par Example: + * @code + * int main(int argc, char* argv[]) + * { + * argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present + * option::Stats stats(usage, argc, argv); + * option::Option options[stats.options_max], buffer[stats.buffer_max]; + * option::Parser parse(usage, argc, argv, options, buffer); + * + * if (parse.error()) + * return 1; + * + * if (options[HELP]) + * ... + * @endcode + */ +class Parser +{ + int op_count; //!< @internal @brief see optionsCount() + int nonop_count; //!< @internal @brief see nonOptionsCount() + const char** nonop_args; //!< @internal @brief see nonOptions() + bool err; //!< @internal @brief see error() +public: + + /** + * @brief Creates a new Parser. + */ + Parser() : + op_count(0), nonop_count(0), nonop_args(0), err(false) + { + } + + /** + * @brief Creates a new Parser and immediately parses the given argument vector. + * @copydetails parse() + */ + Parser(bool gnu, const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[], + int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1) : + op_count(0), nonop_count(0), nonop_args(0), err(false) + { + parse(gnu, usage, argc, argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); + } + + //! @brief Parser(...) with non-const argv. + Parser(bool gnu, const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[], + int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1) : + op_count(0), nonop_count(0), nonop_args(0), err(false) + { + parse(gnu, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); + } + + //! @brief POSIX Parser(...) (gnu==false). + Parser(const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[], int min_abbr_len = 0, + bool single_minus_longopt = false, int bufmax = -1) : + op_count(0), nonop_count(0), nonop_args(0), err(false) + { + parse(false, usage, argc, argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); + } + + //! @brief POSIX Parser(...) (gnu==false) with non-const argv. + Parser(const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[], int min_abbr_len = 0, + bool single_minus_longopt = false, int bufmax = -1) : + op_count(0), nonop_count(0), nonop_args(0), err(false) + { + parse(false, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); + } + + /** + * @brief Parses the given argument vector. + * + * @param gnu if true, parse() will not stop at the first non-option argument. Instead it will + * reorder arguments so that all non-options are at the end. This is the default behaviour + * of GNU getopt() but is not conforming to POSIX. @n + * Note, that once the argument vector has been reordered, the @c gnu flag will have + * no further effect on this argument vector. So it is enough to pass @c gnu==true when + * creating Stats. + * @param usage Array of Descriptor objects that describe the options to support. The last entry + * of this array must have 0 in all fields. + * @param argc The number of elements from @c argv that are to be parsed. If you pass -1, the number + * will be determined automatically. In that case the @c argv list must end with a NULL + * pointer. + * @param argv The arguments to be parsed. If you pass -1 as @c argc the last pointer in the @c argv + * list must be NULL to mark the end. + * @param options Each entry is the first element of a linked list of Options. Each new option + * that is parsed will be appended to the list specified by that Option's + * Descriptor::index. If an entry is not yet used (i.e. the Option is invalid), + * it will be replaced rather than appended to. @n + * The minimum length of this array is the greatest Descriptor::index value that + * occurs in @c usage @e PLUS ONE. + * @param buffer Each argument that is successfully parsed (including unknown arguments, if they + * have a Descriptor whose CheckArg does not return @ref ARG_ILLEGAL) will be stored in this + * array. parse() scans the array for the first invalid entry and begins writing at that + * index. You can pass @c bufmax to limit the number of options stored. + * @param min_abbr_len Passing a value min_abbr_len > 0 enables abbreviated long + * options. The parser will match a prefix of a long option as if it was + * the full long option (e.g. @c --foob=10 will be interpreted as if it was + * @c --foobar=10 ), as long as the prefix has at least @c min_abbr_len characters + * (not counting the @c -- ) and is unambiguous. + * @n Be careful if combining @c min_abbr_len=1 with @c single_minus_longopt=true + * because the ambiguity check does not consider short options and abbreviated + * single minus long options will take precedence over short options. + * @param single_minus_longopt Passing @c true for this option allows long options to begin with + * a single minus. The double minus form will still be recognized. Note that + * single minus long options take precedence over short options and short option + * groups. E.g. @c -file would be interpreted as @c --file and not as + * -f -i -l -e (assuming a long option named @c "file" exists). + * @param bufmax The greatest index in the @c buffer[] array that parse() will write to is + * @c bufmax-1. If there are more options, they will be processed (in particular + * their CheckArg will be called) but not stored. @n + * If you used Stats::buffer_max to dimension this array, you can pass + * -1 (or not pass @c bufmax at all) which tells parse() that the buffer is + * "large enough". + * @attention + * Remember that @c options and @c buffer store Option @e objects, not pointers. Therefore it + * is not possible for the same object to be in both arrays. For those options that are found in + * both @c buffer[] and @c options[] the respective objects are independent copies. And only the + * objects in @c options[] are properly linked via Option::next() and Option::prev(). + * You can iterate over @c buffer[] to + * process all options in the order they appear in the argument vector, but if you want access to + * the other Options with the same Descriptor::index, then you @e must access the linked list via + * @c options[]. You can get the linked list in options from a buffer object via something like + * @c options[buffer[i].index()]. + */ + void parse(bool gnu, const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[], + int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1); + + //! @brief parse() with non-const argv. + void parse(bool gnu, const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[], + int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1) + { + parse(gnu, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); + } + + //! @brief POSIX parse() (gnu==false). + void parse(const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[], + int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1) + { + parse(false, usage, argc, argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); + } + + //! @brief POSIX parse() (gnu==false) with non-const argv. + void parse(const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[], int min_abbr_len = 0, + bool single_minus_longopt = false, int bufmax = -1) + { + parse(false, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax); + } + + /** + * @brief Returns the number of valid Option objects in @c buffer[]. + * + * @note + * @li The returned value always reflects the number of Options in the buffer[] array used for + * the most recent call to parse(). + * @li The count (and the buffer[]) includes unknown options if they are collected + * (see Descriptor::longopt). + */ + int optionsCount() + { + return op_count; + } + + /** + * @brief Returns the number of non-option arguments that remained at the end of the + * most recent parse() that actually encountered non-option arguments. + * + * @note + * A parse() that does not encounter non-option arguments will leave this value + * as well as nonOptions() undisturbed. This means you can feed the Parser a + * default argument vector that contains non-option arguments (e.g. a default filename). + * Then you feed it the actual arguments from the user. If the user has supplied at + * least one non-option argument, all of the non-option arguments from the default + * disappear and are replaced by the user's non-option arguments. However, if the + * user does not supply any non-option arguments the defaults will still be in + * effect. + */ + int nonOptionsCount() + { + return nonop_count; + } + + /** + * @brief Returns a pointer to an array of non-option arguments (only valid + * if nonOptionsCount() >0 ). + * + * @note + * @li parse() does not copy arguments, so this pointer points into the actual argument + * vector as passed to parse(). + * @li As explained at nonOptionsCount() this pointer is only changed by parse() calls + * that actually encounter non-option arguments. A parse() call that encounters only + * options, will not change nonOptions(). + */ + const char** nonOptions() + { + return nonop_args; + } + + /** + * @brief Returns nonOptions()[i] (@e without checking if i is in range!). + */ + const char* nonOption(int i) + { + return nonOptions()[i]; + } + + /** + * @brief Returns @c true if an unrecoverable error occurred while parsing options. + * + * An illegal argument to an option (i.e. CheckArg returns @ref ARG_ILLEGAL) is an + * unrecoverable error that aborts the parse. Unknown options are only an error if + * their CheckArg function returns @ref ARG_ILLEGAL. Otherwise they are collected. + * In that case if you want to exit the program if either an illegal argument + * or an unknown option has been passed, use code like this + * + * @code + * if (parser.error() || options[UNKNOWN]) + * exit(1); + * @endcode + * + */ + bool error() + { + return err; + } + +private: + friend struct Stats; + class StoreOptionAction; + struct Action; + + /** + * @internal + * @brief This is the core function that does all the parsing. + * @retval false iff an unrecoverable error occurred. + */ + static bool workhorse(bool gnu, const Descriptor usage[], int numargs, const char** args, Action& action, + bool single_minus_longopt, bool print_errors, int min_abbr_len); + + /** + * @internal + * @brief Returns true iff @c st1 is a prefix of @c st2 and + * in case @c st2 is longer than @c st1, then + * the first additional character is '='. + * + * @par Examples: + * @code + * streq("foo", "foo=bar") == true + * streq("foo", "foobar") == false + * streq("foo", "foo") == true + * streq("foo=bar", "foo") == false + * @endcode + */ + static bool streq(const char* st1, const char* st2) + { + while (*st1 != 0) + if (*st1++ != *st2++) + return false; + return (*st2 == 0 || *st2 == '='); + } + + /** + * @internal + * @brief Like streq() but handles abbreviations. + * + * Returns true iff @c st1 and @c st2 have a common + * prefix with the following properties: + * @li (if min > 0) its length is at least @c min characters or the same length as @c st1 (whichever is smaller). + * @li (if min <= 0) its length is the same as that of @c st1 + * @li within @c st2 the character following the common prefix is either '=' or end-of-string. + * + * Examples: + * @code + * streqabbr("foo", "foo=bar",) == true + * streqabbr("foo", "fo=bar" , 2) == true + * streqabbr("foo", "fo" , 2) == true + * streqabbr("foo", "fo" , 0) == false + * streqabbr("foo", "f=bar" , 2) == false + * streqabbr("foo", "f" , 2) == false + * streqabbr("fo" , "foo=bar",) == false + * streqabbr("foo", "foobar" ,) == false + * streqabbr("foo", "fobar" ,) == false + * streqabbr("foo", "foo" ,) == true + * @endcode + */ + static bool streqabbr(const char* st1, const char* st2, long long min) + { + const char* st1start = st1; + while (*st1 != 0 && (*st1 == *st2)) + { + ++st1; + ++st2; + } + + return (*st1 == 0 || (min > 0 && (st1 - st1start) >= min)) && (*st2 == 0 || *st2 == '='); + } + + /** + * @internal + * @brief Returns true iff character @c ch is contained in the string @c st. + * + * Returns @c true for @c ch==0 . + */ + static bool instr(char ch, const char* st) + { + while (*st != 0 && *st != ch) + ++st; + return *st == ch; + } + + /** + * @internal + * @brief Rotates args[-count],...,args[-1],args[0] to become + * args[0],args[-count],...,args[-1]. + */ + static void shift(const char** args, int count) + { + for (int i = 0; i > -count; --i) + { + const char* temp = args[i]; + args[i] = args[i - 1]; + args[i - 1] = temp; + } + } +}; + +/** + * @internal + * @brief Interface for actions Parser::workhorse() should perform for each Option it + * parses. + */ +struct Parser::Action +{ + + /// @note 2017-01-26 GRVS Added virtual destructor. + virtual ~Action() = default; + + /** + * @brief Called by Parser::workhorse() for each Option that has been successfully + * parsed (including unknown + * options if they have a Descriptor whose Descriptor::check_arg does not return + * @ref ARG_ILLEGAL. + * + * Returns @c false iff a fatal error has occured and the parse should be aborted. + */ + virtual bool perform(Option&) + { + return true; + } + + /** + * @brief Called by Parser::workhorse() after finishing the parse. + * @param numargs the number of non-option arguments remaining + * @param args pointer to the first remaining non-option argument (if numargs > 0). + * + * @return + * @c false iff a fatal error has occurred. + */ + virtual bool finished(int numargs, const char** args) + { + (void) numargs; + (void) args; + return true; + } +}; + +/** + * @internal + * @brief An Action to pass to Parser::workhorse() that will increment a counter for + * each parsed Option. + */ +class Stats::CountOptionsAction: public Parser::Action +{ + unsigned* buffer_max; +public: + /** + * Creates a new CountOptionsAction that will increase @c *buffer_max_ for each + * parsed Option. + */ + CountOptionsAction(unsigned* buffer_max_) : + buffer_max(buffer_max_) + { + } + + bool perform(Option&) + { + if (*buffer_max == 0x7fffffff) + return false; // overflow protection: don't accept number of options that doesn't fit signed int + ++*buffer_max; + return true; + } +}; + +/** + * @internal + * @brief An Action to pass to Parser::workhorse() that will store each parsed Option in + * appropriate arrays (see Parser::parse()). + */ +class Parser::StoreOptionAction: public Parser::Action +{ + Parser& parser; + Option* options; + Option* buffer; + int bufmax; //! Number of slots in @c buffer. @c -1 means "large enough". +public: + /** + * @brief Creates a new StoreOption action. + * @param parser_ the parser whose op_count should be updated. + * @param options_ each Option @c o is chained into the linked list @c options_[o.desc->index] + * @param buffer_ each Option is appended to this array as long as there's a free slot. + * @param bufmax_ number of slots in @c buffer_. @c -1 means "large enough". + */ + StoreOptionAction(Parser& parser_, Option options_[], Option buffer_[], int bufmax_) : + parser(parser_), options(options_), buffer(buffer_), bufmax(bufmax_) + { + // find first empty slot in buffer (if any) + int bufidx = 0; + while ((bufmax < 0 || bufidx < bufmax) && buffer[bufidx]) + ++bufidx; + + // set parser's optionCount + parser.op_count = bufidx; + } + + bool perform(Option& option) + { + if (bufmax < 0 || parser.op_count < bufmax) + { + if (parser.op_count == 0x7fffffff) + return false; // overflow protection: don't accept number of options that doesn't fit signed int + + buffer[parser.op_count] = option; + int idx = buffer[parser.op_count].desc->index; + if (options[idx]) + options[idx].append(buffer[parser.op_count]); + else + options[idx] = buffer[parser.op_count]; + ++parser.op_count; + } + return true; // NOTE: an option that is discarded because of a full buffer is not fatal + } + + bool finished(int numargs, const char** args) + { + // only overwrite non-option argument list if there's at least 1 + // new non-option argument. Otherwise we keep the old list. This + // makes it easy to use default non-option arguments. + if (numargs > 0) + { + parser.nonop_count = numargs; + parser.nonop_args = args; + } + + return true; + } +}; + +inline void Parser::parse(bool gnu, const Descriptor usage[], int argc, const char** argv, Option options[], + Option buffer[], int min_abbr_len, bool single_minus_longopt, int bufmax) +{ + StoreOptionAction action(*this, options, buffer, bufmax); + err = !workhorse(gnu, usage, argc, argv, action, single_minus_longopt, true, min_abbr_len); +} + +inline void Stats::add(bool gnu, const Descriptor usage[], int argc, const char** argv, int min_abbr_len, + bool single_minus_longopt) +{ + // determine size of options array. This is the greatest index used in the usage + 1 + int i = 0; + while (usage[i].shortopt != 0) + { + if (usage[i].index + 1 >= options_max) + options_max = (usage[i].index + 1) + 1; // 1 more than necessary as sentinel + + ++i; + } + + CountOptionsAction action(&buffer_max); + Parser::workhorse(gnu, usage, argc, argv, action, single_minus_longopt, false, min_abbr_len); +} + +inline bool Parser::workhorse(bool gnu, const Descriptor usage[], int numargs, const char** args, Action& action, + bool single_minus_longopt, bool print_errors, int min_abbr_len) +{ + // protect against NULL pointer + if (args == 0) + numargs = 0; + + int nonops = 0; + + while (numargs != 0 && *args != 0) + { + const char* param = *args; // param can be --long-option, -srto or non-option argument + + // in POSIX mode the first non-option argument terminates the option list + // a lone minus character is a non-option argument + if (param[0] != '-' || param[1] == 0) + { + if (gnu) + { + ++nonops; + ++args; + if (numargs > 0) + --numargs; + continue; + } + else + break; + } + + // -- terminates the option list. The -- itself is skipped. + if (param[1] == '-' && param[2] == 0) + { + shift(args, nonops); + ++args; + if (numargs > 0) + --numargs; + break; + } + + bool handle_short_options; + const char* longopt_name; + if (param[1] == '-') // if --long-option + { + handle_short_options = false; + longopt_name = param + 2; + } + else + { + handle_short_options = true; + longopt_name = param + 1; //for testing a potential -long-option + } + + bool try_single_minus_longopt = single_minus_longopt; + bool have_more_args = (numargs > 1 || numargs < 0); // is referencing argv[1] valid? + + do // loop over short options in group, for long options the body is executed only once + { + int idx = 0; + + const char* optarg = nullptr; /// @note 2017-01-26 GRVS Initialize to nullptr, wasn't initialized before. + + /******************** long option **********************/ + if (handle_short_options == false || try_single_minus_longopt) + { + idx = 0; + while (usage[idx].longopt != 0 && !streq(usage[idx].longopt, longopt_name)) + ++idx; + + if (usage[idx].longopt == 0 && min_abbr_len > 0) // if we should try to match abbreviated long options + { + int i1 = 0; + while (usage[i1].longopt != 0 && !streqabbr(usage[i1].longopt, longopt_name, min_abbr_len)) + ++i1; + if (usage[i1].longopt != 0) + { // now test if the match is unambiguous by checking for another match + int i2 = i1 + 1; + while (usage[i2].longopt != 0 && !streqabbr(usage[i2].longopt, longopt_name, min_abbr_len)) + ++i2; + + if (usage[i2].longopt == 0) // if there was no second match it's unambiguous, so accept i1 as idx + idx = i1; + } + } + + // if we found something, disable handle_short_options (only relevant if single_minus_longopt) + if (usage[idx].longopt != 0) + handle_short_options = false; + + try_single_minus_longopt = false; // prevent looking for longopt in the middle of shortopt group + + optarg = longopt_name; + while (*optarg != 0 && *optarg != '=') + ++optarg; + if (*optarg == '=') // attached argument + ++optarg; + else + // possibly detached argument + optarg = (have_more_args ? args[1] : 0); + } + + /************************ short option ***********************************/ + if (handle_short_options) + { + if (*++param == 0) // point at the 1st/next option character + break; // end of short option group + + idx = 0; + while (usage[idx].shortopt != 0 && !instr(*param, usage[idx].shortopt)) + ++idx; + + if (param[1] == 0) // if the potential argument is separate + optarg = (have_more_args ? args[1] : 0); + else + // if the potential argument is attached + optarg = param + 1; + } + + const Descriptor* descriptor = &usage[idx]; + + if (descriptor->shortopt == 0) /************** unknown option ********************/ + { + // look for dummy entry (shortopt == "" and longopt == "") to use as Descriptor for unknown options + idx = 0; + while (usage[idx].shortopt != 0 && (usage[idx].shortopt[0] != 0 || usage[idx].longopt[0] != 0)) + ++idx; + descriptor = (usage[idx].shortopt == 0 ? 0 : &usage[idx]); + } + + if (descriptor != 0) + { + Option option(descriptor, param, optarg); + switch (descriptor->check_arg(option, print_errors)) + { + case ARG_ILLEGAL: + return false; // fatal + case ARG_OK: + // skip one element of the argument vector, if it's a separated argument + if (optarg != 0 && have_more_args && optarg == args[1]) + { + shift(args, nonops); + if (numargs > 0) + --numargs; + ++args; + } + + // No further short options are possible after an argument + handle_short_options = false; + + break; + case ARG_IGNORE: + case ARG_NONE: + option.arg = 0; + break; + } + + if (!action.perform(option)) + return false; + } + + } while (handle_short_options); + + shift(args, nonops); + ++args; + if (numargs > 0) + --numargs; + + } // while + + if (numargs > 0 && *args == 0) // It's a bug in the caller if numargs is greater than the actual number + numargs = 0; // of arguments, but as a service to the user we fix this if we spot it. + + if (numargs < 0) // if we don't know the number of remaining non-option arguments + { // we need to count them + numargs = 0; + while (args[numargs] != 0) + ++numargs; + } + + return action.finished(numargs + nonops, args - nonops); +} + +/** + * @internal + * @brief The implementation of option::printUsage(). + */ +struct PrintUsageImplementation +{ + /** + * @internal + * @brief Interface for Functors that write (part of) a string somewhere. + */ + struct IStringWriter + { + /** + * @brief Writes the given number of chars beginning at the given pointer somewhere. + */ + virtual void operator()(const char*, int) = 0; /// @note 2017-01-26 GRVS Made pure virtual. + }; + + /** + * @internal + * @brief Encapsulates a function with signature func(string, size) where + * string can be initialized with a const char* and size with an int. + */ + template + struct FunctionWriter: public IStringWriter + { + Function* write; + + virtual void operator()(const char* str, int size) override /// @note 2017-01-26 GRVS Added override. + { + (*write)(str, size); + } + + FunctionWriter(Function* w) : + write(w) + { + } + }; + + /** + * @internal + * @brief Encapsulates a reference to an object with a write(string, size) + * method like that of @c std::ostream. + */ + template + struct OStreamWriter: public IStringWriter + { + OStream& ostream; + + virtual void operator()(const char* str, int size) override + { + ostream.write(str, size); + } + + OStreamWriter(OStream& o) : + ostream(o) + { + } + }; + + /** + * @internal + * @brief Like OStreamWriter but encapsulates a @c const reference, which is + * typically a temporary object of a user class. + */ + template + struct TemporaryWriter: public IStringWriter + { + const Temporary& userstream; + + virtual void operator()(const char* str, int size) override + { + userstream.write(str, size); + } + + TemporaryWriter(const Temporary& u) : + userstream(u) + { + } + }; + + /** + * @internal + * @brief Encapsulates a function with the signature func(fd, string, size) (the + * signature of the @c write() system call) + * where fd can be initialized from an int, string from a const char* and size from an int. + */ + template + struct SyscallWriter: public IStringWriter + { + Syscall* write; + int fd; + + virtual void operator()(const char* str, int size) override + { + (*write)(fd, str, size); + } + + SyscallWriter(Syscall* w, int f) : + write(w), fd(f) + { + } + }; + + /** + * @internal + * @brief Encapsulates a function with the same signature as @c std::fwrite(). + */ + template + struct StreamWriter: public IStringWriter + { + Function* fwrite; + Stream* stream; + + virtual void operator()(const char* str, int size) override + { + (*fwrite)(str, size, 1, stream); + } + + StreamWriter(Function* w, Stream* s) : + fwrite(w), stream(s) + { + } + }; + + /** + * @internal + * @brief Sets i1 = max(i1, i2) + */ + static void upmax(int& i1, int i2) + { + i1 = (i1 >= i2 ? i1 : i2); + } + + /** + * @internal + * @brief Moves the "cursor" to column @c want_x assuming it is currently at column @c x + * and sets @c x=want_x . + * If x > want_x , a line break is output before indenting. + * + * @param write Spaces and possibly a line break are written via this functor to get + * the desired indentation @c want_x . + * @param[in,out] x the current indentation. Set to @c want_x by this method. + * @param want_x the desired indentation. + */ + static void indent(IStringWriter& write, int& x, int want_x) + { + int indent = want_x - x; + if (indent < 0) + { + write("\n", 1); + indent = want_x; + } + + if (indent > 0) + { + char space = ' '; + for (int i = 0; i < indent; ++i) + write(&space, 1); + x = want_x; + } + } + + /** + * @brief Returns true if ch is the unicode code point of a wide character. + * + * @note + * The following character ranges are treated as wide + * @code + * 1100..115F + * 2329..232A (just 2 characters!) + * 2E80..A4C6 except for 303F + * A960..A97C + * AC00..D7FB + * F900..FAFF + * FE10..FE6B + * FF01..FF60 + * FFE0..FFE6 + * 1B000...... + * @endcode + */ + static bool isWideChar(unsigned ch) + { + if (ch == 0x303F) + return false; + + return ((0x1100 <= ch && ch <= 0x115F) || (0x2329 <= ch && ch <= 0x232A) || (0x2E80 <= ch && ch <= 0xA4C6) + || (0xA960 <= ch && ch <= 0xA97C) || (0xAC00 <= ch && ch <= 0xD7FB) || (0xF900 <= ch && ch <= 0xFAFF) + || (0xFE10 <= ch && ch <= 0xFE6B) || (0xFF01 <= ch && ch <= 0xFF60) || (0xFFE0 <= ch && ch <= 0xFFE6) + || (0x1B000 <= ch)); + } + + /** + * @internal + * @brief Splits a @c Descriptor[] array into tables, rows, lines and columns and + * iterates over these components. + * + * The top-level organizational unit is the @e table. + * A table begins at a Descriptor with @c help!=NULL and extends up to + * a Descriptor with @c help==NULL. + * + * A table consists of @e rows. Due to line-wrapping and explicit breaks + * a row may take multiple lines on screen. Rows within the table are separated + * by \\n. They never cross Descriptor boundaries. This means a row ends either + * at \\n or the 0 at the end of the help string. + * + * A row consists of columns/cells. Columns/cells within a row are separated by \\t. + * Line breaks within a cell are marked by \\v. + * + * Rows in the same table need not have the same number of columns/cells. The + * extreme case are interjections, which are rows that contain neither \\t nor \\v. + * These are NOT treated specially by LinePartIterator, but they are treated + * specially by printUsage(). + * + * LinePartIterator iterates through the usage at 3 levels: table, row and part. + * Tables and rows are as described above. A @e part is a line within a cell. + * LinePartIterator iterates through 1st parts of all cells, then through the 2nd + * parts of all cells (if any),... @n + * Example: The row "1 \v 3 \t 2 \v 4" has 2 cells/columns and 4 parts. + * The parts will be returned in the order 1, 2, 3, 4. + * + * It is possible that some cells have fewer parts than others. In this case + * LinePartIterator will "fill up" these cells with 0-length parts. IOW, LinePartIterator + * always returns the same number of parts for each column. Note that this is different + * from the way rows and columns are handled. LinePartIterator does @e not guarantee that + * the same number of columns will be returned for each row. + * + */ + class LinePartIterator + { + const Descriptor* tablestart; //!< The 1st descriptor of the current table. + const Descriptor* rowdesc; //!< The Descriptor that contains the current row. + const char* rowstart; //!< Ptr to 1st character of current row within rowdesc->help. + const char* ptr; //!< Ptr to current part within the current row. + int col; //!< Index of current column. + int len; //!< Length of the current part (that ptr points at) in BYTES + int screenlen; //!< Length of the current part in screen columns (taking narrow/wide chars into account). + int max_line_in_block; //!< Greatest index of a line within the block. This is the number of \\v within the cell with the most \\vs. + int line_in_block; //!< Line index within the current cell of the current part. + int target_line_in_block; //!< Line index of the parts we should return to the user on this iteration. + bool hit_target_line; //!< Flag whether we encountered a part with line index target_line_in_block in the current cell. + + /** + * @brief Determines the byte and character lengths of the part at @ref ptr and + * stores them in @ref len and @ref screenlen respectively. + */ + void update_length() + { + screenlen = 0; + for (len = 0; ptr[len] != 0 && ptr[len] != '\v' && ptr[len] != '\t' && ptr[len] != '\n'; ++len) + { + ++screenlen; + unsigned ch = (unsigned char) ptr[len]; + if (ch > 0xC1) // everything <= 0xC1 (yes, even 0xC1 itself) is not a valid UTF-8 start byte + { + // int __builtin_clz (unsigned int x) + // Returns the number of leading 0-bits in x, starting at the most significant bit + unsigned mask = (unsigned) -1 >> __builtin_clz(ch ^ 0xff); + ch = ch & mask; // mask out length bits, we don't verify their correctness + while (((unsigned char) ptr[len + 1] ^ 0x80) <= 0x3F) // while next byte is continuation byte + { + ch = (ch << 6) ^ (unsigned char) ptr[len + 1] ^ 0x80; // add continuation to char code + ++len; + } + // ch is the decoded unicode code point + if (ch >= 0x1100 && isWideChar(ch)) // the test for 0x1100 is here to avoid the function call in the Latin case + ++screenlen; + } + } + } + + public: + //! @brief Creates an iterator for @c usage. + LinePartIterator(const Descriptor usage[]) : + tablestart(usage), rowdesc(0), rowstart(0), ptr(0), col(-1), len(0), max_line_in_block(0), line_in_block(0), + target_line_in_block(0), hit_target_line(true) + { + } + + /** + * @brief Moves iteration to the next table (if any). Has to be called once on a new + * LinePartIterator to move to the 1st table. + * @retval false if moving to next table failed because no further table exists. + */ + bool nextTable() + { + // If this is NOT the first time nextTable() is called after the constructor, + // then skip to the next table break (i.e. a Descriptor with help == 0) + if (rowdesc != 0) + { + while (tablestart->help != 0 && tablestart->shortopt != 0) + ++tablestart; + } + + // Find the next table after the break (if any) + while (tablestart->help == 0 && tablestart->shortopt != 0) + ++tablestart; + + restartTable(); + return rowstart != 0; + } + + /** + * @brief Reset iteration to the beginning of the current table. + */ + void restartTable() + { + rowdesc = tablestart; + rowstart = tablestart->help; + ptr = 0; + } + + /** + * @brief Moves iteration to the next row (if any). Has to be called once after each call to + * @ref nextTable() to move to the 1st row of the table. + * @retval false if moving to next row failed because no further row exists. + */ + bool nextRow() + { + if (ptr == 0) + { + restartRow(); + return rowstart != 0; + } + + while (*ptr != 0 && *ptr != '\n') + ++ptr; + + if (*ptr == 0) + { + if ((rowdesc + 1)->help == 0) // table break + return false; + + ++rowdesc; + rowstart = rowdesc->help; + } + else // if (*ptr == '\n') + { + rowstart = ptr + 1; + } + + restartRow(); + return true; + } + + /** + * @brief Reset iteration to the beginning of the current row. + */ + void restartRow() + { + ptr = rowstart; + col = -1; + len = 0; + screenlen = 0; + max_line_in_block = 0; + line_in_block = 0; + target_line_in_block = 0; + hit_target_line = true; + } + + /** + * @brief Moves iteration to the next part (if any). Has to be called once after each call to + * @ref nextRow() to move to the 1st part of the row. + * @retval false if moving to next part failed because no further part exists. + * + * See @ref LinePartIterator for details about the iteration. + */ + bool next() + { + if (ptr == 0) + return false; + + if (col == -1) + { + col = 0; + update_length(); + return true; + } + + ptr += len; + while (true) + { + switch (*ptr) + { + case '\v': + upmax(max_line_in_block, ++line_in_block); + ++ptr; + break; + case '\t': + if (!hit_target_line) // if previous column did not have the targetline + { // then "insert" a 0-length part + update_length(); + hit_target_line = true; + return true; + } + + hit_target_line = false; + line_in_block = 0; + ++col; + ++ptr; + break; + case 0: + case '\n': + if (!hit_target_line) // if previous column did not have the targetline + { // then "insert" a 0-length part + update_length(); + hit_target_line = true; + return true; + } + + if (++target_line_in_block > max_line_in_block) + { + update_length(); + return false; + } + + hit_target_line = false; + line_in_block = 0; + col = 0; + ptr = rowstart; + continue; + default: + ++ptr; + continue; + } // switch + + if (line_in_block == target_line_in_block) + { + update_length(); + hit_target_line = true; + return true; + } + } // while + } + + /** + * @brief Returns the index (counting from 0) of the column in which + * the part pointed to by @ref data() is located. + */ + int column() + { + return col; + } + + /** + * @brief Returns the index (counting from 0) of the line within the current column + * this part belongs to. + */ + int line() + { + return target_line_in_block; // NOT line_in_block !!! It would be wrong if !hit_target_line + } + + /** + * @brief Returns the length of the part pointed to by @ref data() in raw chars (not UTF-8 characters). + */ + int length() + { + return len; + } + + /** + * @brief Returns the width in screen columns of the part pointed to by @ref data(). + * Takes multi-byte UTF-8 sequences and wide characters into account. + */ + int screenLength() + { + return screenlen; + } + + /** + * @brief Returns the current part of the iteration. + */ + const char* data() + { + return ptr; + } + }; + + /** + * @internal + * @brief Takes input and line wraps it, writing out one line at a time so that + * it can be interleaved with output from other columns. + * + * The LineWrapper is used to handle the last column of each table as well as interjections. + * The LineWrapper is called once for each line of output. If the data given to it fits + * into the designated width of the last column it is simply written out. If there + * is too much data, an appropriate split point is located and only the data up to this + * split point is written out. The rest of the data is queued for the next line. + * That way the last column can be line wrapped and interleaved with data from + * other columns. The following example makes this clearer: + * @code + * Column 1,1 Column 2,1 This is a long text + * Column 1,2 Column 2,2 that does not fit into + * a single line. + * @endcode + * + * The difficulty in producing this output is that the whole string + * "This is a long text that does not fit into a single line" is the + * 1st and only part of column 3. In order to produce the above + * output the string must be output piecemeal, interleaved with + * the data from the other columns. + */ + class LineWrapper + { + static const int bufmask = 15; //!< Must be a power of 2 minus 1. + /** + * @brief Ring buffer for length component of pair (data, length). + */ + int lenbuf[bufmask + 1]; + /** + * @brief Ring buffer for data component of pair (data, length). + */ + const char* datbuf[bufmask + 1]; + /** + * @brief The indentation of the column to which the LineBuffer outputs. LineBuffer + * assumes that the indentation has already been written when @ref process() + * is called, so this value is only used when a buffer flush requires writing + * additional lines of output. + */ + int x; + /** + * @brief The width of the column to line wrap. + */ + int width; + int head; //!< @brief index for next write + int tail; //!< @brief index for next read - 1 (i.e. increment tail BEFORE read) + + /** + * @brief Multiple methods of LineWrapper may decide to flush part of the buffer to + * free up space. The contract of process() says that only 1 line is output. So + * this variable is used to track whether something has output a line. It is + * reset at the beginning of process() and checked at the end to decide if + * output has already occurred or is still needed. + */ + bool wrote_something; + + bool buf_empty() + { + return ((tail + 1) & bufmask) == head; + } + + bool buf_full() + { + return tail == head; + } + + void buf_store(const char* data, int len) + { + lenbuf[head] = len; + datbuf[head] = data; + head = (head + 1) & bufmask; + } + + //! @brief Call BEFORE reading ...buf[tail]. + void buf_next() + { + tail = (tail + 1) & bufmask; + } + + /** + * @brief Writes (data,len) into the ring buffer. If the buffer is full, a single line + * is flushed out of the buffer into @c write. + */ + void output(IStringWriter& write, const char* data, int len) + { + if (buf_full()) + write_one_line(write); + + buf_store(data, len); + } + + /** + * @brief Writes a single line of output from the buffer to @c write. + */ + void write_one_line(IStringWriter& write) + { + if (wrote_something) // if we already wrote something, we need to start a new line + { + write("\n", 1); + int _ = 0; + indent(write, _, x); + } + + if (!buf_empty()) + { + buf_next(); + write(datbuf[tail], lenbuf[tail]); + } + + wrote_something = true; + } + public: + + /** + * @brief Writes out all remaining data from the LineWrapper using @c write. + * Unlike @ref process() this method indents all lines including the first and + * will output a \\n at the end (but only if something has been written). + */ + void flush(IStringWriter& write) + { + if (buf_empty()) + return; + int _ = 0; + indent(write, _, x); + wrote_something = false; + while (!buf_empty()) + write_one_line(write); + write("\n", 1); + } + + /** + * @brief Process, wrap and output the next piece of data. + * + * process() will output at least one line of output. This is not necessarily + * the @c data passed in. It may be data queued from a prior call to process(). + * If the internal buffer is full, more than 1 line will be output. + * + * process() assumes that the a proper amount of indentation has already been + * output. It won't write any further indentation before the 1st line. If + * more than 1 line is written due to buffer constraints, the lines following + * the first will be indented by this method, though. + * + * No \\n is written by this method after the last line that is written. + * + * @param write where to write the data. + * @param data the new chunk of data to write. + * @param len the length of the chunk of data to write. + */ + void process(IStringWriter& write, const char* data, int len) + { + wrote_something = false; + + while (len > 0) + { + if (len <= width) // quick test that works because utf8width <= len (all wide chars have at least 2 bytes) + { + output(write, data, len); + len = 0; + } + else // if (len > width) it's possible (but not guaranteed) that utf8len > width + { + int utf8width = 0; + int maxi = 0; + while (maxi < len && utf8width < width) + { + int charbytes = 1; + unsigned ch = (unsigned char) data[maxi]; + if (ch > 0xC1) // everything <= 0xC1 (yes, even 0xC1 itself) is not a valid UTF-8 start byte + { + // int __builtin_clz (unsigned int x) + // Returns the number of leading 0-bits in x, starting at the most significant bit + unsigned mask = (unsigned) -1 >> __builtin_clz(ch ^ 0xff); + ch = ch & mask; // mask out length bits, we don't verify their correctness + while ((maxi + charbytes < len) && // + (((unsigned char) data[maxi + charbytes] ^ 0x80) <= 0x3F)) // while next byte is continuation byte + { + ch = (ch << 6) ^ (unsigned char) data[maxi + charbytes] ^ 0x80; // add continuation to char code + ++charbytes; + } + // ch is the decoded unicode code point + if (ch >= 0x1100 && isWideChar(ch)) // the test for 0x1100 is here to avoid the function call in the Latin case + { + if (utf8width + 2 > width) + break; + ++utf8width; + } + } + ++utf8width; + maxi += charbytes; + } + + // data[maxi-1] is the last byte of the UTF-8 sequence of the last character that fits + // onto the 1st line. If maxi == len, all characters fit on the line. + + if (maxi == len) + { + output(write, data, len); + len = 0; + } + else // if (maxi < len) at least 1 character (data[maxi] that is) doesn't fit on the line + { + int i; + for (i = maxi; i >= 0; --i) + if (data[i] == ' ') + break; + + if (i >= 0) + { + output(write, data, i); + data += i + 1; + len -= i + 1; + } + else // did not find a space to split at => split before data[maxi] + { // data[maxi] is always the beginning of a character, never a continuation byte + output(write, data, maxi); + data += maxi; + len -= maxi; + } + } + } + } + if (!wrote_something) // if we didn't already write something to make space in the buffer + write_one_line(write); // write at most one line of actual output + } + + /** + * @brief Constructs a LineWrapper that wraps its output to fit into + * screen columns @c x1 (incl.) to @c x2 (excl.). + * + * @c x1 gives the indentation LineWrapper uses if it needs to indent. + */ + LineWrapper(int x1, int x2) : + x(x1), width(x2 - x1), head(0), tail(bufmask) + { + if (width < 2) // because of wide characters we need at least width 2 or the code breaks + width = 2; + } + }; + + /** + * @internal + * @brief This is the implementation that is shared between all printUsage() templates. + * Because all printUsage() templates share this implementation, there is no template bloat. + */ + static void printUsage(IStringWriter& write, const Descriptor usage[], int width = 80, // + int last_column_min_percent = 50, int last_column_own_line_max_percent = 75) + { + if (width < 1) // protect against nonsense values + width = 80; + + if (width > 10000) // protect against overflow in the following computation + width = 10000; + + int last_column_min_width = ((width * last_column_min_percent) + 50) / 100; + int last_column_own_line_max_width = ((width * last_column_own_line_max_percent) + 50) / 100; + if (last_column_own_line_max_width == 0) + last_column_own_line_max_width = 1; + + LinePartIterator part(usage); + while (part.nextTable()) + { + + /***************** Determine column widths *******************************/ + + const int maxcolumns = 8; // 8 columns are enough for everyone + int col_width[maxcolumns]; + int lastcolumn; + int leftwidth; + int overlong_column_threshold = 10000; + do + { + lastcolumn = 0; + for (int i = 0; i < maxcolumns; ++i) + col_width[i] = 0; + + part.restartTable(); + while (part.nextRow()) + { + while (part.next()) + { + if (part.column() < maxcolumns) + { + upmax(lastcolumn, part.column()); + if (part.screenLength() < overlong_column_threshold) + // We don't let rows that don't use table separators (\t or \v) influence + // the width of column 0. This allows the user to interject section headers + // or explanatory paragraphs that do not participate in the table layout. + if (part.column() > 0 || part.line() > 0 || part.data()[part.length()] == '\t' + || part.data()[part.length()] == '\v') + upmax(col_width[part.column()], part.screenLength()); + } + } + } + + /* + * If the last column doesn't fit on the same + * line as the other columns, we can fix that by starting it on its own line. + * However we can't do this for any of the columns 0..lastcolumn-1. + * If their sum exceeds the maximum width we try to fix this by iteratively + * ignoring the widest line parts in the width determination until + * we arrive at a series of column widths that fit into one line. + * The result is a layout where everything is nicely formatted + * except for a few overlong fragments. + * */ + + leftwidth = 0; + overlong_column_threshold = 0; + for (int i = 0; i < lastcolumn; ++i) + { + leftwidth += col_width[i]; + upmax(overlong_column_threshold, col_width[i]); + } + + } while (leftwidth > width); + + /**************** Determine tab stops and last column handling **********************/ + + int tabstop[maxcolumns]; + tabstop[0] = 0; + for (int i = 1; i < maxcolumns; ++i) + tabstop[i] = tabstop[i - 1] + col_width[i - 1]; + + int rightwidth = width - tabstop[lastcolumn]; + bool print_last_column_on_own_line = false; + if (rightwidth < last_column_min_width && // if we don't have the minimum requested width for the last column + ( col_width[lastcolumn] == 0 || // and all last columns are > overlong_column_threshold + rightwidth < col_width[lastcolumn] // or there is at least one last column that requires more than the space available + ) + ) + { + print_last_column_on_own_line = true; + rightwidth = last_column_own_line_max_width; + } + + // If lastcolumn == 0 we must disable print_last_column_on_own_line because + // otherwise 2 copies of the last (and only) column would be output. + // Actually this is just defensive programming. It is currently not + // possible that lastcolumn==0 and print_last_column_on_own_line==true + // at the same time, because lastcolumn==0 => tabstop[lastcolumn] == 0 => + // rightwidth==width => rightwidth>=last_column_min_width (unless someone passes + // a bullshit value >100 for last_column_min_percent) => the above if condition + // is false => print_last_column_on_own_line==false + if (lastcolumn == 0) + print_last_column_on_own_line = false; + + LineWrapper lastColumnLineWrapper(width - rightwidth, width); + LineWrapper interjectionLineWrapper(0, width); + + part.restartTable(); + + /***************** Print out all rows of the table *************************************/ + + while (part.nextRow()) + { + int x = -1; + while (part.next()) + { + if (part.column() > lastcolumn) + continue; // drop excess columns (can happen if lastcolumn == maxcolumns-1) + + if (part.column() == 0) + { + if (x >= 0) + write("\n", 1); + x = 0; + } + + indent(write, x, tabstop[part.column()]); + + if ((part.column() < lastcolumn) + && (part.column() > 0 || part.line() > 0 || part.data()[part.length()] == '\t' + || part.data()[part.length()] == '\v')) + { + write(part.data(), part.length()); + x += part.screenLength(); + } + else // either part.column() == lastcolumn or we are in the special case of + // an interjection that doesn't contain \v or \t + { + // NOTE: This code block is not necessarily executed for + // each line, because some rows may have fewer columns. + + LineWrapper& lineWrapper = (part.column() == 0) ? interjectionLineWrapper : lastColumnLineWrapper; + + if (!print_last_column_on_own_line || part.column() != lastcolumn) + lineWrapper.process(write, part.data(), part.length()); + } + } // while + + if (print_last_column_on_own_line) + { + part.restartRow(); + while (part.next()) + { + if (part.column() == lastcolumn) + { + write("\n", 1); + int _ = 0; + indent(write, _, width - rightwidth); + lastColumnLineWrapper.process(write, part.data(), part.length()); + } + } + } + + write("\n", 1); + lastColumnLineWrapper.flush(write); + interjectionLineWrapper.flush(write); + } + } + } + +} +; + +/** + * @brief Outputs a nicely formatted usage string with support for multi-column formatting + * and line-wrapping. + * + * printUsage() takes the @c help texts of a Descriptor[] array and formats them into + * a usage message, wrapping lines to achieve the desired output width. + * + * Table formatting: + * + * Aside from plain strings which are simply line-wrapped, the usage may contain tables. Tables + * are used to align elements in the output. + * + * @code + * // Without a table. The explanatory texts are not aligned. + * -c, --create |Creates something. + * -k, --kill |Destroys something. + * + * // With table formatting. The explanatory texts are aligned. + * -c, --create |Creates something. + * -k, --kill |Destroys something. + * @endcode + * + * Table formatting removes the need to pad help texts manually with spaces to achieve + * alignment. To create a table, simply insert \\t (tab) characters to separate the cells + * within a row. + * + * @code + * const option::Descriptor usage[] = { + * {..., "-c, --create \tCreates something." }, + * {..., "-k, --kill \tDestroys something." }, ... + * @endcode + * + * Note that you must include the minimum amount of space desired between cells yourself. + * Table formatting will insert further spaces as needed to achieve alignment. + * + * You can insert line breaks within cells by using \\v (vertical tab). + * + * @code + * const option::Descriptor usage[] = { + * {..., "-c,\v--create \tCreates\vsomething." }, + * {..., "-k,\v--kill \tDestroys\vsomething." }, ... + * + * // results in + * + * -c, Creates + * --create something. + * -k, Destroys + * --kill something. + * @endcode + * + * You can mix lines that do not use \\t or \\v with those that do. The plain + * lines will not mess up the table layout. Alignment of the table columns will + * be maintained even across these interjections. + * + * @code + * const option::Descriptor usage[] = { + * {..., "-c, --create \tCreates something." }, + * {..., "----------------------------------" }, + * {..., "-k, --kill \tDestroys something." }, ... + * + * // results in + * + * -c, --create Creates something. + * ---------------------------------- + * -k, --kill Destroys something. + * @endcode + * + * You can have multiple tables within the same usage whose columns are + * aligned independently. Simply insert a dummy Descriptor with @c help==0. + * + * @code + * const option::Descriptor usage[] = { + * {..., "Long options:" }, + * {..., "--very-long-option \tDoes something long." }, + * {..., "--ultra-super-mega-long-option \tTakes forever to complete." }, + * {..., 0 }, // ---------- table break ----------- + * {..., "Short options:" }, + * {..., "-s \tShort." }, + * {..., "-q \tQuick." }, ... + * + * // results in + * + * Long options: + * --very-long-option Does something long. + * --ultra-super-mega-long-option Takes forever to complete. + * Short options: + * -s Short. + * -q Quick. + * + * // Without the table break it would be + * + * Long options: + * --very-long-option Does something long. + * --ultra-super-mega-long-option Takes forever to complete. + * Short options: + * -s Short. + * -q Quick. + * @endcode + * + * Output methods: + * + * Because TheLeanMeanC++Option parser is freestanding, you have to provide the means for + * output in the first argument(s) to printUsage(). Because printUsage() is implemented as + * a set of template functions, you have great flexibility in your choice of output + * method. The following example demonstrates typical uses. Anything that's similar enough + * will work. + * + * @code + * #include // write() + * #include // cout + * #include // ostringstream + * #include // fwrite() + * using namespace std; + * + * void my_write(const char* str, int size) { + * fwrite(str, size, 1, stdout); + * } + * + * struct MyWriter { + * void write(const char* buf, size_t size) const { + * fwrite(str, size, 1, stdout); + * } + * }; + * + * struct MyWriteFunctor { + * void operator()(const char* buf, size_t size) { + * fwrite(str, size, 1, stdout); + * } + * }; + * ... + * printUsage(my_write, usage); // custom write function + * printUsage(MyWriter(), usage); // temporary of a custom class + * MyWriter writer; + * printUsage(writer, usage); // custom class object + * MyWriteFunctor wfunctor; + * printUsage(&wfunctor, usage); // custom functor + * printUsage(write, 1, usage); // write() to file descriptor 1 + * printUsage(cout, usage); // an ostream& + * printUsage(fwrite, stdout, usage); // fwrite() to stdout + * ostringstream sstr; + * printUsage(sstr, usage); // an ostringstream& + * + * @endcode + * + * @par Notes: + * @li the @c write() method of a class that is to be passed as a temporary + * as @c MyWriter() is in the example, must be a @c const method, because + * temporary objects are passed as const reference. This only applies to + * temporary objects that are created and destroyed in the same statement. + * If you create an object like @c writer in the example, this restriction + * does not apply. + * @li a functor like @c MyWriteFunctor in the example must be passed as a pointer. + * This differs from the way functors are passed to e.g. the STL algorithms. + * @li All printUsage() templates are tiny wrappers around a shared non-template implementation. + * So there's no penalty for using different versions in the same program. + * @li printUsage() always interprets Descriptor::help as UTF-8 and always produces UTF-8-encoded + * output. If your system uses a different charset, you must do your own conversion. You + * may also need to change the font of the console to see non-ASCII characters properly. + * This is particularly true for Windows. + * @li @b Security @b warning: Do not insert untrusted strings (such as user-supplied arguments) + * into the usage. printUsage() has no protection against malicious UTF-8 sequences. + * + * @param prn The output method to use. See the examples above. + * @param usage the Descriptor[] array whose @c help texts will be formatted. + * @param width the maximum number of characters per output line. Note that this number is + * in actual characters, not bytes. printUsage() supports UTF-8 in @c help and will + * count multi-byte UTF-8 sequences properly. Asian wide characters are counted + * as 2 characters. + * @param last_column_min_percent (0-100) The minimum percentage of @c width that should be available + * for the last column (which typically contains the textual explanation of an option). + * If less space is available, the last column will be printed on its own line, indented + * according to @c last_column_own_line_max_percent. + * @param last_column_own_line_max_percent (0-100) If the last column is printed on its own line due to + * less than @c last_column_min_percent of the width being available, then only + * @c last_column_own_line_max_percent of the extra line(s) will be used for the + * last column's text. This ensures an indentation. See example below. + * + * @code + * // width=20, last_column_min_percent=50 (i.e. last col. min. width=10) + * --3456789 1234567890 + * 1234567890 + * + * // width=20, last_column_min_percent=75 (i.e. last col. min. width=15) + * // last_column_own_line_max_percent=75 + * --3456789 + * 123456789012345 + * 67890 + * + * // width=20, last_column_min_percent=75 (i.e. last col. min. width=15) + * // last_column_own_line_max_percent=33 (i.e. max. 5) + * --3456789 + * 12345 + * 67890 + * 12345 + * 67890 + * @endcode + */ +template +void printUsage(OStream& prn, const Descriptor usage[], int width = 80, int last_column_min_percent = 50, + int last_column_own_line_max_percent = 75) +{ + PrintUsageImplementation::OStreamWriter write(prn); + PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent); +} + +template +void printUsage(Function* prn, const Descriptor usage[], int width = 80, int last_column_min_percent = 50, + int last_column_own_line_max_percent = 75) +{ + PrintUsageImplementation::FunctionWriter write(prn); + PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent); +} + +template +void printUsage(const Temporary& prn, const Descriptor usage[], int width = 80, int last_column_min_percent = 50, + int last_column_own_line_max_percent = 75) +{ + PrintUsageImplementation::TemporaryWriter write(prn); + PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent); +} + +template +void printUsage(Syscall* prn, int fd, const Descriptor usage[], int width = 80, int last_column_min_percent = 50, + int last_column_own_line_max_percent = 75) +{ + PrintUsageImplementation::SyscallWriter write(prn, fd); + PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent); +} + +template +void printUsage(Function* prn, Stream* stream, const Descriptor usage[], int width = 80, int last_column_min_percent = + 50, + int last_column_own_line_max_percent = 75) +{ + PrintUsageImplementation::StreamWriter write(prn, stream); + PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent); +} + +} +// namespace option + +#endif /* OPTIONPARSER_H_ */ diff --git a/third_party/optionparser-1.4/src/printUsage.h b/third_party/optionparser-1.4/src/printUsage.h new file mode 100644 index 00000000..ebe313c8 --- /dev/null +++ b/third_party/optionparser-1.4/src/printUsage.h @@ -0,0 +1,11 @@ +/** + * @file + * @brief Dummy file for documentation purposes. + */ + +/** + * @brief @ref option::printUsage() formats the usage message with column alignment and line wrapping. + */ +class UsageMsg{ + // Dummy file to get an entry for printUsage() in Classes. +}; diff --git a/third_party/optionparser-1.4/src/testodr1.cc b/third_party/optionparser-1.4/src/testodr1.cc new file mode 100644 index 00000000..1ca677ef --- /dev/null +++ b/third_party/optionparser-1.4/src/testodr1.cc @@ -0,0 +1,50 @@ +/* Written 2012 by Matthias S. Benkmann + * + * The author hereby waives all copyright and related rights to the contents + * of this example file (testodr1.cc) to the extent possible under the law. + */ + +/** + * @file + * @brief Test for multiple definition errors. + * + * @note + * This program is for developing TLMC++OP. It is neither an example nor a functionality test. + * Do not worry if it doesn't compile or run on your platform. + * + * @ref testodr1.cc and @ref testodr2.cc test optionparser.h for + * violations of the one definition rule, both at compile-time and at + * link-time. IOW, they test if optionparser.h can be included + * multiple times as well as that multiple object files that include + * it can be linked together. + * + */ + +#include "optionparser.h" +#include "optionparser.h" //intentionally included twice + +#include + +using option::Option; +using option::Descriptor; + +extern const Descriptor usage[]; + +extern bool bar(int argc, const char* argv[]) +{ + printUsage(std::fwrite, stdout, usage); + option::Stats stats(usage, argc, argv); + option::Option buffer [stats.buffer_max]; + option::Option options[stats.options_max]; + option::Parser parse(usage, argc, argv, options, buffer); + return parse.error(); +} + +int main() +{ + Descriptor d = usage[0]; + std::printf("%s",d.shortopt); +} + + + diff --git a/third_party/optionparser-1.4/src/testodr2.cc b/third_party/optionparser-1.4/src/testodr2.cc new file mode 100644 index 00000000..979d3a55 --- /dev/null +++ b/third_party/optionparser-1.4/src/testodr2.cc @@ -0,0 +1,39 @@ +/* Written 2012 by Matthias S. Benkmann + * + * The author hereby waives all copyright and related rights to the contents + * of this example file (testodr2.cc) to the extent possible under the law. + */ + +/** + * @file + * @brief Test for multiple definition errors. + * @copydoc testodr1.cc + */ + +#include "optionparser.h" + +#include + +using option::Descriptor; +using option::Arg; +enum OptionIndex {CREATE}; +enum OptionType {DISABLE, ENABLE, OTHER}; + +extern const Descriptor usage[] = { + { CREATE, OTHER, + "c", "create", + Arg::None, + "--create\t\t\tTells the program to create something." + } + }; + +extern bool foo(int argc, const char* argv[]) +{ + printUsage(std::fwrite, stdout, usage); + option::Stats stats(usage, argc, argv); + option::Option buffer [stats.buffer_max]; + option::Option options[stats.options_max]; + option::Parser parse(usage, argc, argv, options, buffer); + return parse.error(); +} + diff --git a/third_party/optionparser-1.4/src/testparse.cpp b/third_party/optionparser-1.4/src/testparse.cpp new file mode 100644 index 00000000..7969166f --- /dev/null +++ b/third_party/optionparser-1.4/src/testparse.cpp @@ -0,0 +1,368 @@ +/* Written 2012 by Matthias S. Benkmann + * + * The author hereby waives all copyright and related rights to the contents + * of this example file (testparse.cpp) to the extent possible under the law. + */ + +/** + * @file + * @brief Test program for option::Stats and option::Parser. + * + * @note + * This program is for developing TLMC++OP. It is neither an example nor a functionality test. + * Do not worry if it doesn't compile or run on your platform. + * + */ + +/** + * @mainpage + * @copydetails optionparser.h + */ + +#include +#include + +#include "optionparser.h" + +using option::Option; +using option::Descriptor; +using option::Parser; +using option::Stats; +using option::ArgStatus; + +struct Arg: public option::Arg +{ + static ArgStatus Required(const Option& option, bool) + { + return option.arg == 0 ? option::ARG_ILLEGAL : option::ARG_OK; + } + static ArgStatus Empty(const Option& option, bool) + { + return (option.arg == 0 || option.arg[0] == 0) ? option::ARG_OK : option::ARG_IGNORE; + } +}; + +char* gettext(const char * msgid) +{ + return (char*) msgid; +} + +const Descriptor empty_usage[] = { { 0, 0, 0, 0, 0, 0 } }; + +const Descriptor minimal_usage[] = // + { { 0, 0, "x", "", Arg::None, 0 }, // + { 0, 0, 0, 0, 0, 0 } }; + +const Descriptor optional_usage[] = // + { { 0, 0, "f", "", Arg::Required, 0 }, // + { 0, 0, 0, 0, 0, 0 } }; + +const Descriptor gettext_usage[] = // + { { 0, 0, "f", "", Arg::Required, gettext("This is a test") }, // + { 0, 0, 0, 0, 0, 0 } }; + +enum OptionIndex +{ + UNKNOWN, FOO, VERBOSE, X, ABBREVIATE, EMPTY +}; +enum OptionType +{ + UNUSED = 0, DISABLED = 1, ENABLED = 2 +}; + +const Descriptor multi_usage[] = // + { { UNKNOWN, 0, "", "", Arg::None, 0 }, // UNKNOWN option catch-all + { FOO, ENABLED, "", "enable-foo", Arg::None, 0 }, // FOO enable + { FOO, DISABLED, "", "disable-foo", Arg::None, 0 }, // FOO disable + { VERBOSE, 0, "v", "verbose", Arg::None, 0 }, // VERBOSE (counted option) + { X, 0, "X", "X", Arg::Required, 0 }, // -X, -X , -X=, --X= + { ABBREVIATE, 0, "", "abbreviate-me", Arg::None, 0 }, // ABBREVIATE + { EMPTY, 0, "", "emptyarg", Arg::Empty, 0 }, // EMPTY (ignores arguments that are not "") + { 0, 0, 0, 0, 0, 0 } }; + +const char* empty_args[] = { 0 }; +const char* non_options[] = { "1", "2", "3", (const char*) -1 }; +const char* unknown_option[] = { "--unknown", "nonoption", 0 }; +const char* lone_minus[] = { "-f", "-", "-", 0 }; +const char* lone_doubleminus[] = { "--", 0 }; + +// NOTE: (const char*) -1 is used to cause a segfault should this element be dereferenced. +// 0 is not used here, because the parser explicitly checks for 0 which could mask bugs. +// If a number of arguments >= 0 is passed, the parser is supposed to honor that and never +// dereference an element beyond the last. +const char* multi1[] = + { "--enable-foo", "--unknown1", "-u", "-vX", "xyzzy", "--", "--strangefilename", (const char*) -1 }; +const char* multi2[] = { "-vvXfoo", "-X", "bar", "-X=foobar", "-X", "", "--disable-foo", "-v", (const char*) -1 }; +const char* multi3[] = { "-abbr", "-abb", "--emptyarg", "-verbose", "--emptyarg", "", "--emptyarg=", "nonoption1", + "nonoption2", (const char*) -1 }; + +const char* illegal[] = { "-X", 0 }; +const char* reorder[] = { "-X", "--", "-", "-X", "--", "foo", "-v", "--", "bar", "--", 0 }; +const char* reorder2[] = { "-X", "--", "-", "-X", "--", "-", 0 }; + +int count(const char** args) +{ + for (int c = 0;; ++c) + if (args[c] == (const char*) -1) + return c; +} + +bool eq(const char* s1, const char* s2) +{ + if (s1 == s2) + return true; + + if (s1 == 0 || s2 == 0) + return false; + + while (*s1 != 0 && *s2 != 0) + { + ++s1; + ++s2; + } + + return *s1 == *s2; +} + +int main() +{ + { + Stats stats(empty_usage, -1, empty_args); + stats.add(empty_usage, 0, empty_args); + assert(stats.buffer_max == 1); + assert(stats.options_max == 1); + Option buffer[stats.buffer_max]; + Option options[stats.options_max]; + Parser parse(empty_usage, 99, empty_args, options, buffer); + parse.parse(empty_usage, -1, empty_args, options, buffer); + assert(parse.optionsCount() == 0); + assert(parse.nonOptionsCount() == 0); + assert(!buffer[0]); + assert(!options[0]); + assert(buffer[0].count()==0); + assert(parse.nonOptions()==0); + + stats.add(empty_usage, 3, non_options); + assert(stats.buffer_max == 1); + assert(stats.options_max == 1); + parse.parse(empty_usage, 3, non_options, options, buffer); + assert(parse.optionsCount() == 0); + assert(parse.nonOptionsCount() == 3); + assert(!buffer[0]); + assert(!options[0]); + assert(parse.nonOptions()==&non_options[0]); + + stats.add(minimal_usage, -1, unknown_option); + assert(stats.buffer_max == 1); + assert(stats.options_max == 2); + parse.parse(minimal_usage, -1, unknown_option, options, buffer); + assert(parse.optionsCount() == 0); + assert(parse.nonOptionsCount() == 1); + assert(!buffer[0]); + assert(!options[0]); + assert(parse.nonOptions()==&unknown_option[1]); + } + { + Stats stats(gettext_usage, -1, lone_minus); + Stats stats2; + stats2.add(gettext_usage, -1, lone_minus); + assert(stats.buffer_max == 2); + assert(stats.options_max == 2); + assert(stats2.buffer_max == 2); + assert(stats2.options_max == 2); + Option buffer[stats.buffer_max]; + Option options[stats.options_max]; + Parser parse; + parse.parse(gettext_usage, -1, lone_minus, options, buffer); + assert(parse.optionsCount() == 1); + assert(parse.nonOptionsCount() == 1); + assert(parse.nonOptions()==&lone_minus[2]); + assert(options[0]); + assert(buffer[0]); + assert(options[0].count()==1); + assert(options[0].isFirst()); + assert(options[0].isLast()); + assert(options[0].first() == options[0]); + assert(options[0].last() == options[0]); + assert(options[0].prevwrap() == &options[0]); + assert(options[0].nextwrap() == &options[0]); + assert(options[0].prev() == 0); + assert(options[0].next() == 0); + assert(options[0].desc == &gettext_usage[0]); + assert(eq(options[0].name, "f")); + assert(eq(options[0].arg, "-")); + } + { + Stats stats(optional_usage, -1, lone_minus); + Stats stats2; + stats2.add(optional_usage, -1, lone_minus); + assert(stats.buffer_max == 2); + assert(stats.options_max == 2); + assert(stats2.buffer_max == 2); + assert(stats2.options_max == 2); + Option buffer[stats.buffer_max]; + Option options[stats.options_max]; + Parser parse; + parse.parse(optional_usage, -1, lone_minus, options, buffer); + assert(parse.optionsCount() == 1); + assert(parse.nonOptionsCount() == 1); + assert(parse.nonOptions()==&lone_minus[2]); + assert(options[0]); + assert(buffer[0]); + assert(options[0].count()==1); + assert(options[0].isFirst()); + assert(options[0].isLast()); + assert(options[0].first() == options[0]); + assert(options[0].last() == options[0]); + assert(options[0].prevwrap() == &options[0]); + assert(options[0].nextwrap() == &options[0]); + assert(options[0].prev() == 0); + assert(options[0].next() == 0); + assert(options[0].desc == &optional_usage[0]); + assert(eq(options[0].name, "f")); + assert(eq(options[0].arg, "-")); + } + { + Stats stats; + stats.add(minimal_usage, -1, lone_doubleminus); + assert(stats.buffer_max == 1); + assert(stats.options_max == 2); + Option buffer[stats.buffer_max]; + Option options[stats.options_max]; + Parser parse(minimal_usage, -1, lone_doubleminus, options, buffer); + assert(parse.optionsCount() == 0); + assert(parse.nonOptionsCount() == 0); + assert(!buffer[0]); + assert(!options[0]); + assert(parse.nonOptions()==0); + } + { + Stats stats; + stats.add(multi_usage, count(multi1), multi1, 4, true); + assert(stats.buffer_max == 6); + assert(stats.options_max == 7); + stats.add(multi_usage, count(multi2), multi2, 4, true); + assert(stats.buffer_max == 14); + assert(stats.options_max == 7); + stats.add(multi_usage, count(multi3), multi3, 4, true); + assert(stats.buffer_max == 22); + assert(stats.options_max == 7); + Option buffer[stats.buffer_max]; + Option options[stats.options_max]; + assert(options[FOO].last()->type() == UNUSED); + assert(options[ABBREVIATE].count()==0); + Parser parse; + assert(!parse.error()); + + parse.parse(multi_usage, count(multi1), multi1, options, buffer, 4, true); + assert(!parse.error()); + assert(parse.optionsCount() == 5); + assert(parse.nonOptionsCount() == 1); + assert(eq(parse.nonOptions()[0],"--strangefilename")); + assert(options[FOO].last()->type() == ENABLED); + assert(eq(options[FOO].last()->name, "--enable-foo")); + assert(options[FOO].last()->arg == 0); + assert(options[UNKNOWN].count() == 2); + assert(eq(options[UNKNOWN].first()->name,"--unknown1")); + assert(eq(options[UNKNOWN].last()->name,"u")); + assert(options[UNKNOWN].first()->arg == 0); + assert(options[UNKNOWN].last()->arg == 0); + assert(options[VERBOSE].count()==1); + assert(options[VERBOSE].arg==0); + assert(options[VERBOSE].name[0] == 'v' && options[VERBOSE].namelen == 1); + assert(eq(options[X].arg,"xyzzy")); + assert(eq(options[X].name,"X")); + + parse.parse(multi_usage, count(multi2), multi2, options, buffer, 4, true); + assert(!parse.error()); + assert(parse.optionsCount() == 13); + assert(parse.nonOptionsCount() == 1); + assert(eq(parse.nonOptions()[0],"--strangefilename")); + assert(options[FOO].last()->type() == DISABLED); + assert(options[FOO].last()->arg == 0); + assert(options[UNKNOWN].count() == 2); + assert(eq(options[UNKNOWN].first()->name,"--unknown1")); + assert(eq(options[UNKNOWN].last()->name,"u")); + assert(options[VERBOSE].count()==4); + assert(options[X].count()==5); + const char* Xargs[] = { "xyzzy", "foo", "bar", "foobar", "", "sentinel" }; + const char** Xarg = &Xargs[0]; + for (Option* Xiter = options[X]; Xiter != 0; Xiter = Xiter->next()) + assert(eq(Xiter->arg, *Xarg++)); + + assert(!options[ABBREVIATE]); + parse.parse(multi_usage, count(multi3), multi3, options, buffer, 4, true); + assert(!parse.error()); + assert(parse.optionsCount() == 21); + assert(parse.nonOptionsCount() == 2); + assert(eq(parse.nonOptions()[0],"nonoption1")); + assert(eq(parse.nonOptions()[1],"nonoption2")); + assert(options[ABBREVIATE]); + assert(options[EMPTY].count()==3); + assert(options[EMPTY].first()->arg==0); + assert(eq(options[EMPTY].last()->arg,"")); + assert(eq(options[EMPTY].last()->prev()->arg,"")); + assert(options[FOO].last()->type() == DISABLED); + assert(options[UNKNOWN].count() == 5); + assert(eq(options[UNKNOWN].first()->name,"--unknown1")); + assert(options[UNKNOWN].first()->arg == 0); + assert(eq(options[UNKNOWN].last()->name,"b")); + assert(options[VERBOSE].count()==5); + assert(options[X].count()==5); + Xarg = &Xargs[0]; + for (Option* Xiter = options[X]; Xiter != 0; Xiter = Xiter->next()) + assert(eq(Xiter->arg, *Xarg++)); + + for (Option* opt = buffer[0]; *opt; ++opt) + if (opt->desc->check_arg != Arg::Required && opt->desc->check_arg != Arg::Empty) + assert(opt->arg == 0); + } + { + Option buffer[2]; + Option options[20]; + Parser parse; + assert(!parse.error()); + parse.parse(multi_usage, -1, illegal, options, buffer, 0, false, 2); + assert(parse.error()); + } + { + Stats stats(multi_usage, count(multi3), multi3, 0, true); + const int bufmax = 3; + Option buffer[bufmax]; + Option options[stats.options_max]; + assert(!options[ABBREVIATE]); + Parser parse(multi_usage, count(multi3), multi3, options, buffer, 4, true, bufmax); + assert(!parse.error()); + assert(parse.optionsCount() == bufmax); + assert(parse.nonOptionsCount() == 2); + assert(eq(parse.nonOptions()[0],"nonoption1")); + assert(eq(parse.nonOptions()[1],"nonoption2")); + assert(options[ABBREVIATE]); + assert(options[UNKNOWN].count() == 2); // because of buxmax the 2nd 'b' cannot be stored + assert(options[UNKNOWN].first()->name[0] == 'a' && options[UNKNOWN].first()->namelen == 1); + assert(options[UNKNOWN].first()->arg == 0); + assert(eq(options[UNKNOWN].last()->name,"bb")); + } + { + Stats stats(true, multi_usage, -1, reorder); + Option buffer[stats.buffer_max]; + Option options[stats.options_max]; + Parser parse(true, multi_usage, -1, reorder, options, buffer); + assert(!parse.error()); + assert(parse.optionsCount() == 3); + assert(parse.nonOptionsCount() == 4); + assert(parse.nonOptions() == &reorder[6]); + } + { + Option buffer[10]; + Option options[10]; + Parser parse(true, multi_usage, 666, reorder2, options, buffer, 0, false, 10); + assert(!parse.error()); + assert(parse.optionsCount() == 2); + assert(parse.nonOptionsCount() == 2); + } + + fprintf(stdout, "All tests passed.\n"); + return 0; +} + diff --git a/third_party/optionparser-1.4/src/testprintusage.cpp b/third_party/optionparser-1.4/src/testprintusage.cpp new file mode 100644 index 00000000..f9c0cd08 --- /dev/null +++ b/third_party/optionparser-1.4/src/testprintusage.cpp @@ -0,0 +1,167 @@ +/* Written 2012 by Matthias S. Benkmann + * + * The author hereby waives all copyright and related rights to the contents + * of this example file (testprintusage.cpp) to the extent possible under the law. + */ + +/** + * @file + * @brief Test program for the option::printUsage() function. + * + * @note + * This program is for developing TLMC++OP. It is neither an example nor a functionality test. + * Do not worry if it doesn't compile or run on your platform. + */ + +#include +#include +#include +#include + +#include "optionparser.h" + +using namespace std; +using option::Descriptor; +using option::Arg; + +const Descriptor test_vtabs[] = { + {0,0,"","",Arg::None, "Cölüümn 1 line ı\vColumn 1 line 2\vColumn 1 line 3 \t\vColumn 2 line 2 \tColumn 3 line 1\v\vColumn 3 line 3 "}, + {0,0,0,0,0,0} +}; + +const Descriptor test_columns[] = { + {0,0,"","",Arg::None, "Column 1 line 1 \t\tColumn 3 line 1\n" + "Column 1 line 2 \tColumn 2 line 2 \tColumn 3 line 2\n" + "Column 1 line 3 \t\tColumn 3 line 3" }, + {0,0,0,0,0,0} +}; + +const Descriptor test_column1[] = { + {0,0,"","",Arg::None, "11 \t21\v22\v23\t 31\nxx" }, + {0,0,0,0,0,0} +}; + + +const Descriptor test_tables[] = { + {0,0,"","",Arg::None,0}, // table break + {0,0,"","",Arg::None,0}, // table break + {0,0,"","",Arg::None, "Each table has its own column widths and is not aligned with other tables."}, + {0,0,"","",Arg::None, "Table 1 Column 1 Line 1 \tTable 1 Column 2 Line 1 \tTable 1 Column 3 Line 1\n" + "Table 1 Col 1 Line 2 \tTable 1 Col 2 Line 2 \tTable 1 Col 3 Line 2" + }, + {0,0,"","",Arg::None, "Table 1 Col 1 Line 3 \tTable 1 Col 2 Line 3 \tTable 1 Column 3 Line 3\n" + "Table 1 Col 1 Line 4 \tTable 1 Column 2 Line 4 \tTable 1 Column 3 Line 4" + }, + {0,0,"","",Arg::None,0}, // table break + {0,0,"","",Arg::None,0}, // table break + {0,0,"","",Arg::None, "This is the only line of table 2." }, + {0,0,"","",Arg::None,0}, // table break + {0,0,"","",Arg::None, "This is the very long 1st line of table 3. It is more than 80 characters in length and therefore needs to be wrapped. In fact it is so long that it needs to be wrapped multiple times to fit into a normal 80 characters terminal.\v" + "This is the very long 2nd line of table 3. It is more than 80 characters in length and therefore needs to be wrapped. In fact it is so long that it needs to be wrapped multiple times to fit into a normal 80 characters terminal.\v" + "This is a reasonably sized line 3 of table 3." + }, + {0,0,"","",Arg::None,0}, // table break + {0,0,"","",Arg::None, "Table 4:\n" + " \tTable 4 C 1 L 1 \tTable 4 C 2 L 1 \tTable 4 C 3 L 1\n" + "\tTable 4 C 1 L 2 \tTable 4 C 2 L 2 \tTable 4 C 3 L 2" + }, + {0,0,"","",Arg::None,0}, // table break + {0,0,"","",Arg::None, "This is the only line of table 5"}, + {0,0,"","",Arg::None,0}, // table break + {0,0,"","",Arg::None, "Table 6 C 1 L 1 \tTable 6 C 2 L 1 \tTable 6 C 3 L 1\n" + "Table 6 C 1 L 2 \tTable 6 C 2 L 2 \tTable 6 C 3 L 2" + }, + {0,0,"","",Arg::None,0 }, // table break + {0,0,"","",Arg::None, "Table 7 Column 1 Line 1 \tTable 7 Column 2 Line 1 \tTable 7 Column 3 Line 1\n" + "Table 7 Column 1 Line 2 \tTable 7 Column 2 Line 2 \tTable 7 Column 3 Line 2\n" + }, + {0,0,0,0,0,0} +}; + +const Descriptor test_nohelp[] = { + {0,0,"","",Arg::None, 0 }, + {0,0,"","",Arg::None, 0 }, + {0,0,"","",Arg::None, 0 }, + {0,0,0,0,0,0} +}; + +const Descriptor test_wide[] = { + {0,0,"","",Arg::None, "Roma\t|x漢" }, + {0,0,"","",Arg::None, "ｶﾀｶﾅ\t|漢字" }, + {0,0,"","",Arg::None, "漢字\t|漢ｶ " }, + {0,0,"","",Arg::None, "漢字\t|ｶﾅ 漢字" }, + {0,0,0,0,0,0} +}; + +const Descriptor test_overlong[] = { + {0,0,"","",Arg::None, "Good \t| Good \t| This is good." }, + {0,0,"","",Arg::None, "Good \t| This is an overlong cell. \t| This is good." }, + {0,0,"","",Arg::None, "Good \t| Good \t| This is good." }, + {0,0,0,0,0,0} +}; + +const Descriptor test_toomanycolumns[] = { + {0,0,"","",Arg::None, "This \ttable \thas \ttoo \tmany \tcolumns. \tThe \tlast \tcolumns \tare \tdiscarded." }, + {0,0,"","",Arg::None, "1\t2\t3\t4\t5\t6\t7\t8\t9\t10\t11" }, + {0,0,0,0,0,0} +}; + +const Descriptor test_ownline[] = { + {0,0,"","",Arg::None, "1234567890AB\vBA0987654321\tStarts on its own line and is indented somewhat.\vThis one, too." }, + {0,0,0,0,0,0} +}; + +const Descriptor test_overflow[] = { + {0,0,"","",Arg::None, "漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字漢字" }, + {0,0,0,0,0,0} +}; + +void stderr_write(const char* str, int size) +{ + fwrite(str, size, 1, stderr); +} + +struct stderr_writer +{ + void write(const char* buf, size_t size) const + { + ::write(2, buf, size); + } +}; + +struct stderr_write_functor +{ + void operator()(const char* buf, size_t size) + { + ::write(2, buf, size); + } +}; + +int main() +{ + fputs("---------------------------------------------------------------\n",stderr); + option::printUsage(stderr_write, test_overflow, 1); + fputs("---------------------------------------------------------------\n",stderr); + option::printUsage(stderr_write, test_vtabs); + fputs("---------------------------------------------------------------\n",stderr); + option::printUsage(stderr_writer(), test_columns); + fputs("---------------------------------------------------------------\n",stderr); + option::printUsage(write, 2, test_column1); + fputs("---------------------------------------------------------------\n",stderr); + option::printUsage(cerr, test_tables); + fputs("---------------------------------------------------------------\n",stderr); + option::printUsage(fwrite, stderr, test_nohelp); + fputs("---------------------------------------------------------------\n",stderr); + ostringstream sst; + option::printUsage(sst, test_wide, 8); + cerr<