add support for positional arguments

Author: cbeck88

REFERENCE_derive_conf.md

@@ -21,6 +21,7 @@ The `#[conf(...)]` attributes conform to [Rust’s structured attribute conventi
   * [Parameter](#parameter)
     * [short](#parameter-short)
     * [long](#parameter-long)
+    * [pos](#parameter-pos)
     * [env](#parameter-env)
     * [aliases](#parameter-aliases)
     * [env_aliases](#parameter-env-aliases)
@@ -238,6 +239,81 @@ A parameter represents a single value that can be parsed from a string.
 
    *Note*: This behavior is the same as in `clap-derive`.
 
+*  <a name="parameter-pos"></a> `pos` (no arguments)
+
+   Specifies that this parameter is a positional argument.
+   Positional arguments are identified by their position in the command line, not by a flag name.
+   The order of positional arguments is determined by the order of fields in the struct.
+
+   example: `#[arg(pos)]`
+
+   example command-line: `./my_prog input.txt output.txt` where the first positional is assigned to the first `pos` field, the second to the second `pos` field, etc.
+
+   **Positional argument filling**:
+   - Positional arguments are filled left-to-right based on their declaration order in the struct
+   - You cannot skip a positional argument to provide a later one
+   - If you have multiple optional positionals and provide fewer arguments, they fill from left to right
+
+   **Optional positionals**:
+   - A positional parameter can be optional by using `Option<T>` as the field type
+   - All optional positional arguments must come after all required positional arguments
+   - The parser will panic at construction time if a required positional follows an optional positional
+
+   **Compatibility**:
+   - `pos` is mutually exclusive with `short` and `long` (you cannot have a positional argument with flag names)
+   - `pos` is compatible with `env` (the value can be provided via environment variable or positional argument)
+   - `pos` is supported in regular `flatten` and in subcommands
+   - `pos` is NOT supported in `flatten` with `Option<T>` (flatten optional) - this will produce an error
+
+   **Examples**:
+
+   Valid configuration:
+   ```rust
+   #[derive(Conf)]
+   struct MyConfig {
+       /// Input file (required positional)
+       #[conf(pos)]
+       input: String,
+
+       /// Output file (required positional)
+       #[conf(pos)]
+       output: String,
+
+       /// Optional log file (optional positional - OK because it's at the end)
+       #[conf(pos)]
+       log_file: Option<String>,
+   }
+   ```
+
+   Command-line usage: `./my_prog input.txt output.txt` or `./my_prog input.txt output.txt debug.log`
+
+   Invalid configuration (will panic):
+   ```rust
+   #[derive(Conf)]
+   struct BadConfig {
+       #[conf(pos)]
+       first: String,
+
+       #[conf(pos)]
+       second: Option<String>,  // optional
+
+       #[conf(pos)]
+       third: String,  // ERROR: required after optional!
+   }
+   ```
+
+   Positional with environment variable fallback:
+   ```rust
+   #[derive(Conf)]
+   struct MyConfig {
+       /// Can be provided as first positional arg or via INPUT env var
+       #[conf(pos, env)]
+       input: String,
+   }
+   ```
+
+   Command-line usage: `./my_prog input.txt` or `INPUT=input.txt ./my_prog`
+
 *  <a name="parameter-env"></a> `env` (optional string argument)
 
    Specifies an environment variable associated to this parameter.

conf_derive/src/proc_macro_options/field_item/flag_item.rs

@@ -212,6 +212,7 @@ impl FlagItem {
                 is_required: false,
                 allow_hyphen_values: false,
                 secret: Some(false),
+                is_positional: false,
             });
         })
     }

conf_derive/src/proc_macro_options/field_item/flatten_item.rs

@@ -245,10 +245,29 @@ impl FlattenItem {
 
         // The initializer simply gets all program options, modifies as needed,
         // and then checks for a skip-short error.
+        let positional_check = if self.is_optional_type.is_some() {
+            quote! {
+              // Check for positional args in flatten optional
+              for opt in __inner_options__ {
+                  if opt.is_positional {
+                      return Err(::conf::Error::positional_in_flatten_optional(
+                          #field_name,
+                          <#inner_type as ::conf::Conf>::get_name(),
+                          &opt.id
+                      ));
+                  }
+              }
+            }
+        } else {
+            quote! {}
+        };
+
         let push_expr = quote! {
           let mut #was_skipped_ident = [false; #skip_short_len];
+          let __inner_options__ = <#inner_type as ::conf::Conf>::get_program_options()?;
+          #positional_check
           #program_options_ident.extend(
-            <#inner_type as ::conf::Conf>::get_program_options()?.iter().cloned().map(
+            __inner_options__.iter().cloned().map(
               |program_option|
                 program_option
                   #modify_program_option

conf_derive/src/proc_macro_options/field_item/parameter_item.rs

@@ -71,6 +71,7 @@ pub struct ParameterItem {
     value_parser: Option<Expr>,
     serde: Option<ParameterSerdeItem>,
     doc_string: Option<String>,
+    is_positional: bool,
 }
 
 impl ParameterItem {
@@ -99,6 +100,7 @@ impl ParameterItem {
             value_parser: None,
             serde: None,
             doc_string: None,
+            is_positional: false,
         };
 
         for attr in &field.attrs {
@@ -168,25 +170,45 @@ impl ParameterItem {
                             &mut result.serde,
                             Some(ParameterSerdeItem::new(meta)?),
                         )
+                    } else if path.is_ident("pos") {
+                        result.is_positional = true;
+                        Ok(())
                     } else {
                         Err(meta.error("unrecognized conf parameter option"))
                     }
                 })?;
             }
         }
 
+        // Validate positional argument constraints
+        if result.is_positional {
+            if result.short_switch.is_some() {
+                return Err(Error::new(
+                    field.span(),
+                    "#[conf(pos)] cannot be used with #[conf(short)]",
+                ));
+            }
+            if result.long_switch.is_some() {
+                return Err(Error::new(
+                    field.span(),
+                    "#[conf(pos)] cannot be used with #[conf(long)]",
+                ));
+            }
+        }
+
         if result.is_optional_type.is_none()
             && result.short_switch.is_none()
             && result.long_switch.is_none()
             && result.env_name.is_none()
             && result.default_value.is_none()
+            && !result.is_positional
             && struct_item.serde.is_none()
         {
             return Err(Error::new(
                 field.span(),
                 "There is no way for the user to give this parameter a value. \
-                Trying using #[arg(short)], #[arg(long)], or #[arg(env)] to specify a switch \
-                or an env associated to this value, or specify a default value.",
+                Trying using #[arg(short)], #[arg(long)], #[arg(env)], or #[arg(pos)] to specify a switch, \
+                positional argument, or an env associated to this value, or specify a default value.",
             ));
         }
 
@@ -276,6 +298,7 @@ impl ParameterItem {
         let default_value = quote_opt_into(&self.default_value);
         let allow_hyphen_values = self.allow_hyphen_values;
         let secret = quote_opt(&self.secret);
+        let is_positional = self.is_positional;
 
         Ok(quote! {
             #program_options_ident.push(::conf::ProgramOption {
@@ -291,6 +314,7 @@ impl ParameterItem {
                 is_required: #is_required,
                 allow_hyphen_values: #allow_hyphen_values,
                 secret: #secret,
+                is_positional: #is_positional,
             });
         })
     }

conf_derive/src/proc_macro_options/field_item/repeat_item.rs

@@ -293,6 +293,7 @@ impl RepeatItem {
               is_required: false,
               allow_hyphen_values: #allow_hyphen_values,
               secret: #secret,
+              is_positional: false,
             });
         })
     }

examples/serde/figment.rs

@@ -1,8 +1,8 @@
 use conf::Conf;
 use figment::{
+    Figment,
     providers::{Format, Json, Toml},
     value::Value,
-    Figment,
 };
 use std::env;
 

src/builder.rs

@@ -1,4 +1,4 @@
-use crate::{parse_env, Conf, ConfContext, Error, InnerError, ParsedArgs, ParsedEnv};
+use crate::{Conf, ConfContext, Error, InnerError, ParsedArgs, ParsedEnv, parse_env};
 use std::{ffi::OsString, marker::PhantomData};
 
 /// A builder which collects config value sources for the parse.

src/conf_context.rs

@@ -1,4 +1,4 @@
-use crate::{str_to_bool, InnerError, ParseType, ParsedArgs, ParsedEnv, ProgramOption};
+use crate::{InnerError, ParseType, ParsedArgs, ParsedEnv, ProgramOption, str_to_bool};
 use clap::parser::ValueSource;
 use core::fmt::Debug;
 
@@ -154,7 +154,7 @@ impl<'a> ConfContext<'a> {
                     self.args.id_to_option()
                 )
             });
-        if opt.short_form.is_some() || opt.long_form.is_some() {
+        if opt.short_form.is_some() || opt.long_form.is_some() || opt.is_positional {
             if let Some(val) = self.args.arg_matches.get_one::<String>(&id) {
                 let value_source = self
                     .args

src/error.rs

@@ -1,5 +1,5 @@
 use crate::{ConfValueSource, FlattenedOptionalDebugInfo, ProgramOption};
-use clap::{builder::Styles, error::ErrorKind, Command, Error as ClapError};
+use clap::{Command, Error as ClapError, builder::Styles, error::ErrorKind};
 use std::{ffi::OsString, fmt, fmt::Write};
 
 /// An error which occurs when a `Conf::parse` function is called.
@@ -42,9 +42,24 @@ impl Error {
         field_name: &'static str,
         field_type_name: &'static str,
     ) -> Self {
-        let buf = format!("Internal error (invalid skip short)\n  When flattening {field_type_name} at {field_name}, these short options were not found: {not_found_chars:?}\n  To fix this error, remove them from the skip_short attribute list.");
+        let buf = format!(
+            "Internal error (invalid skip short)\n  When flattening {field_type_name} at {field_name}, these short options were not found: {not_found_chars:?}\n  To fix this error, remove them from the skip_short attribute list."
+        );
         ClapError::raw(ErrorKind::UnknownArgument, buf).into()
     }
+
+    // An error reported when positional arguments are used in flatten optional
+    #[doc(hidden)]
+    pub fn positional_in_flatten_optional(
+        field_name: &str,
+        field_type_name: &str,
+        option_id: &str,
+    ) -> Self {
+        let buf = format!(
+            "Cannot use flatten optional with struct '{field_type_name}' at field '{field_name}' because it contains positional argument '{option_id}'. Positional arguments are not supported in flatten optional structs (but are supported in regular flatten)."
+        );
+        ClapError::raw(ErrorKind::ArgumentConflict, buf).into()
+    }
 }
 
 impl From<ClapError> for Error {
@@ -378,7 +393,10 @@ impl InnerError {
                     instance_id_prefix.insert_str(0, " @ .");
                     remove_trailing_dot(&mut instance_id_prefix);
                 }
-                writeln!(stream, "  One of these must be provided: (constraint on {struct_name}{instance_id_prefix}): ")?;
+                writeln!(
+                    stream,
+                    "  One of these must be provided: (constraint on {struct_name}{instance_id_prefix}): "
+                )?;
                 for opt in single_opts {
                     write!(stream, "  ")?;
                     print_opt_requirements(stream, opt, "")?;
@@ -402,7 +420,10 @@ impl InnerError {
                     instance_id_prefix.insert_str(0, " @ .");
                     remove_trailing_dot(&mut instance_id_prefix);
                 }
-                writeln!(stream, "  Too many arguments, provide at most one of these: (constraint on {struct_name}{instance_id_prefix}): ")?;
+                writeln!(
+                    stream,
+                    "  Too many arguments, provide at most one of these: (constraint on {struct_name}{instance_id_prefix}): "
+                )?;
                 for (opt, source) in single_opts {
                     let provided_opt = render_provided_opt(opt, source);
                     writeln!(stream, "    {provided_opt}")?;
@@ -474,6 +495,23 @@ fn print_opt_requirements(
     opt: &ProgramOption,
     trailing_text: &str,
 ) -> fmt::Result {
+    // Handle positional arguments
+    if opt.is_positional {
+        let pos_name = format!("<{}>", opt.id);
+        match opt.env_form.as_deref() {
+            Some(name) => {
+                let trailing_text = if trailing_text.is_empty() {
+                    "".to_owned()
+                } else {
+                    ", ".to_owned() + trailing_text
+                };
+                writeln!(stream, "  env '{name}', or '{pos_name}'{trailing_text}")?
+            }
+            None => writeln!(stream, "  '{pos_name}' {trailing_text}")?,
+        }
+        return Ok(());
+    }
+
     let maybe_switch = render_help_switch(opt);
     match (maybe_switch, opt.env_form.as_deref()) {
         (Some(switch), Some(name)) => {
@@ -487,7 +525,10 @@ fn print_opt_requirements(
         (Some(switch), None) => writeln!(stream, "  '{switch}' {trailing_text}")?,
         (None, Some(name)) => writeln!(stream, "  env '{name}' {trailing_text}")?,
         (None, None) => {
-            debug_assert!(false, "This should be unreachable, we should not be printing opt requirements for an option with no way to specify it");
+            debug_assert!(
+                false,
+                "This should be unreachable, we should not be printing opt requirements for an option with no way to specify it"
+            );
             writeln!(
                 stream,
                 "  There is no way to provide this value, this is an internal error ({id})",