working but likely very buggy

.vscode/settings.json

@@ -97,5 +97,6 @@
     },
     "C_Cpp.default.includePath": [
         "./src"
-    ]
+    ],
+    "C_Cpp.formatting": "clangFormat"
 }

Doxyfile

@@ -48,7 +48,7 @@ PROJECT_NAME           = libcmdapp
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         =
+PROJECT_NUMBER         = v0.1.0
 
 # 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
@@ -623,7 +623,7 @@ HIDE_SCOPE_NAMES       = NO
 # YES the compound reference will be hidden.
 # The default value is: NO.
 
-HIDE_COMPOUND_REFERENCE= NO
+HIDE_COMPOUND_REFERENCE = NO
 
 # If the SHOW_HEADERFILE tag is set to YES then the documentation for a class
 # will show which file needs to be included to use the class.

book/main.md

@@ -1,12 +1,35 @@
 \mainpage Introduction
 
-libcmdapp aims to be a simple and intuitive way to parse command line options and arguments.
-It aims to provide flexible behavior with the least verbosity possible, intelligently filling any gaps.
+\section overview_sec Overview
 
-Item | Location
-------- | ---------
-**Documentation** | cmdapp.h
-**Repository** | https://github.com/ethanuppal/libcmdapp2
+libcmdapp aims to be a simple and intuitive way to parse command line options and arguments.
+It aims to provide flexible behavior with the least verbosity possible, intelligently filling any gaps. It is a complete replacement and successor to [libcmdapp](https://github.com/ethanuppal/libcmdapp), which I wrote over 2 years ago.
+
+<table>
+    <tr>
+        <th style="text-align:left; vertical-align:top">Item</th>
+        <th style="text-align:left; vertical-align:top">Location</th>
+    </tr>
+    <tr>
+        <td style="text-align:left; vertical-align:top"><b>Documentation</b></td>
+        <td style="text-align:left; vertical-align:top">cmdapp.h</td>
+    </tr>
+    <tr>
+        <td style="text-align:left; vertical-align:top"><b>Repository</b></td>
+        <td style="text-align:left; vertical-align:top">
+            <a href="https://github.com/ethanuppal/libcmdapp2">https://github.com/ethanuppal/libcmdapp2</a>
+        </td>
+    </tr>
+    <tr>
+        <td style="text-align:left; vertical-align:top"><b>Contents</b></td>
+        <td style="text-align:left; vertical-align:top">
+            \ref overview_sec <br> 
+            \ref feature_sec <br> 
+            \ref install_sec <br> 
+            \ref example_sec
+        </td>
+    </tr>
+</table>
 
 \section feature_sec Features
 
@@ -23,9 +46,9 @@ This library supports
     const char* expr = "EXPR";
     ca_opt('e', "expr", ". !@f", &expr, "evaluates an expression");
     ```
-- Automatic `--help` and `--version` generation
+- Automatic `--help` and `--version` generation, ca_print_version(), ca_print_help()
     - The default implementation integrates with [`help2man`](https://www.gnu.org/software/help2man/) for __automatic man pages__
-    - You can override and call ca_print_version() / ca_print_help() on your own
+    - You can override with ca_override_help_version()
 - Error handling and option conflicts
 
 You can read more about supplying options [here](opt.md).
@@ -72,7 +95,7 @@ if (ca_init(argc, argv) != 0) {
 Then, we can tell it information about our program, such as the year it was written, the authors, etc.
 ```c
 ca_description("Serves as a useful example program for libcmdapp.");
-ca_author("Ethan Uppal");
+ca_author("First Author");
 ca_author("Other Author");
 ca_year(2024);
 ca_version(1, 0, 0);
@@ -87,15 +110,23 @@ ca_synopsis("[OPTION]... FILE");
 
 Finally, we supply the program options
 ```c
+// options without arguments
 ca_opt('a', "alert", "", NULL, "oh no!");
 ca_opt('b', "very-long-name", "", NULL,
     "this text has been put down a line");
 
+// options with arguments
 const char* expr = "EXPR";
 ca_opt('e', "expr", ". !@f", &expr, "evaluates an expression");
 
 const char* filename = "FILE";
 ca_opt('f', "file", ". !@e", &filename, "processes a file");
+
+// help & version
+ca_opt('h', "help", "<h", NULL, "prints this info");
+ca_opt('v', "version", "<v", NULL, "prints version info");
 ```
 
+Note that ca_opt() and ca_long_opt() can return nonzero on error. However, if you don't make any errors in how you write the functions, you shouldn't ever need to check because they usually won't be dependent on dynamic data.
+
 All you need now is to call ca_parse() or related functions!

book/opt.md

@@ -37,10 +37,12 @@ Example `behavior` | Description
 `""` | The empty string means that there is no additional behavior associated with this option.
 `"."` | A dot means that the option takes an argument.
 `".?"` | A question mark following the dot means that the option's argument is optional.
+`"*"` | A star means that the option occurs in multiflag mode.
 `". @abc"` | `@abc` means that this option can only be passed when __at least one__ of `-a`, `-b`, or `-c` is passed.
 `".@abc"` | Whitespace isn't needed.
 `". &abc"` | `&abc` means that this option can only be passed when __all__ of `-a`, `-b`, or `-c` are passed.
 `". !@abc"` | `!&abc` means that this option can only be passed when __none__ of `-a`, `-b`, or `-c` are passed.
+`"<abc"` | `<abc` means that this option can only be passed when only some of `-a`, `-b`, or `c` are passed, but not when any other flag is passed.
 
 \warning
 Note that you will not be able to specify referencing behavior for options that do not have a short flag form.
@@ -51,10 +53,16 @@ Symbol | Meaning
 --- | ---
 `.` | The option takes an argument.
 `?` following `.` | The argument is optional.
+`*` | The option occurs in multiflag mode.
 `!` preceding `@` or `&` | The following quantifier is negated.
 `@` | At least one of the following.
 `&` | All of the following.
+`<` | Only some of the following.
 
-Essentially, the quantifiers allow to express relationships between options. If you want an option that must be passed by itself, use `"@"` or `"&"` with no additional flags. In other words, the option is only valid when any (or all) of *nothing* is passed. If you want an option that is dependent on another option `-a`, use `"&a"`. If you want to disable an option when the either `-a` and `-b` flags are passed, use `"!@ab"` (or `"!@ba"`).
+Essentially, the quantifiers `@`, `&`, and `<` enable you to express relationships between options:
 
-The argument information (`"."` or `".?"`) must be supplied before quantifiers, and arbitrary whitespace may be used to separate them for readability. It is possible to have quantifiers with no argument information.
+- If you want an option `-a` that must be passed by itself, use `"<a"`. 
+- If you want an option that is dependent on another option `-a`, use `"&a"`. 
+- If you want to disable an option when the either `-a` and `-b` flags are passed, use `"!@ab"` (or `"!@ba"`).
+
+The argument information (`"."`, `".?"`, or `"*"`) must be supplied before quantifiers, and arbitrary whitespace may be used to separate them for readability. It is possible to have quantifiers with no argument information, and vice versa.

book/todo.md

@@ -1,3 +1,10 @@
-- [ ] multiple-argument options
-- [ ] on-line parsing for duplicate flags, or maybe arrays?
-- [ ] code copyright laws into it since it won't extend forever
+\page todo_log Todo Log
+
+This is an internal document.
+
+\todo multiple-argument options
+\todo on-line parsing for duplicate flags, or maybe arrays?
+\todo code copyright laws into it since it won't extend forever
+\todo long options with = like --foo=bar
+\todo write a canonical rep function for opts that returns a static buffer for printf locally
+\todo fix the naming of "conflicts" it should probably have a better name but hard to find a general one