Rename all mutating functions/macros with a !

E.g. add_arg_table -> add_arg_table! etc.
Create deprecation warnings for the exported ones.

Project.toml

@@ -1,9 +1,10 @@
 name = "ArgParse"
 uuid = "c7e460c6-2fb9-53a9-8c5b-16f535851c63"
-version = "1.0.0"
 author = ["Carlo Baldassi <[email protected]>"]
+version = "1.0.0"
 
 [deps]
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 TextWrap = "b718987f-49a8-5099-9789-dcd902bef87d"
 
 [compat]

README.md

@@ -32,10 +32,16 @@ See also the examples in the [examples directory](examples).
 ## Changes in release 1.0.0
 
 * Drop support for Julia versions v0.6/v0.7
+* Renamed a few functions and macros (old versions can be used but produced deprecation warnings):
+  + `@add_arg_table` → `@add_arg_table!`
+  + `add_arg_table` → `add_arg_table!`
+  + `add_arg_group` → `add_arg_group!`
+  + `set_default_arg_group` → `set_default_arg_group!`
+  + `import_settings` → `import_settings!`. The signature of this function has also changed:
+    `args_only` is now a keyword argument
 * Parsing does not exit julia by default when in interactive mode now
 * Added mutually-exclusive and/or required argument groups
 * Added command aliases
-* Renamed function `import_settings` → `import_settings!`
 
 ## Changes in release 0.6.2
 

docs/src/arg_table.md

@@ -13,11 +13,11 @@ Each entry of the table consist of an argument name and a list of argument setti
 There are two very similar methods to populate a table:
 
 ```@docs
-@add_arg_table
+@add_arg_table!
 ```
 
 ```@docs
-add_arg_table
+add_arg_table!
 ```
 
 ## Argument names
@@ -139,7 +139,7 @@ using ArgParse
 * `store_arg` (non-flag): store the argument. This is the default unless `nargs` is `0`. Example:
 
   ```
-  julia> @add_arg_table(settings, "arg", action => :store_arg);
+  julia> @add_arg_table!(settings, "arg", action => :store_arg);
 
   julia> parse_args(["x"], settings)
   Dict{String,Any} with 1 entry:
@@ -149,7 +149,7 @@ using ArgParse
   The result is a vector if `nargs` is a non-zero number, or one of `'*'`, `'+'`, `'R'`:
 
   ```
-  julia> @add_arg_table(settings, "arg", action => :store_arg, nargs => 2);
+  julia> @add_arg_table!(settings, "arg", action => :store_arg, nargs => 2);
 
   julia> parse_args(["x", "y"], settings)
   Dict{String,Any} with 1 entry:
@@ -159,7 +159,7 @@ using ArgParse
 * `store_true` (flag): store `true` if given, otherwise `false`. Example:
 
   ```
-  julia> @add_arg_table(settings, "-v", action => :store_true);
+  julia> @add_arg_table!(settings, "-v", action => :store_true);
 
   julia> parse_args([], settings)
   Dict{String,Any} with 1 entry:
@@ -173,7 +173,7 @@ using ArgParse
 * `store_false` (flag): store `false` if given, otherwise `true`. Example:
 
   ```
-  julia> @add_arg_table(settings, "-v", action => :store_false);
+  julia> @add_arg_table!(settings, "-v", action => :store_false);
 
   julia> parse_args([], settings)
   Dict{String,Any} with 1 entry:
@@ -188,7 +188,7 @@ using ArgParse
   Example:
 
   ```
-  julia> @add_arg_table(settings, "-v", action => :store_const, constant => 1, default => 0);
+  julia> @add_arg_table!(settings, "-v", action => :store_const, constant => 1, default => 0);
 
   julia> parse_args([], settings)
   Dict{String,Any} with 1 entry:
@@ -202,7 +202,7 @@ using ArgParse
 * `append_arg` (non-flag): append the argument to the result. Example:
 
   ```
-  julia> @add_arg_table(settings, "-x", action => :append_arg);
+  julia> @add_arg_table!(settings, "-x", action => :append_arg);
 
   julia> parse_args(["-x", "1", "-x", "2"], settings)
   Dict{String,Any} with 1 entry:
@@ -212,7 +212,7 @@ using ArgParse
   The result will be a `Vector{Vector}` if `nargs` is a non-zero number, or one of `'*'`, `'+'`, `'R'`:
 
   ```
-  julia> @add_arg_table(settings, "-x", action => :append_arg, nargs => '*');
+  julia> @add_arg_table!(settings, "-x", action => :append_arg, nargs => '*');
 
   julia> parse_args(["-x", "1", "2", "-x", "3"], settings)
   Dict{String,Any} with 1 entry:
@@ -222,7 +222,7 @@ using ArgParse
 * `append_const` (flag): append the value passed as `constant` in the entry settings. Example:
 
   ```
-  julia> @add_arg_table(settings, "-x", action => :append_const, constant => 1);
+  julia> @add_arg_table!(settings, "-x", action => :append_const, constant => 1);
 
   julia> parse_args(["-x", "-x", "-x"], settings)
   Dict{String,Any} with 1 entry:
@@ -233,7 +233,7 @@ using ArgParse
   invoked. Example:
 
   ```
-  julia> @add_arg_table(settings, "-x", action => :count_invocations);
+  julia> @add_arg_table!(settings, "-x", action => :count_invocations);
 
   julia> parse_args(["-x", "-x", "-x"], settings)
   Dict{String,Any} with 1 entry:
@@ -244,7 +244,7 @@ using ArgParse
   `false`. Example:
 
   ```
-  julia> @add_arg_table(settings, "-x", action => :show_help);
+  julia> @add_arg_table!(settings, "-x", action => :show_help);
 
   julia> parse_args(["-x"], settings)
   usage: <PROGRAM> [-x]
@@ -259,7 +259,7 @@ using ArgParse
   ```
   julia> settings.version = "1.0";
 
-  julia> @add_arg_table(settings, "-x", action => :show_version);
+  julia> @add_arg_table!(settings, "-x", action => :show_version);
 
   julia> parse_args(["-v"], settings)
   1.0
@@ -285,7 +285,7 @@ using ArgParse
 function parse_commandline()
     s = ArgParseSettings()
 
-    @add_arg_table s begin
+    @add_arg_table! s begin
         "cmd1", "C"
             help = "first command"
             action = :command
@@ -348,7 +348,7 @@ optional arguments:
 
 The argument settings and tables for commands can be accessed by using a dict-like notation, i.e. `settings["cmd1"]` is an
 `ArgParseSettings` object specific to the `"cmd1"` command. Therefore, to populate a command sub-argument-table, simply
-use `@add_arg_table(settings["cmd1"], table...)` and similar.
+use `@add_arg_table!(settings["cmd1"], table...)` and similar.
 
 These sub-settings are created when a command is added to the argument table, and by default they inherit their parent general
 settings except for the `prog` setting (which is auto-generated, as can be seen in the above example) and the
@@ -376,7 +376,7 @@ arguments, displayed in that order. Example:
 ```@repl args
 settings = ArgParseSettings(exit_after_help = false);
 
-@add_arg_table settings begin
+@add_arg_table! settings begin
    "--opt"
    "arg"
      required = true
@@ -395,44 +395,44 @@ options in the group can be provided. A group can also be declared to be require
 one argument in the group needs to be provided.
 
 ```@docs
-add_arg_group
+add_arg_group!
 ```
 
 ```@docs
-set_default_arg_group
+set_default_arg_group!
 ```
 
-Besides setting a default group with `add_arg_group` and `set_default_group`, it's also possible to assign individual arguments
-to a group by using the `group` setting in the argument table entry, which follows the same rules as `set_default_group`.
+Besides setting a default group with `add_arg_group!` and `set_default_group!`, it's also possible to assign individual arguments
+to a group by using the `group` setting in the argument table entry, which follows the same rules as `set_default_group!`.
 
 Note that if the `add_help` or `add_version` general settings are `true`, the `--help, -h` and `--version` options
 will always be added to the `optional` group.
 
 ## Argument table styles
 
-Here are some examples of styles for the [`@add_arg_table`](@ref) marco and [`add_arg_table`](@ref) function invocation:
+Here are some examples of styles for the [`@add_arg_table!`](@ref) marco and [`add_arg_table!`](@ref) function invocation:
 
 ```julia
-@add_arg_table settings begin
+@add_arg_table! settings begin
     "--opt", "-o"
         help = "an option"
     "arg"
         help = "a positional argument"
 end
 
-@add_arg_table(settings
+@add_arg_table!(settings
     , ["--opt", "-o"]
     ,    help => "an option"
     , "arg"
     ,    help => "a positional argument"
     )
 
-@add_arg_table settings begin
+@add_arg_table! settings begin
     (["--opt", "-o"]; help = an option)
     ("arg"; help = "a positional argument")
 end
 
-@add_arg_table(settings,
+@add_arg_table!(settings,
     ["-opt", "-o"],
     begin
         help = "an option"
@@ -442,7 +442,7 @@ end
         help = "a positional argument"
     end)
 
-add_arg_table(settings,
+add_arg_table!(settings,
     ["-opt", "-o"], Dict(:help => "an option"),
     "arg"         , Dict(:help => "a positional argument")
     )

docs/src/conflicts.md

@@ -24,5 +24,5 @@ the resolution of most of the conflicts in favor of the newest added entry. The
 * In case of duplicate positional arguments metavars, the older argument is deleted
 * A command can override an argument with the same destination key
 * However, an argument can never override a command; neither can a command override another command when added
-  with `@add_arg_table` (compatible commands are merged by [`import_settings`](@ref) though)
+  with `@add_arg_table!` (compatible commands are merged by [`import_settings!`](@ref) though)
 * Conflicting command aliases are removed

docs/src/import.md

@@ -4,7 +4,5 @@ It may be useful in some cases to import an argument table into the one which is
 specialized versions of a common interface.
 
 ```@docs
-import_settings
+import_settings!
 ```
-
-

docs/src/index.md

@@ -17,7 +17,7 @@ as well.
 To install the module, use Julia's package manager: start pkg mode by pressing `]` and then enter:
 
 ```
-(v1.0) pkg> add ArgParse
+(v1.3) pkg> add ArgParse
 ```
 
 Dependencies will be installed automatically.
@@ -31,12 +31,12 @@ using ArgParse
 ```
 
 There are two main steps for defining a command-line interface: creating an [`ArgParseSettings`](@ref) object, and
-populating it with allowed arguments and options using either the macro [`@add_arg_table`](@ref) or the
-function [`add_arg_table`](@ref) (see the [Argument table](@ref) section):
+populating it with allowed arguments and options using either the macro [`@add_arg_table!`](@ref) or the
+function [`add_arg_table!`](@ref) (see the [Argument table](@ref) section):
 
 ```
 s = ArgParseSettings()
-@add_arg_table s begin
+@add_arg_table! s begin
     "--opt1"
         help = "an option with an argument"
     "--opt2", "-o"
@@ -85,7 +85,7 @@ using ArgParse
 function parse_commandline()
     s = ArgParseSettings()
 
-    @add_arg_table s begin
+    @add_arg_table! s begin
         "--opt1"
             help = "an option with an argument"
         "--opt2", "-o"
@@ -169,7 +169,7 @@ Parsed args:
 
 From these examples, a number of things can be noticed:
 
-* `opt1` defaults to `nothing`, since no `default` setting was used for it in `@add_arg_table`
+* `opt1` defaults to `nothing`, since no `default` setting was used for it in `@add_arg_table!`
 * `opt1` argument type, begin unspecified, defaults to `Any`, but in practice it's parsed as a
   string (e.g. `"2+2"`)
 * `opt2` instead has `Int` argument type, so `"4"` will be parsed and converted to an integer,

examples/argparse_example1.jl

@@ -7,7 +7,7 @@ function main(args)
     # initialize the settings (the description is for the help screen)
     s = ArgParseSettings(description = "Example 1 for argparse.jl: minimal usage.")
 
-    @add_arg_table s begin
+    @add_arg_table! s begin
         "--opt1"               # an option (will take an argument)
         "--opt2", "-o"         # another option, with short form
         "arg1"                 # a positional argument

examples/argparse_example2.jl

@@ -8,7 +8,7 @@ function main(args)
                          "flags, options help, " *
                          "required arguments.")
 
-    @add_arg_table s begin
+    @add_arg_table! s begin
         "--opt1"
             help = "an option"     # used by the help screen
         "--opt2", "-o"

examples/argparse_example3.jl

@@ -12,7 +12,7 @@ function main(args)
                          version = "Version 1.0", # version info
                          add_version = true)      # audo-add version option
 
-    @add_arg_table s begin
+    @add_arg_table! s begin
         "--opt1"
             nargs = '?'              # '?' means optional argument
             arg_type = Int           # only Int arguments allowed

examples/argparse_example4.jl

@@ -10,7 +10,7 @@ function main(args)
                          "dest_name, metvar, range_tested, " *
                          "alternative actions.")
 
-    @add_arg_table s begin
+    @add_arg_table! s begin
         "--opt1"
             action = :append_const   # appends 'constant' to 'dest_name'
             arg_type = String        # the only utility of this is restricting the dest array type

examples/argparse_example5.jl

@@ -8,7 +8,7 @@ function main(args)
                              # which we want to extend
 
     # So we just add a simple table
-    @add_arg_table s0 begin
+    @add_arg_table! s0 begin
         "--parent-flag", "-o"
             action=>"store_true"
             help=>"parent flag"
@@ -25,11 +25,11 @@ function main(args)
                          add_help = false,           # disable auto-add of --help option
                          version = "Version 1.0")    # we set the version info, but --version won't be added
 
-    import_settings(s, s0)       # now s has all of s0 arguments (except help/version)
+    import_settings!(s, s0)      # now s has all of s0 arguments (except help/version)
 
     s.error_on_conflict = false  # do not error-out when trying to override an option
 
-    @add_arg_table s begin
+    @add_arg_table! s begin
         "-o"                       # this will partially override s0's --parent-flag
             action = :store_true
             help = "child flag"

examples/argparse_example6.jl

@@ -7,7 +7,7 @@ function main(args)
     s = ArgParseSettings("Example 6 for argparse.jl: " *
                          "commands and their associated sub-tables.")
 
-    @add_arg_table s begin
+    @add_arg_table! s begin
         "run"
             action = :command        # adds a command which will be read from an argument
             help = "start running mode"
@@ -16,7 +16,7 @@ function main(args)
             help = "start jumping mode"
     end
 
-    @add_arg_table s["run"] begin    # add command arg_table: same as usual, but invoked on s["cmd"]
+    @add_arg_table! s["run"] begin    # add command arg_table: same as usual, but invoked on s["cmd"]
         "--speed"
             arg_type = Float64
             default = 10.
@@ -29,7 +29,7 @@ function main(args)
     s["jump"].autofix_names = true                     # this uses dashes in long options, underscores
                                                        # in auto-generated dest_names
 
-    @add_arg_table s["jump"] begin
+    @add_arg_table! s["jump"] begin
         "--higher"
             action = :store_true
             help = "enhance jumping"