Remove help error condition

README.md

@@ -21,14 +21,10 @@ See the examples under the `examples/` directory.
 
 See http://lua-cliargs.netlify.com/ for the API docs.
 
-## Help listings `--help`
-
-A help listing will be automatically generated and accessed using the `--help` argument. When such an option is encountered, `cli:parse()` will abort and return `nil, string` with the help message; you are free to print it to the screen using `print()` if you want.
-
-You can also force its display in the code using `cli:print_help()`.
-
-This is the result for our example (see `examples/00_general.lua`):
+## Help Listings
 
+The library contains code to automatically generate help and usage text for all of the specified options and flags registered with the library; users should use the `cli:print_help()` function to generate it.
+Here is some sample output of this code (see `examples/00_general.lua` to see where these specific options are defined):
 ```
 Usage: cli_example.lua [OPTIONS]  INPUT  [OUTPUT-1 [OUTPUT-2 [...]]]
 
@@ -46,6 +42,8 @@ OPTIONS:
   --verbose             the script output will be very verbose
 ```
 
+This code can be used to specify a `-h/--help` option, see `examples/05_help.lua` for an example of how this can be done.
+
 ## Validations
 
 ### Runtime argument validation

examples/05_help.lua

@@ -0,0 +1,21 @@
+#!/usr/bin/lua
+
+--[[
+Shows how to use the builtin help functions to create a -h/--help option.
+--]]
+
+local cli = require "cliargs"
+
+function help()
+  cli:print_help()
+  os.exit(0)
+end
+
+cli:flag("-h, --help", "prints the help and usage text", help)
+
+local args, err = cli:parse()
+
+if not args then
+  print(err)
+  os.exit(1)
+end

spec/core_spec.lua

@@ -38,46 +38,12 @@ describe("cliargs::core", function()
       assert.equal(arguments[1], "--quiet")
     end)
 
-    it("generates the help listing but does not print it to STDOUT", function()
-      local res, err = cli:parse({'--help'})
-
-      assert.equal(type(res), "nil")
-      assert.equal(type(err), "string")
-    end)
-
     it("returns error strings but does not print them to STDOUT", function()
       local res, err = cli:parse({ "arg1" })
 
       assert.equal(type(res), "nil")
       assert.equal(type(err), "string")
     end)
-
-    describe('displaying the help listing', function()
-      local res, err
-
-      before_each(function()
-        cli:argument('INPUT', '...')
-        cli:flag('--quiet', '...')
-      end)
-
-      after_each(function()
-        assert.equal(type(res), "nil")
-        assert.equal(type(err), "string")
-        assert.equal(err, cli.printer.generate_help_and_usage())
-      end)
-
-      it('works with --help in the beginning', function()
-        res, err = helpers.parse(cli, '--help something')
-      end)
-
-      it('works with --help in the end of options', function()
-        res, err = helpers.parse(cli, '--quiet --help something')
-      end)
-
-      it('works with --help after an argument', function()
-        res, err = helpers.parse(cli, '--quiet something --help')
-      end)
-    end)
   end)
 
   describe('#parse - the --__DUMP__ special option', function()

src/cliargs/parser.lua

@@ -66,17 +66,6 @@ function p.invoke_command(args, options, done)
   return done()
 end
 
-function p.print_help(args, printer, done)
-  -- has --help or -h ? display the help listing and abort!
-  for _, v in pairs(args) do
-    if v == "--help" or v == "-h" then
-      return nil, printer.generate_help_and_usage()
-    end
-  end
-
-  return done()
-end
-
 function p.track_dump_request(args, done)
   -- starts with --__DUMP__; set dump to true to dump the parsed arguments
   if args[1] == "--__DUMP__" then
@@ -300,15 +289,13 @@ return function(arguments, options, printer)
   -- the spiral of DOOM:
   return p.invoke_command(args, options, function()
     return p.track_dump_request(args, function(dump, args_without_dump)
-      return p.print_help(args_without_dump, printer, function()
-        return p.process_arguments(args_without_dump, options, function(values, arg_count)
-          return p.validate(options, arg_count, function()
-            if dump then
-              return nil, printer.dump_internal_state(values)
-            else
-              return p.collect_results(values, options)
-            end
-          end)
+      return p.process_arguments(args_without_dump, options, function(values, arg_count)
+        return p.validate(options, arg_count, function()
+          if dump then
+            return nil, printer.dump_internal_state(values)
+          else
+            return p.collect_results(values, options)
+          end
         end)
       end)
     end)