optparse_spec.yaml

before:
  hell = require "specl.shell"

specify std.optparse:
- before: |
    OptionParser = require "std.optparse"

    help = [[
    parseme (stdlib spec) 0α1

    Copyright © 2015 Gary V. Vaughan
    This test program comes with ABSOLUTELY NO WARRANTY.

    Usage: parseme [<options>] <file>...

    Banner text.

    Long description.

    Options:

      -h, --help               display this help, then exit
          --version            display version information, then exit
      -b                       a short option with no long option
          --long               a long option with no short option
          --another-long       a long option with internal hypen
          --true               a Lua keyword as an option name
      -v, --verbose            a combined short and long option
      -n, --dryrun, --dry-run  several spellings of the same option
      -u, --name=USER          require an argument
      -o, --output=[FILE]      accept an optional argument
      --                       end of options

    Footer text.

    Please report bugs at <http://github.com/lua-stdlib/lua-stdlib/issues>.
    ]]

    -- strip off the leading whitespace required for YAML
    parser = OptionParser (help:gsub ("^    ", ""))

- context when required:
  - context by name:
    - it does not touch the global table:
        expect (show_apis {added_to="_G", by="std.optparse"}).
          to_equal {}

- describe OptionParser:
  - it recognises the program name:
      expect (parser.program).to_be "parseme"
  - it recognises the version number:
      expect (parser.version).to_be "0α1"
  - it recognises the version text:
      expect (parser.versiontext).
        to_match "^parseme .*Copyright .*NO WARRANTY%."
  - it recognises the help text: |
      expect (parser.helptext).
        to_match ("^Usage: parseme .*Banner .*Long .*Options:.*" ..
                      "Footer .*/issues>%.")
  - it diagnoses incorrect input text:
      expect (OptionParser "garbage in").to_raise "argument must match"

- describe parser:
  - before: |
      code = [[
        package.path = "]] .. package.path .. [["
        local OptionParser = require 'std.optparse'
        local help = [=[]] .. help .. [[]=]
        help = help:match ("^[%s\n]*(.-)[%s\n]*$")

        local parser = OptionParser (help)
        local arg, opts = parser:parse (_G.arg)

        o = {}
        for k, v in pairs (opts) do
          table.insert (o, k .. " = " .. tostring (v))
        end
        if #o > 0 then
          table.sort (o)
          print ("opts = { " .. table.concat (o, ", ") .. " }")
        end
        if #arg > 0 then
          print ("args = { " .. table.concat (arg, ", ") .. " }")
        end
      ]]
      parse = bind (luaproc, {code})

  - it responds to --version with version text:
      expect (parse {"--version"}).
        to_match_output "^%s*parseme .*Copyright .*NO WARRANTY%.\n$"
  - it responds to --help with help text: |
      expect (parse {"--help"}).
        to_match_output ("^%s*Usage: parseme .*Banner.*Long.*" ..
                              "Options:.*Footer.*/issues>%.\n$")
  - it leaves behind unrecognised short options:
      expect (parse {"-x"}).to_output "args = { -x }\n"
  - it recognises short options:
      expect (parse {"-b"}).to_output "opts = { b = true }\n"
  - it leaves behind unrecognised options:
      expect (parse {"--not-an-option"}).
        to_output "args = { --not-an-option }\n"
  - it recognises long options:
      expect (parse {"--long"}).to_output "opts = { long = true }\n"
  - it recognises long options with hyphens:
      expect (parse {"--another-long"}).
        to_output "opts = { another_long = true }\n"
  - it recognises long options named after Lua keywords:
      expect (parse {"--true"}).to_output "opts = { true = true }\n"
  - it recognises combined short and long option specs:
      expect (parse {"-v"}).to_output "opts = { verbose = true }\n"
      expect (parse {"--verbose"}).to_output "opts = { verbose = true }\n"
  - it recognises options with several spellings:
      expect (parse {"-n"}).to_output "opts = { dry_run = true }\n"
      expect (parse {"--dry-run"}).to_output "opts = { dry_run = true }\n"
      expect (parse {"--dryrun"}).to_output "opts = { dry_run = true }\n"
  - it recognises end of options marker:
      expect (parse {"-- -n"}).to_output "args = { -n }\n"
  - context given an unhandled long option:
    - it leaves behind unmangled argument:
        expect (parse {"--not-an-option=with-an-argument"}).
          to_output "args = { --not-an-option=with-an-argument }\n"
  - context given an option with a required argument:
    - it records an argument to a long option following an '=' delimiter:
        expect (parse {"--name=Gary"}).
          to_output "opts = { name = Gary }\n"
    - it records an argument to a short option without a space:
        expect (parse {"-uGary"}).
          to_output "opts = { name = Gary }\n"
    - it records an argument to a long option following a space:
        expect (parse {"--name Gary"}).
          to_output "opts = { name = Gary }\n"
    - it records an argument to a short option following a space:
        expect (parse {"-u Gary"}).
          to_output "opts = { name = Gary }\n"
    - it diagnoses a missing argument:
        expect (parse {"--name"}).
          to_contain_error "'--name' requires an argument"
        expect (parse {"-u"}).
          to_contain_error "'-u' requires an argument"
  - context given an option with an optional argument:
    - it records an argument to a long option following an '=' delimiter:
        expect (parse {"--output=filename"}).
          to_output "opts = { output = filename }\n"
    - it records an argument to a short option without a space:
        expect (parse {"-ofilename"}).
          to_output "opts = { output = filename }\n"
    - it records an argument to a long option following a space:
        expect (parse {"--output filename"}).
          to_output "opts = { output = filename }\n"
    - it records an argument to a short option following a space:
        expect (parse {"-o filename"}).
          to_output "opts = { output = filename }\n"
    - it doesn't consume the following option:
        expect (parse {"--output -v"}).
          to_output "opts = { output = true, verbose = true }\n"
        expect (parse {"-o -v"}).
          to_output "opts = { output = true, verbose = true }\n"
  - context when splitting combined short options:
    - it separates non-argument options:
        expect (parse {"-bn"}).
          to_output "opts = { b = true, dry_run = true }\n"
        expect (parse {"-vbn"}).
          to_output "opts = { b = true, dry_run = true, verbose = true }\n"
    - it stops separating at a required argument option:
        expect (parse {"-vuname"}).
          to_output "opts = { name = name, verbose = true }\n"
        expect (parse {"-vuob"}).
          to_output "opts = { name = ob, verbose = true }\n"
    - it stops separating at an optional argument option:
        expect (parse {"-vofilename"}).
          to_output "opts = { output = filename, verbose = true }\n"
        expect (parse {"-vobn"}).
          to_output "opts = { output = bn, verbose = true }\n"
    - it leaves behind unsplittable short options:
        expect (parse {"-xvb"}).to_output "args = { -xvb }\n"
        expect (parse {"-vxb"}).to_output "args = { -vxb }\n"
        expect (parse {"-vbx"}).to_output "args = { -vbx }\n"
    - it separates short options before unsplittable options:
        expect (parse {"-vb -xvb"}).
          to_output "opts = { b = true, verbose = true }\nargs = { -xvb }\n"
        expect (parse {"-vb -vxb"}).
          to_output "opts = { b = true, verbose = true }\nargs = { -vxb }\n"
        expect (parse {"-vb -vbx"}).
          to_output "opts = { b = true, verbose = true }\nargs = { -vbx }\n"
    - it separates short options after unsplittable options:
        expect (parse {"-xvb -vb"}).
          to_output "opts = { b = true, verbose = true }\nargs = { -xvb }\n"
        expect (parse {"-vxb -vb"}).
          to_output "opts = { b = true, verbose = true }\nargs = { -vxb }\n"
        expect (parse {"-vbx -vb"}).
          to_output "opts = { b = true, verbose = true }\nargs = { -vbx }\n"

  - context with option defaults:
    - before: |
        function main (arg)
          local OptionParser = require "std.optparse"
          local parser = OptionParser ("program 0\nUsage: program\n" ..
                           "  -x  set x\n" ..
                           "  -y  set y\n" ..
                           "  -z  set z\n")
          local state = { arg = {}, opts = { x={"t"}, y=false }}
          state.arg, state.opts = parser:parse (arg, state.opts)
          return state
        end
    - it prefers supplied argument:
        expect (main {"-x", "-y"}).
          to_equal { arg = {}, opts = { x=true, y=true }}
        expect (main {"-x", "-y", "-z"}).
          to_equal { arg = {}, opts = { x=true, y=true, z=true }}
        expect (main {"-w", "-x", "-y"}).
          to_equal { arg = {"-w"}, opts = { x=true, y=true }}
    - it defers to default value:
        expect (main {}).
          to_equal { arg = {}, opts = { x={"t"}, y=false }}
        expect (main {"-z"}).
          to_equal { arg = {}, opts = { x={"t"}, y=false, z=true }}
        expect (main {"-w"}).
          to_equal { arg = {"-w"}, opts = { x={"t"}, y=false }}

  - context with io.die:
    - before: |
        runscript = function (code)
          return luaproc ([[
            local OptionParser = require "std.optparse"
            local parser = OptionParser ("program 0\nUsage: program\n")
            _G.arg, _G.opts = parser:parse (_G.arg)
            ]] .. code .. [[
            require "std.io".die "By 'eck!"
          ]])
        end
    - it prefers `prog.name` to `opts.program`: |
        code = [[prog = { file = "file", name = "name" }]]
        expect (runscript (code)).to_fail_while_matching ": name: By 'eck!\n"
    - it prefers `prog.file` to `opts.program`: |
        code = [[prog = { file = "file" }]]
        expect (runscript (code)).to_fail_while_matching ": file: By 'eck!\n"
    - it appends `prog.line` if any to `prog.file` over using `opts`: |
        code = [[
          prog = { file = "file", line = 125 }; opts.line = 99]]
        expect (runscript (code)).
          to_fail_while_matching ": file:125: By 'eck!\n"
    - it prefixes `opts.program` if any: |
        expect (runscript ("")).to_fail_while_matching ": program: By 'eck!\n"
    - it appends `opts.line` if any, to `opts.program`: |
        code = [[opts.line = 99]]
        expect (runscript (code)).
          to_fail_while_matching ": program:99: By 'eck!\n"

  - context with io.warn:
    - before: |
        runscript = function (code)
          return luaproc ([[
            local OptionParser = require "std.optparse"
            local parser = OptionParser ("program 0\nUsage: program\n")
            _G.arg, _G.opts = parser:parse (_G.arg)
            ]] .. code .. [[
            require "std.io".warn "Ayup!"
          ]])
        end
    - it prefers `prog.name` to `opts.program`: |
        code = [[prog = { file = "file", name = "name" }]]
        expect (runscript (code)).to_output_error "name: Ayup!\n"
    - it prefers `prog.file` to `opts.program`: |
        code = [[prog = { file = "file" }]]
        expect (runscript (code)).to_output_error "file: Ayup!\n"
    - it appends `prog.line` if any to `prog.file` over using `opts`: |
        code = [[
          prog = { file = "file", line = 125 }; opts.line = 99]]
        expect (runscript (code)).
          to_output_error "file:125: Ayup!\n"
    - it prefixes `opts.program` if any: |
        expect (runscript ("")).to_output_error "program: Ayup!\n"
    - it appends `opts.line` if any, to `opts.program`: |
        code = [[opts.line = 99]]
        expect (runscript (code)).
          to_output_error "program:99: Ayup!\n"

- describe parser:on:
  - before: |
      function parseargs (onargstr, arglist)
        code = [[
          package.path = "]] .. package.path .. [["
          local OptionParser = require 'std.optparse'
          local help = [=[]] .. help .. [[]=]
          help = help:match ("^[%s\n]*(.-)[%s\n]*$")

          local parser = OptionParser (help)

          parser:on (]] .. onargstr .. [[)

          _G.arg, _G.opts = parser:parse (_G.arg)

          o = {}
          for k, v in pairs (opts) do
            table.insert (o, k .. " = " .. tostring (v))
          end
          if #o > 0 then
            table.sort (o)
            print ("opts = { " .. table.concat (o, ", ") .. " }")
          end
          if #arg > 0 then
            print ("args = { " .. table.concat (arg, ", ") .. " }")
          end
        ]]

        return luaproc (code, arglist)
      end

  - it recognises short options:
      expect (parseargs ([["x"]], {"-x"})).
        to_output "opts = { x = true }\n"
  - it recognises long options:
      expect (parseargs([["something"]], {"--something"})).
        to_output "opts = { something = true }\n"
  - it recognises long options with hyphens:
      expect (parseargs([["some-thing"]], {"--some-thing"})).
        to_output "opts = { some_thing = true }\n"
  - it recognises long options named after Lua keywords:
      expect (parseargs ([["if"]], {"--if"})).
        to_output "opts = { if = true }\n"
  - it recognises combined short and long option specs:
      expect (parseargs ([[{"x", "if"}]], {"-x"})).
        to_output "opts = { if = true }\n"
      expect (parseargs ([[{"x", "if"}]], {"--if"})).
        to_output "opts = { if = true }\n"
  - it recognises options with several spellings:
      expect (parseargs ([[{"x", "blah", "if"}]], {"-x"})).
        to_output "opts = { if = true }\n"
      expect (parseargs ([[{"x", "blah", "if"}]], {"--blah"})).
        to_output "opts = { if = true }\n"
      expect (parseargs ([[{"x", "blah", "if"}]], {"--if"})).
        to_output "opts = { if = true }\n"
  - it recognises end of options marker:
      expect (parseargs ([["x"]], {"--", "-x"})).
        to_output "args = { -x }\n"
  - context given an option with a required argument:
    - it records an argument to a short option without a space:
        expect (parseargs ([["x", parser.required]], {"-y", "-xarg", "-b"})).
          to_contain_output "opts = { b = true, x = arg }"
    - it records an argument to a short option following a space:
        expect (parseargs ([["x", parser.required]], {"-y", "-x", "arg", "-b"})).
          to_contain_output "opts = { b = true, x = arg }\n"
    - it records an argument to a long option following a space:
        expect (parseargs ([["this", parser.required]], {"--this", "arg"})).
          to_output "opts = { this = arg }\n"
    - it records an argument to a long option following an '=' delimiter:
        expect (parseargs ([["this", parser.required]], {"--this=arg"})).
          to_output "opts = { this = arg }\n"
    - it diagnoses a missing argument:
        expect (parseargs ([[{"x", "this"}, parser.required]], {"-x"})).
          to_contain_error "'-x' requires an argument"
        expect (parseargs ([[{"x", "this"}, parser.required]], {"--this"})).
          to_contain_error "'--this' requires an argument"
    - context with a boolean handler function:
      - it records a truthy argument:
          for _, optarg in ipairs {"1", "TRUE", "true", "yes", "Yes", "y"}
          do
            expect (parseargs ([["x", parser.required, parser.boolean]],
                               {"-x", optarg})).
              to_output "opts = { x = true }\n"
          end
      - it records a falsey argument:
          for _, optarg in ipairs {"0", "FALSE", "false", "no", "No", "n"}
          do
            expect (parseargs ([["x", parser.required, parser.boolean]],
                               {"-x", optarg})).
              to_output "opts = { x = false }\n"
          end
    - context with a file handler function:
      - it records an existing file:
          expect (parseargs ([["x", parser.required, parser.file]],
                             {"-x", "/dev/null"})).
            to_output "opts = { x = /dev/null }\n"
      - it diagnoses a missing file: |
          expect (parseargs ([["x", parser.required, parser.file]],
                             {"-x", "/this/file/does/not/exist"})).
            to_contain_error "error: /this/file/does/not/exist: "
    - context with a custom handler function:
      - it calls the handler:
          expect (parseargs ([["x", parser.required, function (p,o,a)
                                                       return "custom"
                                                     end
                             ]], {"-x", "ignored"})).
            to_output "opts = { x = custom }\n"
      - it diagnoses a missing argument:
          expect (parseargs ([["x", parser.required, function (p,o,a)
                                                       return "custom"
                                                     end
                             ]], {"-x"})).
            to_contain_error "option '-x' requires an argument"
  - context given an option with an optional argument:
    - it records an argument to a short option without a space:
        expect (parseargs ([["x", parser.optional]], {"-y", "-xarg", "-b"})).
          to_contain_output "opts = { b = true, x = arg }"
    - it records an argument to a short option following a space:
        expect (parseargs ([["x", parser.optional]], {"-y", "-x", "arg", "-b"})).
          to_contain_output "opts = { b = true, x = arg }\n"
    - it records an argument to a long option following a space:
        expect (parseargs ([["this", parser.optional]], {"--this", "arg"})).
          to_output "opts = { this = arg }\n"
    - it records an argument to a long option following an '=' delimiter:
        expect (parseargs ([["this", parser.optional]], {"--this=arg"})).
          to_output "opts = { this = arg }\n"
    - it does't consume the following option:
        expect (parseargs ([[{"x", "this"}, parser.optional]], {"-x", "-b"})).
          to_output "opts = { b = true, this = true }\n"
          expect (parseargs ([[{"x", "this"}, parser.optional]], {"--this", "-b"})).
          to_output "opts = { b = true, this = true }\n"
    - context with a boolean handler function:
      - it records a truthy argument:
          for _, optarg in ipairs {"1", "TRUE", "true", "yes", "Yes", "y"}
          do
            expect (parseargs ([["x", parser.optional, parser.boolean]],
                               {"-x", optarg})).
              to_output "opts = { x = true }\n"
          end
      - it records a falsey argument:
          for _, optarg in ipairs {"0", "FALSE", "false", "no", "No", "n"}
          do
            expect (parseargs ([["x", parser.optional, parser.boolean]],
                               {"-x", optarg})).
              to_output "opts = { x = false }\n"
          end
      - it defaults to a truthy value:
          expect (parseargs ([["x", parser.optional, parser.boolean]],
                             {"-x", "-b"})).
            to_output "opts = { b = true, x = true }\n"
    - context with a file handler function:
      - it records an existing file:
          expect (parseargs ([["x", parser.optional, parser.file]],
                             {"-x", "/dev/null"})).
            to_output "opts = { x = /dev/null }\n"
      - it diagnoses a missing file: |
          expect (parseargs ([["x", parser.optional, parser.file]],
                             {"-x", "/this/file/does/not/exist"})).
            to_contain_error "error: /this/file/does/not/exist: "
    - context with a custom handler function:
      - it calls the handler:
          expect (parseargs ([["x", parser.optional, function (p,o,a)
                                                       return "custom"
                                                     end
                             ]], {"-x", "ignored"})).
            to_output "opts = { x = custom }\n"
      - it does not consume a following option:
          expect (parseargs ([["x", parser.optional, function (p,o,a)
                                                       return a or "default"
                                                     end
                             ]], {"-x", "-b"})).
            to_output "opts = { b = true, x = default }\n"
  - context when splitting combined short options:
    - it separates non-argument options:
        expect (parseargs ([["x"]], {"-xb"})).
          to_output "opts = { b = true, x = true }\n"
        expect (parseargs ([["x"]], {"-vxb"})).
          to_output "opts = { b = true, verbose = true, x = true }\n"
    - it stops separating at a required argument option:
        expect (parseargs ([[{"x", "this"}, parser.required]], {"-bxbit"})).
          to_output "opts = { b = true, this = bit }\n"
    - it stops separating at an optional argument option:
        expect (parseargs ([[{"x", "this"}, parser.optional]], {"-bxbit"})).
          to_output "opts = { b = true, this = bit }\n"