bmjames / scala-optparse-applicative

Scala port of Paolo Capriotti's optparse-applicative library. This repository is no longer maintained; newer versions exist in this fork: https://github.com/xuwei-k/optparse-applicative

scala-optparse-applicative

A port of the optparse-applicative library to the Scala programming language.

Most functionality has been ported, except completion.

This library depends on Scalaz for functional data structures, type classes and combinators.

How to get it

Version 0.7 of scala-optparse-applicative is available for Scala 2.10, 2.11 and 2.12.

resolvers += "bmjames Bintray Repo" at "https://dl.bintray.com/bmjames/maven"

libraryDependencies += "net.bmjames" %% "scala-optparse-applicative" % "0.7"

License

This library is distributed under a BSD 3-Clause license (see LICENSE).

Simple example

This example follows the one from the [optparse-applicative] 1 docs.

case class Sample(hello: String, quiet: Boolean)

object SampleMain {

  val sample: Parser[Sample] =
    ^(
      strOption(long("hello"), metavar("TARGET"), help("Target for the greeting")),
      switch(long("quiet"), help("Whether to be quiet"))
    )(Sample.apply)

  def greet(s: Sample): Unit = s match {
    case Sample(h, false) => println("Hello, " ++ h)
    case _ =>
  }

  def main(args: Array[String]) {
    val opts = info(sample <*> helper,
      progDesc("Print a greeting for TARGET"),
      header("hello - a test for scala-optparse-applicative"))
    greet(execParser(args, "SampleMain", opts))
  }

}

When run with the --help option, it prints:

hello - a test for scala-optparse-applicative

Usage: SampleMain --hello TARGET [--quiet]
  Print a greeting for TARGET

Available options:
  -h,--help                Show this help text
  --hello TARGET           Target for the greeting
  --quiet                  Whether to be quiet

Advanced examples

Further examples can be found in src/test/examples.

To Do

• More tests

scala-optparse-applicative's Issues

Possible to parse several values for an option

Wondering how possible it would be to have the parser behave like:

$ ./foo --file 1 2 3
$ ./foo --user 4 5 6

I believe if we define a ReadM instance, by the time it gets around to that bit it's already tokenized the arguments so I only get at the 1 or something, as opposed to some sort of List(1,2,3).

Ideas for making a Cats version?

I have a few projects which are moving to Cats. It'd be nice if we could have a version of this that worked for Cats without slurping in Scalaz.

I can think of a couple options:

1. Duplicate the project, swap out Scalaz for Cats.
2. Write a core with 0 dependencies (reimplementing the needed typeclasses), then provide contrib modules which brought in the needed scalaz or cats version.
3. Use some crazy thing like @tpolecat's yax to ifdef things.

Based on the commit history, I think 1 is probably the best option since the project seems to be changing relatively slowly. Would you agree? Do you have better ideas?

cc/ @bmjames

Wish: remove dependence on Kiama

My current company for very social (not rigorously technical/legal) reasons is uncomfortable with the LGPL license pulled in by Kiama.

It doesn't seem like Kiama is used too much by this project, and something hand-rolled might be possible -- maybe at the loss of some performance or generality -- but this is just a command-line parsing tool, so hopefully it's not that big a deal.

If someone else (me) put in the work, would you be open to getting off of Kiama?

Add more examples/doc

It's quite hard to get on track without knowing how exactly to use the library in non-trivial cases, for example how to parse the same option multiple times (the equivalent of many and some in optparse-applicative), or how to use subparsers/commands.

Parser[T] is invariant of T

Is that a necessity? It's necessitating type declarations when using subcommands, e.g.:

sealed trait Cmd
case class DeployCmd(...)  extends Cmd
case class RestartCmd(...) extends Cmd

val deployCmd: Parser[Cmd]  = subparser(command("deploy", ...))
val restartCmd: Parser[Cmd] = subparser(command("restart", ...))

val subcmd = deployCmd <+> restartCmd  

The above will fail to compile if either one of deployCmd or restartCmd aren't declared as Parser[Cmd].

But then again I've been told that variance causes other, more serious, type inference issues, so if that's the case I'm willing to live with the explicit type annotations.

Add ReadM (and related) for other types

e.g. Short, Long, BigInt

Should these be placed in the same place as the existing ones or in a separate place?

Add example on how to use `helper` when validating arguments

Consider the following setting:

  type V[A] = ValidationNel[String, A]
  type ParserV[A] = Parser[V[A]]

implicit val ParserVInstance: Applicative[ParserV] =
       Applicative[Parser] compose Applicative[V]

 val optsParser: ParserV[Options] = ???

In this case it is not possible to compose the parsers with helper:

 execParser(args, "xxx", info(optsParser <*> helper))

It'd be nice to have an example on how helper can be used in the setting of parsers with validation.

Very slow to render help message after a library upgrade (0.5 -> 0.6)

91.09s user 1.72s system 104% cpu 1:29.04 total (v 0.6)
vs
2.15s user 0.13s system 162% cpu 1.403 total (v 0.5, most of the time went to logback init)

It seems to be spending a very long time in findBest now, e.g. stack trace:

"main" #1 prio=5 os_prio=31 tid=0x00007f9394001000 nid=0x1b03 runnable [0x000070000a5a4000]
   java.lang.Thread.State: RUNNABLE
	at net.bmjames.opts.types.RenderDoc$.$anonfun$findBestCore$2(Doc.scala:155)
	at net.bmjames.opts.types.RenderDoc$$$Lambda$311/412925308.apply(Unknown Source)
	at scalaz.Free$.$anonfun$suspend$2(Free.scala:27)
	at scalaz.Free$$$Lambda$52/198099809.apply(Unknown Source)
	at scalaz.Free.$anonfun$resume$2(Free.scala:111)
	at scalaz.Free$$Lambda$315/2073640037.apply(Unknown Source)
	at scalaz.std.FunctionInstances$$anon$1.$anonfun$map$1(Function.scala:77)
	at scalaz.std.FunctionInstances$$anon$1$$Lambda$53/807752428.apply(Unknown Source)
	at scalaz.Free.$anonfun$run$1(Free.scala:263)
	at scalaz.Free$$Lambda$48/1658699134.apply(Unknown Source)
	at scalaz.Free.go2$1(Free.scala:154)
	at scalaz.Free.go(Free.scala:157)
	at scalaz.Free.run(Free.scala:263)
	at net.bmjames.opts.types.RenderDoc$.findBest(Doc.scala:150)

Seems related to kiama removal.
Reverted project back to 0.5 for now but would appreciate if there were a better answer to this.

Just to give you and idea - it's not a huge CLI but larger than a "hello world", 2 commands, 14 options in the largest command and a handful of global options.

Thanks!