Add callbacks for options parsing

This allows the user to specify a function to be called whenever an
option is parsed. Just pass a callback function to `cli:add_opt` and
that function will be called when the parser successfully parses the
option.

Arguments to the callback function are:
* The option key specified on the command-line
* The value being assigned to the option
* The alternate key for the option (i.e. expanded-key)

Author: o-lim

examples/00_general.lua

@@ -9,6 +9,14 @@ Try this file with the following commands lines;
 
 local cli = require "cliargs"
 
+local function print_version(key, value, altkey)
+  -- this is called when the flag -v or --version is set
+  if key == 'version' then
+    print("cli_example.lua: version 1.2.1")
+    os.exit(0)
+  end
+end
+
 cli:set_name("cli_example.lua")
 
 -- Required arguments:
@@ -26,8 +34,8 @@ cli:set_name("cli_example.lua")
 -- Flags: a flag is a boolean option. Defaults to false
   -- A flag with short-key notation only
   cli:add_flag("-d", "script will run in DEBUG mode")
-  -- A flag with both the short-key and --expanded-key notations
-  cli:add_flag("-v, --version", "prints the program's version and exits")
+  -- A flag with both the short-key and --expanded-key notations, and callback function
+  cli:add_flag("-v, --version", "prints the program's version and exits", print_version)
   -- A flag with --expanded-key notation only
   cli:add_flag("--verbose", "the script output will be very verbose")
 
@@ -43,12 +51,6 @@ end
 -- upon successful parsing cliargs will delete itslef to free resources
 -- for k,item in pairs(args) do print(k .. " => " .. tostring(item)) end
 
--- checking for flags: is -v or --version set?
-if args["v"] then
-  print("cli_example.lua: version 1.2.1")
-  os.exit(0)
-end
-
 print("Input file: " .. args["INPUT"])
 print("Output file: " .. args["o"])
 

examples/02_parse_callbacks.lua

@@ -0,0 +1,35 @@
+--[[
+
+Shows how to define a callback to be invoked as soon as an option is parsed.
+Callbacks are useful for abruptive options like "--help" or "--version" where
+you might want to stop the execution of the parser/program if passed.
+
+Try this file with the following commands lines;
+  example.lua --version
+  example.lua -v
+  example.lua
+--]]
+
+local cli = require "cliargs"
+
+local function print_version(key, value, altkey)
+  -- this is called when the flag -v or --version is set
+  if key == 'version' then
+    print("example.lua: version 1.2.1")
+    os.exit(0)
+  end
+end
+
+cli:set_name("try_my_version.lua")
+cli:add_flag("-v, --version", "prints the program's version and exits", print_version)
+
+-- Parses from _G['arg']
+local args = cli:parse()
+
+if not args then
+  -- something wrong happened and an error was printed
+  os.exit(1)
+end
+
+-- if we got to this point, it means -v (or --version) were not passed:
+print "Why, hi!"

spec/cliargs_parsing_spec.lua

@@ -314,4 +314,49 @@ describe("Testing cliargs library parsing commandlines", function()
     assert.is.truthy(result)
     assert.are.equal("", result.compress)
   end)
+
+  describe("Tests parsing with callback", function()
+    local cb = {}
+
+    local function callback(key, value, altkey)
+        cb.key, cb.value, cb.altkey = key, value, altkey
+    end
+
+    before_each(function()
+      cb = {}
+    end)
+
+    it("tests short-key option", function()
+      _G.arg = { "-k", "myvalue" }
+      cli:add_option("-k, --long-key=VALUE", "key descriptioin", "", callback)
+      local expected = { k = "myvalue", ["long-key"] = "myvalue" }
+      local result = cli:parse()
+      assert.are.same(expected, result)
+      assert.are.equal(cb.key, "k")
+      assert.are.equal(cb.value, "myvalue")
+      assert.are.equal(cb.altkey, "long-key")
+    end)
+
+    it("tests expanded-key option", function()
+      _G.arg = { "--long-key", "val" }
+      cli:add_option("-k, --long-key=VALUE", "key descriptioin", "", callback)
+      local expected = { k = "val", ["long-key"] = "val" }
+      local result = cli:parse()
+      assert.are.same(expected, result)
+      assert.are.equal(cb.key, "long-key")
+      assert.are.equal(cb.value, "val")
+      assert.are.equal(cb.altkey, "k")
+    end)
+
+    it("tests expanded-key flag with not short-key", function()
+      _G.arg = { "--version" }
+      cli:add_flag("--version", "prints the version and exits", callback)
+      local expected = { version = true }
+      local result = cli:parse()
+      assert.are.same(expected, result)
+      assert.are.equal(cb.key, "version")
+      assert.are.equal(cb.value, true)
+      assert.are.equal(cb.altkey, nil)
+    end)
+  end)
 end)

src/cliargs.lua

@@ -139,7 +139,7 @@ end
 ---
 --- ### Parameters
 --- 1. **key**: the argument's "name" that will be displayed to the user
---- 1. **desc**: a description of the argument
+--- 2. **desc**: a description of the argument
 ---
 --- ### Usage example
 --- The following will parse the argument (if specified) and set its value in `args["root"]`:
@@ -162,9 +162,9 @@ end
 ---
 --- ### Parameters
 --- 1. **key**: the argument's "name" that will be displayed to the user
---- 1. **desc**: a description of the argument
---- 1. **default**: *optional*; specify a default value (the default is "")
---- 1. **maxcount**: *optional*; specify the maximum number of occurences allowed (default is 1)
+--- 2. **desc**: a description of the argument
+--- 3. **default**: *optional*; specify a default value (the default is "")
+--- 4. **maxcount**: *optional*; specify the maximum number of occurences allowed (default is 1)
 ---
 --- ### Usage example
 --- The following will parse the argument (if specified) and set its value in `args["root"]`:
@@ -192,13 +192,14 @@ end
 --- if the 2nd notation is used then a value can be defined after an `=` (`'-key, --expanded-key=VALUE'`).
 --- As a final option it is possible to only use the expanded key (eg. `'--expanded-key'`) both with and
 --- without a value specified.
---- 1. **desc**: a description for the argument to be shown in --help
---- 1. **default**: *optional*; specify a default value (the default is "")
+--- 2. **desc**: a description for the argument to be shown in --help
+--- 3. **default**: *optional*; specify a default value (the default is "")
+--- 4. **callback**: *optional*; specify a function to call when this option is parsed (the default is nil)
 ---
 --- ### Usage example
 --- The following option will be stored in `args["i"]` and `args["input"]` with a default value of `my_file.txt`:
 --- `cli:add_option("-i, --input=FILE", "path to the input file", "my_file.txt")`
-function cli:add_opt(key, desc, default)
+function cli:add_opt(key, desc, default, callback)
   -- parameterize the key if needed, possible variations:
   -- 1. -key
   -- 2. -key VALUE
@@ -219,6 +220,14 @@ function cli:add_opt(key, desc, default)
     ),
     "Default argument: expected a string, nil, or {}"
   )
+  assert(
+    (
+      type(callback) == "function"
+      or callback == nil
+      or (getmetatable(callback) or {}).__call
+    ),
+    "Callback argument: expected a function or nil"
+  )
 
   local k, ek, v = disect(key)
 
@@ -244,6 +253,7 @@ function cli:add_opt(key, desc, default)
     label = key,
     flag = (default == false),
     value = default,
+    callback = callback,
   }
 
   table.insert(self.optional, entry)
@@ -256,9 +266,10 @@ end
 ---
 --- ### Parameters
 -- 1. **key**: the argument's key
--- 1. **desc**: a description of the argument to be displayed in the help listing
-function cli:add_flag(key, desc)
-  self:add_opt(key, desc, false)
+-- 2. **desc**: a description of the argument to be displayed in the help listing
+-- 4. **callback**: *optional*; specify a function to call when this flag is parsed (the default is nil)
+function cli:add_flag(key, desc, callback)
+  self:add_opt(key, desc, false, callback)
 end
 
 --- Parses the arguments found in #arg and returns a table with the populated values.
@@ -268,7 +279,7 @@ end
 --- ### Parameters
 --- 1. **arguments**: set this to arg
 --- 1. **noprint**: set this flag to prevent any information (error or help info) from being printed
---- 1. **dump**: set this flag to dump the parsed variables for debugging purposes, alternatively
+--- 2. **dump**: set this flag to dump the parsed variables for debugging purposes, alternatively
 --- set the first option to --__DUMP__ (option with 2 trailing and leading underscores) to dump at runtime.
 ---
 --- ### Returns
@@ -372,6 +383,17 @@ function cli:parse(arguments, noprint, dump)
     else
       entry.value = optval
     end
+
+    -- invoke the option's parse-callback, if any
+    if entry.callback then
+      local altkey = entry.key
+
+      if optkey == entry.key then
+        altkey = entry.expanded_key
+      end
+
+      entry.callback(optkey, optval, altkey)
+    end
   end
 
   -- missing any required arguments, or too many?