Support leftover positional arguments and bump version to 0.2.4

Author: zachmatson

Project.toml

@@ -1,7 +1,7 @@
 name = "ArgMacros"
 uuid = "dbc42088-9de8-42a0-8ec8-2cd114e1ea3e"
 authors = ["zachmatson"]
-version = "0.2.3"
+version = "0.2.4"
 
 [deps]
 TextWrap = "b718987f-49a8-5099-9789-dcd902bef87d"

docs/src/index.md

@@ -63,6 +63,7 @@ The types of arguments supported are broken down into two categories:
   - [`@positionalrequired`](@ref)
   - [`@positionaldefault`](@ref)
   - [`@positionaloptional`](@ref)
+  - [`@positionalleftover`](@ref)
 
 The arguments are either required, optional, or have default values, as is evident
 in their names. Additionally, [`@argumentflag`](@ref) checks the presence of a flag,
@@ -76,7 +77,8 @@ For this reason, ALL options must be declared before ANY positionals, required
 positionals must be declared before default/optional ones, and positional arguments
 must be declared in the order the user is expected to enter them.
 
-You should make your argument types `Symbol`, `String`, or subtypes of `Number`.
+You should make your argument types `Symbol`, `String`, subtypes of `Number`,
+or some type with a sensible direct conversion from `String`.
 
 Here is an example with some arguments:
 ```julia
@@ -100,7 +102,7 @@ of the name of local variable they will be stored in.
     but making sure to follow them is essential to your code running properly.
     Additionally, make sure not to declare multiple arguments using the same flags.
     Other than the reserved `-h` and `--help` flags, this will not be detected automatically
-    at compile time, and could lead to undefined behavior. 
+    during compilation, and could lead to undefined behavior. 
 
 ## Using Argument Values
 
@@ -267,10 +269,19 @@ end
 ## Leftover Arguments
 
 By default, the program will exit and print a warning if more arguments are given than the program declares.
-If you don't want this to happen, include the [`@allowextraarguments`](@ref) macro.
+If you don't want this to happen, include the [`@allowextraarguments`](@ref) macro, or use [`@positionalleftover`](@ref)
+to store the extra arguments into a variable.
 
-This can occur anywhere inside the `@...arguments` block, but the recommended placement is at the end,
-after all other help, test, and argument declarations.
+[`@allowextraarguments`](@ref) can occur anywhere inside the `@...arguments` block, but the recommended placement is at the end,
+after all other help, test, and argument declarations. [`@positionalleftover`](@ref) must be the last argument declared in the block.
+
+```julia
+@inlinearguments begin
+    ...
+    @positionalleftover String file_names "files"
+    ...
+end
+```
 
 ```julia
 @inlinearguments begin

docs/src/macros.md

@@ -29,12 +29,14 @@ Additionally, it is recommended to specify the short flag first when using multi
 
 These arguments are specified by their position in the command.
 You must specify these in your code in the same order that users are expected to enter them.
-It is important to put these after all option arguments, and specify the required positional arguments first.
+It is important to put these after all option arguments, and specify the required positional arguments first.  
+If you want to specify leftover positional arguments, they must come after all other arguments.  
 
 ```@docs
 @positionalrequired
 @positionaldefault
 @positionaloptional
+@positionalleftover
 ```
 
 ## Help Options

src/ArgMacros.jl

@@ -17,7 +17,8 @@ export @beginarguments, @inlinearguments, @structarguments,
 export @helpusage, @helpdescription, @helpepilog
 export @argumentrequired, @argumentdefault, @argumentoptional,
        @argumentflag, @argumentcount
-export @positionalrequired, @positionaldefault, @positionaloptional
+export @positionalrequired, @positionaldefault, @positionaloptional,
+       @positionalleftover
 export @arghelp, @argtest, @allowextraarguments
 
 include("constants.jl")
@@ -26,12 +27,6 @@ include("help.jl")
 include("argsparsing.jl")
 include("macros.jl")
 
-#=
-TODO
-    multi-value arguments
-    escaping behavior
-=#
-
 include("precompile.jl")
 _precompile_()
 

src/argsparsing.jl

@@ -121,6 +121,11 @@ function _converttype!(::Type{T}, s::String, name::String)::T where T
     end
 end
 
+"Convert a vector of strings to Number type with parse or other types with direct conversions"
+function _converttype!(::Type{T}, values::Vector{String}, name::String)::Vector{T} where T
+    map(s -> _converttype!(T, s, name), values)
+end
+
 "Quit program if the value is nothing"
 function _converttype!(::Type{T}, ::Nothing, name::String)::Nothing where T
     _quit_try_help("Argument $name missing")

src/constants.jl

@@ -18,3 +18,4 @@ const POSITIONAL_REQUIRED_SYMBOL = Symbol("@positionalrequired")
 const POSITIONAL_DEFAULT_SYMBOL = Symbol("@positionaldefault")
 const POSITIONAL_OPTIONAL_SYMBOL = Symbol("@positionaloptional")
 const POSITIONAL_OPTIONAL_SYMBOLS = [POSITIONAL_DEFAULT_SYMBOL, POSITIONAL_OPTIONAL_SYMBOL]
+const POSITIONAL_LEFTOVER_SYMBOL = Symbol("@positionalleftover")

src/handleast.jl

@@ -15,13 +15,14 @@ end
 
 """
 Enforce argument declaration ordering:  
-    Flagged → Required Positional → Optional Positional
+    Flagged → Required Positional → Optional Positional → Leftover Positional
 
 Throw `ArgumentError` if ordering violates this rule.
 """
 function _validateorder(block::Expr)
     encountered_positional = false
     encoundered_optional_positional = false
+    encountered_leftover_positional = false
 
     for arg in _getmacrocalls(block)
         # Fix namespace issues
@@ -44,6 +45,16 @@ function _validateorder(block::Expr)
         elseif macroname in POSITIONAL_OPTIONAL_SYMBOLS
             encountered_positional = true
             encoundered_optional_positional = true
+
+            if encountered_leftover_positional
+                throw(ArgumentError(
+                    "Leftover arguments must be declared after all other arguments.\nFrom: $arg"
+                ))
+            end
+        elseif macroname == POSITIONAL_LEFTOVER_SYMBOL
+            encountered_positional = true
+            encoundered_optional_positional = true
+            encountered_leftover_positional = true
         end
     end
 end
@@ -52,12 +63,14 @@ end
 function _getargumentpair(arg::Expr)::Union{Expr, Nothing}
     macroname::Symbol = _get_macroname(arg)
 
-    if macroname in (ARGUMENT_REQUIRED_SYMBOL, POSITIONAL_REQUIRED_SYMBOL)
-        :($(arg.args[4])::$(arg.args[3]))
-    elseif macroname in (ARGUMENT_DEFAULT_SYMBOL, POSITIONAL_DEFAULT_SYMBOL)
+    if macroname in (ARGUMENT_DEFAULT_SYMBOL, POSITIONAL_DEFAULT_SYMBOL)
         :($(arg.args[5])::$(arg.args[3]))
+    elseif macroname in (ARGUMENT_REQUIRED_SYMBOL, POSITIONAL_REQUIRED_SYMBOL)
+        :($(arg.args[4])::$(arg.args[3]))
     elseif macroname in (ARGUMENT_OPTIONAL_SYMBOL, POSITIONAL_OPTIONAL_SYMBOL)
         :($(arg.args[4])::Union{$(arg.args[3]), Nothing})
+    elseif macroname == POSITIONAL_LEFTOVER_SYMBOL
+        :($(arg.args[4])::Vector{$(arg.args[3])})
     elseif macroname == ARGUMENT_FLAG_SYMBOL
         :($(arg.args[3])::Bool)
     elseif macroname == ARGUMENT_COUNT_SYMBOL

src/macros.jl

@@ -383,6 +383,39 @@ macro positionaloptional(type::Symbol, local_name::Symbol, help_name::Union{Stri
     end
 end
 
+"""
+    @positionalleftover type local_name [help_name]
+
+Get any leftover positional arguments after all other arguments have been parsed, and store in
+variable `local_name` with the type `Vector{type}`. This vector will be empty if there are no
+leftover arguments.
+
+This macro must be used after all other arguments have been declared, as positional arguments are
+read in order after all flag/option arguments have been read.  
+Using this macro means all input will be captured by this argument if not by another, so
+`@allowextraarguments` is not necesesary when this macro is used.
+`help_name` used instead of `local_name` in messages to user if specified.
+
+Must be used in `@beginarguments begin ... end` block
+
+# Example
+```julia
+@beginarguments begin
+    ...
+    @positionalleftover String file_names "files"
+    ...
+end
+```
+"""
+macro positionalleftover(type::Symbol, local_name::Symbol, help_name::Union{String, Nothing}=nothing)
+    help_name_str::String = something(help_name, String(local_name))
+    return quote
+        local $(esc(esc(local_name)))::$(esc(esc(Vector))){$(esc(esc(type)))} = 
+            _converttype!($type, splitargs, $help_name_str)
+        empty!(splitargs)
+    end   
+end
+
 """
     @argtest argname func [desc]
 
@@ -419,6 +452,10 @@ Disables the default behavior of printing a message and exiting
 the program when not all values in `ARGS` could be assigned to
 specified arguments.
 
+This will not capture any arguments, use `@positionalleftover`
+if you want to capture extra arguments that could not otherwise
+be assigned.
+
 Must be used in `@beginarguments begin ... end` block
 
 # Example

src/precompile.jl

@@ -8,6 +8,7 @@ function _precompile_()
     arg_types = (Float64, Float32, Int64, Int32, String, Symbol)
     for T in arg_types
         Base.precompile(Tuple{typeof(ArgMacros._converttype!),Type{T},String,String})
+        Base.precompile(Tuple{typeof(ArgMacros._converttype!),Type{T},Vector{String},String})
         Base.precompile(Tuple{typeof(ArgMacros._converttype!),Type{T},Nothing,String})
         for T2 in arg_types
             Base.precompile(Tuple{typeof(ArgMacros._converttype!),Type{T},T2,String})

test/runtests.jl

@@ -1,12 +1,12 @@
-println("Times for 8 argument example using all macros")
+println("Times for 11 argument example using all macros")
 println("Load Time (using ArgMacros)")
 @time using ArgMacros
 using Test
 
 # Commands Set 1
 let
     empty!(ARGS)
-    append!(ARGS, ["TEST STRING F", "-deeee", "30", "3.14", "-b=6.28", "--cc", "ArgMacros", "-a", "2"])
+    append!(ARGS, ["TEST STRING F", "-deeee", "30", "3.14", "-b=6.28", "--cc", "ArgMacros", "-a", "2", "4", "5", "6"])
 
     println("Inline Arguments Time with Precompile")
     let
@@ -22,6 +22,7 @@ let
             @positionaldefault Int 20 g
             @argtest g (x -> x % 10 == 0)
             @positionaloptional Float64 h
+            @positionalleftover Int64 i
         end
     end
 
@@ -38,6 +39,7 @@ let
         @positionaldefault Int 20 g
         @argtest g (x -> x % 10 == 0)
         @positionaloptional Float64 h
+        @positionalleftover Int64 i
     end
 
     println("Struct Arguments Time")
@@ -54,6 +56,7 @@ let
             @positionaldefault Int 20 g
             @argtest g (x -> x % 10 == 0)
             @positionaloptional Float64 h
+            @positionalleftover Int64 i
         end
 
         argsstruct = ArgsStruct()
@@ -72,6 +75,7 @@ let
         @positionaldefault Int 20 g
         @argtest g (x -> x % 10 == 0)
         @positionaloptional Float64 h
+        @positionalleftover Int64 i
     end
 
     println("Dict Arguments Time")
@@ -87,6 +91,7 @@ let
         @positionaldefault Int 20 g
         @argtest g (x -> x % 10 == 0)
         @positionaloptional Float64 h
+        @positionalleftover Int64 i
     end
 
     @testset "Correct, All Arguments" begin
@@ -98,7 +103,8 @@ let
             @test e == 4
             @test f == "TEST STRING F"
             @test g == 30
-            @test h  == 3.14
+            @test h == 3.14
+            @test i == [4, 5, 6]
         end
 
         @testset "Struct" begin
@@ -109,7 +115,8 @@ let
             @test argsstruct.e == 4
             @test argsstruct.f == "TEST STRING F"
             @test argsstruct.g == 30
-            @test argsstruct.h  == 3.14
+            @test argsstruct.h == 3.14
+            @test argsstruct.i == [4, 5, 6]
         end
 
         @testset "Tuple" begin
@@ -120,7 +127,8 @@ let
             @test argstuple.e == 4
             @test argstuple.f == "TEST STRING F"
             @test argstuple.g == 30
-            @test argstuple.h  == 3.14
+            @test argstuple.h == 3.14
+            @test argstuple.i == [4, 5, 6]
         end
 
         @testset "Dict" begin
@@ -131,7 +139,8 @@ let
             @test argsdict[:e] == 4
             @test argsdict[:f] == "TEST STRING F"
             @test argsdict[:g] == 30
-            @test argsdict[:h]  == 3.14
+            @test argsdict[:h] == 3.14
+            @test argsdict[:i] == [4, 5, 6]
         end
     end
 end
@@ -153,6 +162,7 @@ let
         @positionaldefault Int 20 g
         @argtest g (x -> x % 10 == 0)
         @positionaloptional Float64 h
+        @positionalleftover Int64 i
     end
 
     @structarguments false ArgsStruct begin
@@ -167,6 +177,7 @@ let
         @positionaldefault Int 20 g
         @argtest g (x -> x % 10 == 0)
         @positionaloptional Float64 h
+        @positionalleftover Int64 i
     end
 
     argsstruct = ArgsStruct()
@@ -183,6 +194,7 @@ let
         @positionaldefault Int 20 g
         @argtest g (x -> x % 10 == 0)
         @positionaloptional Float64 h
+        @positionalleftover Int64 i
     end
 
     argsdict = @dictarguments begin
@@ -197,6 +209,7 @@ let
         @positionaldefault Int 20 g
         @argtest g (x -> x % 10 == 0)
         @positionaloptional Float64 h
+        @positionalleftover Int64 i
     end
 
     @testset "Correct, Minimal Arguments" begin
@@ -209,6 +222,7 @@ let
             @test f == "OTHER TEST STRING F"
             @test g == 20
             @test isnothing(h)
+            @test isempty(i)
         end
 
         @testset "Struct" begin
@@ -220,6 +234,7 @@ let
             @test argsstruct.f == "OTHER TEST STRING F"
             @test argsstruct.g == 20
             @test isnothing(argsstruct.h)
+            @test isempty(argsstruct.i)
         end
 
         @testset "Tuple" begin
@@ -231,6 +246,7 @@ let
             @test argstuple.f == "OTHER TEST STRING F"
             @test argstuple.g == 20
             @test isnothing(argstuple.h)
+            @test isempty(argstuple.i)
         end
 
         @testset "Dict" begin
@@ -242,6 +258,7 @@ let
             @test argsdict[:f] == "OTHER TEST STRING F"
             @test argsdict[:g] == 20
             @test isnothing(argsdict[:h])
+            @test isempty(argsdict[:i])
         end
     end
 end