Enable default value and help text when parsing multiple values

[JordanMartinez]

To parse a single value that has a default value, I'll usually use a regular option rather than an argument: strOption (long "arg-name" <> value "default" <> help "help text" <> ...)

To parse multiple values, I need to use an argument: some $ argument str $ metavar "FILES..."

However, the multi-value parser removes the help text option and does not allow me to specify a default value.

How can I re-add that support?

Full context: I'm migrating from Yargs to this library since the former has a high severity warning when NPM audits its dependencies. (JordanMartinez/purescript-jordans-reference#315). Yargs allows one to specify an array of values (with a default value) that I used in my ToC generator program. This capability isn't strictly necessary, but I'd prefer to not have to drop support for it.

[safareli]

In general when there is many and some and you want to use some but have default value you can use many instead, map over it and if you have Nil replace it with default value.

-- `one` must be parsed or will fail
some one = lift2 Cons one (many one)

so you can do for example:

many <#> case  _  of
  Nil -> Nothing
  Cons a as -> Just $ NES.cons' a as

Also you don;t have to use argument necessarily if you want to get many values, you can wrap your old strOption in many/some. for example: https://github.com/f-o-a-m/purescript-optparse/blob/master/test/Examples/Cabal.purs#L114

and you would have to pass many values like this

command --arg-name val1 --arg-name val2

if you don't want to type --arg-name multiple times, you can use option and eitherReader to create parse which splits input on ,:

strings = eitherReader \s -> 
  note "got empy string in input" 
  $ traverse 
  $ map NonEmptyString.fromString
  $ split (Pattern ",") s 

x = option strings (long "arg-name" <> value "default" <> help "help text" <> ...)

then you could do --arg-name asd,asda,asd or even use some with it

[JordanMartinez]

Gotcha. Thanks for the clear explanation and overview of the approaches I could take.

I like the last solution you provided best because it seems to allow one to still use value <> showDefaultWith, so that the default value appears in the help text.
Would you mind if I submitted a PR that adds the eitherReader implementation you provided as a convenience function?

Something like

-- | Allows one to parse multiple values in one option
-- | via a separator (like a comma or a colon). For example:
-- | `--arg-name first,second,third`
-- | `--arg-name first:second:third`
-- |
-- | To produce the above examples, we would write
-- | strings = multi (Pattern ",") NonEmptyString.fromString "got empty string on input"
multi :: forall a. Pattern -> (String -> Either String a) String -> ReadM (Array a)
multi splitter mapper errorMessage = eitherReader (\s ->
    note errorMessage
    $ traverse 
    $ map mapper
    $ split splitterPattern s 

[JordanMartinez]

This is the code I ultimately used:

multiString :: ReadM (Array String)
multiString = eitherReader \s ->
  let strArray = filter String.null $ split (Pattern ",") s
  in
    if Array.null strArray
      then Left "got empty string as input"
      else Right strArray

parseExcludedTopLevelDirs :: Parser (Array String)
parseExcludedTopLevelDirs =
    option multiString
      ( long "exclude-top-level-dirs"
     <> short 't'
     <> metavar "DIR1,DIR2,...,DIR3"
     <> help "A comma-separated list of top-level directories \
             \(case-sensitive) to exclude."
     <> value [ ".git", ".github", ".procedures", ".travis", "output"]
     <> showDefaultWith (\array -> intercalate "," array)
      )

However, this doesn't entirely fix the issue. The code compiles fine, and running the program without passing in the required args node dist/ghtoc.js will print the missing args version of the help text:

Missing: (-r|--root-dir ROOT_DIR) (-o|--output-file OUTPUT_FILE)

Usage: readert-ghtoc.js (-r|--root-dir ROOT_DIR) (-o|--output-file OUTPUT_FILE)
                        [-t|--exclude-top-level-dirs DIR1,DIR2,...,DIR3]
                        [-d|--exclude-regular-dirs DIR1,DIR2,...,DIR3]
                        [-f|--include-files-with-extensions .EXT1,.EXT2,...,.EXT3]
                        [-u|--github-username USERNAME]
                        [-p|--github-project PROJECT_NAME]
                        [--github-reference TAG_OR_BRANCH]
                        [--log-level LOG_LEVEL] [--skip-url-verification]
  Produces a Table of Contents file in Markdown whose links refer to a GitHub
  repo's corresponding file.

When I pass in the --help flag (node dist/ghtoc.js --help), the full help text isn't displayed. Instead, the program just hangs until I terminate it.

[safareli]

Can you comment out all/most of options/commands and see if --help works, when not many options/commands are used? I think I might have had similar issue before but I think I fixed it. If you comment out things and then get help, it means during porting from haskell I missed some case which relies on haskell being lazy and in PS too much work is done and for some inputs it takes toooo long. I think the issue might be in PrettyPrint.Leijen#renderFits#best. If you can provide me with a gist or something might be able to look into it over the weekend in more details (if not now).

regarding adding multi or multiParser it's hard to make it work well for all use-cases, also lib has many and some and other already built in approach for getting multiple values. I would rather not add that and let users Implement it as they see fit (for example in first example we had no error on null, on the other, we do. Someone might want List or NonEmptyArray etc) tho it's a nice thing to just document and adding ti to README would be great.

[JordanMartinez]

regarding adding multi or multiParser it's hard to make it work well for all use-cases, also lib has many and some and other already built in approach for getting multiple values. I would rather not add that and let users Implement it as they see fit (for example in first example we had no error on null, on the other, we do. Someone might want List or NonEmptyArray etc) tho it's a nice thing to just document and adding ti to README would be great.

Good point. That does sound like a better place to put it.

Can you comment out all/most of options/commands and see if --help works, when not many options/commands are used? I think I might have had similar issue before but I think I fixed it. If you comment out things and then get help, it means during porting from haskell I missed some case which relies on haskell being lazy and in PS too much work is done and for some inputs it takes toooo long. I think the issue might be in PrettyPrint.Leijen#renderFits#best. If you can provide me with a gist or something might be able to look into it over the weekend in more details (if not now).

So, looks like the help text does get printed either way, but it gets slower with the larger number of arguments. I'm also using all the modifiers I can in each argument, so that might be why.
Here's the gist: https://gist.github.com/JordanMartinez/7ff1af377dfcddf885aad8cd17fb16c3

I tested it without using the multiString ReadM above. I haven't tested it with that on yet.

[safareli]

I have fixed the "help taking too long" issue #10.

[JordanMartinez]

Nice! Thanks for fixing that!

[safareli]

#10 and #8 are merged so closing