From 7474a66ef6e26701e1b4be5428ab3e1ffada9c21 Mon Sep 17 00:00:00 2001 From: Matthew Limbinar <73853812+matthew-limbinar@users.noreply.github.com> Date: Sun, 3 Jul 2022 19:55:17 -0400 Subject: [PATCH] Clarify positional argument docs (#335) --- README.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ede30ef..5e4e3d2 100644 --- a/README.md +++ b/README.md @@ -125,15 +125,34 @@ vector to the `help` function. ## Positional Arguments -Positional arguments can be optionally parsed into one or more options. -To set up positional arguments, call +Positional arguments are those given without a preceding flag and can be used +alongside non-positional arguments. There may be multiple positional arguments, +and the final positional argument may be a container type to hold a list of all +remaining positionals. + +To set up positional arguments, first declare the options, then configure a +set of those arguments as positional like: ```cpp -options.parse_positional({"first", "second", "last"}) +options.add_options() + ("script", "The script file to execute", cxxopts::value()) + ("server", "The server to execute on", cxxopts::value()) + ("filenames", "The filename(s) to process", cxxopts::value>()); + +options.parse_positional({"script", "server", "filenames"}) ``` -where "last" should be the name of an option with a container type, and the -others should have a single value. +Then parsing a set of arguments like: +~~~ +my_script.py my_server.com file1.txt file2.txt file3.txt +~~~ +will result in parsed arguments like the following table: + +| Field | Value | +| ------------- | ----------------------------------------- | +| `"script"` | `"my_script.py"` | +| `"server"` | `"my_server.com"` | +| `"filenames"` | `{"file1.txt", "file2.txt", "file3.txt"}` | ## Default and implicit values -- libgit2 0.21.4