[Feature] Adding variadic positional arguments

Author: lucocozz

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Printing subcommand list on command execution that cannot be executed directly.
+- Support for variadic positional arguments, allowing multiple values for a single positional argument.
 
 ### Changed
 - Change `ARGUS_RELEASE` into `ARGUS_DEBUG`

Justfile

@@ -165,6 +165,7 @@ examples:
             basic_usage)          desc="Basic flags, string, and integer options" ;; \
             subcommands)          desc="Git-like subcommands implementation" ;; \
             positional_args)      desc="Handling positional arguments" ;; \
+            variadic_positional)  desc="Handling variadic positional arguments" ;; \
             custom_handlers)      desc="Creating custom option handlers" ;; \
             advanced_options)     desc="Dependencies, conflicts, and exclusive groups" ;; \
             nested_commands)      desc="Complex nested subcommands (like git or docker)" ;; \

argus.def

@@ -38,6 +38,10 @@ EXPORTS
     free_map_int_handler
     free_map_float_handler
     free_map_bool_handler
+    variadic_string_handler
+    variadic_int_handler
+    variadic_float_handler
+    free_variadic_string_handler
     range_validator
     length_validator
     count_validator

docs/docs/api-reference/overview.md

@@ -76,6 +76,11 @@ POSITIONAL_STRING(name, ...)         // String positional
 POSITIONAL_INT(name, ...)            // Integer positional
 POSITIONAL_BOOL(name, ...)           // Boolean positional
 POSITIONAL_FLOAT(name, ...)          // Float positional
+
+// Variadic positionals (accept multiple values)
+POSITIONAL_MANY_STRING(name, ...)    // Variadic string positional
+POSITIONAL_MANY_INT(name, ...)       // Variadic integer positional
+POSITIONAL_MANY_FLOAT(name, ...)     // Variadic float positional
 ```
 
 ### Structure Macros

docs/docs/appendices/cheat-sheet.md

@@ -54,8 +54,14 @@ OPTION_MAP_BOOL('f', "features", HELP("Feature flags"))
 ## // Positional Arguments
 
 ```c
+// Single positionals
 POSITIONAL_STRING("input", HELP("Input file"))
 POSITIONAL_INT("count", HELP("Count"), FLAGS(FLAG_OPTIONAL))
+
+// Variadic positionals (accept multiple values)
+POSITIONAL_MANY_STRING("files", HELP("Files to process"))
+POSITIONAL_MANY_INT("numbers", HELP("Numbers to calculate"))
+POSITIONAL_MANY_FLOAT("values", HELP("Decimal values"))
 ```
 
 ## // Option Modifiers
@@ -208,6 +214,9 @@ int main(int argc, char **argv)
 # Positional
 program input.txt output.txt
 
+# Variadic positionals
+program file1.c file2.c file3.c ...
+
 # Stop parsing
 program --option -- --not-an-option
 ```

docs/docs/features/collections.md

@@ -178,6 +178,75 @@ ARGUS_OPTIONS(
 </TabItem>
 </Tabs>
 
+## // Variadic Positional
+
+Accept multiple values for positional arguments, similar to array options but for positional parameters:
+
+<Tabs>
+<TabItem value="variadic-types" label="Variadic Types" default>
+
+```c
+ARGUS_OPTIONS(
+    options,
+    HELP_OPTION(),
+    
+    // Multiple string values
+    POSITIONAL_MANY_STRING("files", HELP("Input files to process"), 
+                           HINT("FILE..."),
+                           FLAGS(FLAG_UNIQUE | FLAG_SORTED)),
+    
+    // Multiple integer values
+    POSITIONAL_MANY_INT("numbers", HELP("Numbers to process"),
+                        HINT("NUM..."),
+                        VALIDATOR(V_COUNT(1, 10))),
+    
+    // Multiple float values
+    POSITIONAL_MANY_FLOAT("values", HELP("Float values"),
+                          HINT("VAL...")),
+)
+```
+
+**Supported types:**
+- `POSITIONAL_MANY_STRING` - Multiple text values
+- `POSITIONAL_MANY_INT` - Multiple integer values  
+- `POSITIONAL_MANY_FLOAT` - Multiple decimal values
+
+**Important restrictions:**
+- Only one `POSITIONAL_MANY` argument allowed per command
+- Must be placed after all regular positional arguments
+- Cannot mix with optional positional arguments
+- Cannot be used with subcommands at the same level
+
+</TabItem>
+<TabItem value="variadic-usage" label="Usage Examples">
+
+```bash
+# Process multiple files
+./program file1.c file2.c file3.c
+
+# Process numbers
+./program 1 2 3 4 5
+
+# No arguments (if optional)
+./program
+
+# With other options
+./program --verbose file1.txt file2.txt
+```
+
+**Key characteristics:**
+- Accepts zero or more values
+- Values are collected into an array
+- Supports same flags as array options (`FLAG_SORTED`, `FLAG_UNIQUE`)
+- Can use validation like `V_COUNT()` to enforce limits
+
+**Access methods:**
+- Same as array collections: `argus_get().as_array`, `argus_count()`, `argus_array_it()`
+- See [Accessing Values](../fundamentals/accessing-values#variadic-positional) for detailed examples
+
+</TabItem>
+</Tabs>
+
 ## // Accessing Collection Values
 
 <Tabs>

docs/docs/fundamentals/accessing-values.md

@@ -361,6 +361,114 @@ int main(int argc, char **argv)
 </TabItem>
 </Tabs>
 
+## // Variadic Positional
+
+Access variadic positional arguments the same way as array collections:
+
+<Tabs>
+<TabItem value="variadic-direct" label="Direct Access" default>
+
+```c
+ARGUS_OPTIONS(
+    options,
+    HELP_OPTION(),
+    POSITIONAL_MANY_STRING("files", HELP("Input files to process"), 
+                           HINT("FILE..."),
+                           FLAGS(FLAG_UNIQUE | FLAG_SORTED)),
+)
+
+int main(int argc, char **argv)
+{
+    argus_t argus = argus_init(options, "myapp", "1.0.0");
+    argus_parse(&argus, argc, argv);
+    
+    // Check if files were provided
+    if (argus_is_set(&argus, "files")) {
+        size_t count = argus_count(&argus, "files");
+        argus_value_t *files = argus_get(&argus, "files").as_array;
+        
+        printf("Processing %zu files:\n", count);
+        for (size_t i = 0; i < count; i++) {
+            printf("  %zu: %s\n", i + 1, files[i].as_string);
+        }
+    } else {
+        printf("No files specified\n");
+    }
+    
+    argus_free(&argus);
+    return 0;
+}
+```
+
+</TabItem>
+<TabItem value="variadic-iterator" label="Iterator Access">
+
+```c
+ARGUS_OPTIONS(
+    options,
+    HELP_OPTION(),
+    POSITIONAL_MANY_STRING("files", HELP("Input files"), HINT("FILE...")),
+)
+
+int main(int argc, char **argv)
+{
+    argus_t argus = argus_init(options, "myapp", "1.0.0");
+    argus_parse(&argus, argc, argv);
+    
+    // Use iterator for clean traversal
+    argus_array_it_t it = argus_array_it(&argus, "files");
+    
+    printf("Files to process:\n");
+    while (argus_array_next(&it)) {
+        printf("  - %s\n", it.value.as_string);
+        process_file(it.value.as_string);
+    }
+    
+    argus_free(&argus);
+    return 0;
+}
+```
+
+</TabItem>
+<TabItem value="variadic-helper" label="Helper Functions">
+
+```c
+ARGUS_OPTIONS(
+    options,
+    HELP_OPTION(),
+    POSITIONAL_MANY_INT("numbers", HELP("Numbers to process"), HINT("NUM...")),
+)
+
+int main(int argc, char **argv)
+{
+    argus_t argus = argus_init(options, "myapp", "1.0.0");
+    argus_parse(&argus, argc, argv);
+    
+    // Access specific elements by index
+    int first = argus_array_get(&argus, "numbers", 0).as_int;
+    int second = argus_array_get(&argus, "numbers", 1).as_int;
+    
+    if (first) printf("First number: %d\n", first);
+    if (second) printf("Second number: %d\n", second);
+    
+    // Get total count
+    size_t total = argus_count(&argus, "numbers");
+    printf("Total numbers: %zu\n", total);
+    
+    argus_free(&argus);
+    return 0;
+}
+```
+
+</TabItem>
+</Tabs>
+
+**Important notes:**
+- Variadic positionals use the same access functions as array options
+- Always check `argus_is_set()` before accessing since they accept zero values
+- Use `argus_count()` to get the number of values provided
+- Iterator pattern is most efficient for processing all values
+
 ## // Subcommand Access
 
 In subcommand context, access values using path notation or relative names:
@@ -576,6 +684,8 @@ FILE *f = fopen(output, "w"); // output might be NULL!
 | **Check if set** | `argus_is_set()` | `if (argus_is_set(&argus, "output"))` |
 | **Array elements** | `argus_array_get()` | `argus_array_get(&argus, "tags", 0)` |
 | **Array iteration** | `argus_array_it()` | `while (argus_array_next(&it))` |
+| **Variadic positional** | `argus_get().as_array` | `argus_get(&argus, "files").as_array` |
+| **Variadic iteration** | `argus_array_it()` | `while (argus_array_next(&it))` |
 | **Map lookup** | `argus_map_get()` | `argus_map_get(&argus, "env", "USER")` |
 | **Map iteration** | `argus_map_it()` | `while (argus_map_next(&it))` |
 | **Subcommand relative** | `argus_get()` | `argus_get(argus, "file").as_string` |

examples/meson.build

@@ -3,6 +3,7 @@ example_programs = [
   'basic_usage',
   'subcommands',
   'positional_args',
+  'variadic_positional',
   'custom_handlers',
   'advanced_options',
   'nested_commands',

examples/variadic_positional.c

@@ -0,0 +1,53 @@
+/**
+ * Multi-value positional arguments example for argus
+ * 
+ * Demonstrates how to use positional arguments that can accept
+ * multiple values, similar to how many command-line tools work (e.g., cp file1 file2 file3 dest)
+ */
+
+#include "argus.h"
+#include <stdio.h>
+#include <stdlib.h>
+
+ARGUS_OPTIONS(
+    options,
+    HELP_OPTION(),
+    VERSION_OPTION(),
+
+    POSITIONAL_STRING(
+        "command", HELP("Operation to perform"), HINT("CMD"),
+        VALIDATOR(V_CHOICE_STR("build", "copy", "delete"))),
+
+    POSITIONAL_MANY_STRING(
+        "files", HELP("Input files to process"), HINT("FILE..."),
+        FLAGS(FLAG_UNIQUE | FLAG_SORTED)),
+)
+
+int main(int argc, char **argv)
+{
+    argus_t argus = argus_init(options, "many_args_example", "1.0.0");
+    argus.description = "Example of multi-value positional arguments";
+    
+    int status = argus_parse(&argus, argc, argv);
+    if (status != ARGUS_SUCCESS)
+        return status;
+
+    const char *command = argus_get(&argus, "command").as_string;
+    
+    printf("Configuration:\n");
+    printf("  Command: %s\n", command);
+
+    if (argus_is_set(&argus, "files"))
+    {
+        printf("  Files:\n");
+
+        argus_array_it_t it = argus_array_it(&argus, "files");   
+        while (argus_array_next(&it))
+            printf("    - %s\n", it.value.as_string);
+    }
+    else
+        printf("  Files: (none)\n");
+    
+    argus_free(&argus);
+    return 0;
+}

includes/argus/internal/callbacks/handlers.h

@@ -35,8 +35,7 @@ int map_bool_handler(argus_t *argus, argus_option_t *options, char *arg);
  */
 int default_free(argus_option_t *option);
 int free_array_string_handler(argus_option_t *option);
-// int free_array_int_handler(argus_option_t *option);
-// int free_array_float_handler(argus_option_t *option);
+int free_variadic_string_handler(argus_option_t *option);
 
 int free_map_string_handler(argus_option_t *option);
 int free_map_int_handler(argus_option_t *option);