Add firrtl.options

This adds a new package, "firrtl.options", that provides a framework for
working with options inside and outside FIRRTL.

Small changes:
  - Make TerminateOnExit return the correct exit code
  - Deprecate mutable TerminateOnExit
  - Add immutable DoNotTermianteOnExit

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

1 files changed, 63 insertions, 0 deletions

diff --git a/src/main/scala/firrtl/options/Shell.scala b/src/main/scala/firrtl/options/Shell.scala
new file mode 100644
index 00000000..b9278f30
--- /dev/null
+++ b/src/main/scala/firrtl/options/Shell.scala
@@ -0,0 +1,63 @@
+// See LICENSE for license details.
+
+package firrtl.options
+
+import firrtl.AnnotationSeq
+
+import scopt.OptionParser
+
+import java.util.ServiceLoader
+
+/** Indicate an error in [[firrtl.options]]
+  * @param msg a message to print
+  */
+case class OptionsException(msg: String, cause: Throwable = null) extends Exception(msg, cause)
+
+/** A utility for working with command line options
+  * @param applicationName the application associated with these command line options
+  */
+class Shell(val applicationName: String) {
+
+  /** Command line argument parser (OptionParser) with modifications */
+  final val parser = new OptionParser[AnnotationSeq](applicationName) with DoNotTerminateOnExit with DuplicateHandling
+
+  /** Contains all discovered [[RegisteredLibrary]] */
+  lazy val registeredLibraries: Seq[RegisteredLibrary] = {
+    val libraries = scala.collection.mutable.ArrayBuffer[RegisteredLibrary]()
+    val iter = ServiceLoader.load(classOf[RegisteredLibrary]).iterator()
+    while (iter.hasNext) {
+      val lib = iter.next()
+      libraries += lib
+      parser.note(lib.name)
+      lib.addOptions(parser)
+    }
+    libraries
+  }
+
+  /** Contains all discovered [[RegisteredTransform]] */
+  lazy val registeredTransforms: Seq[RegisteredTransform] = {
+    val transforms = scala.collection.mutable.ArrayBuffer[RegisteredTransform]()
+    val iter = ServiceLoader.load(classOf[RegisteredTransform]).iterator()
+    parser.note("FIRRTL Transform Options")
+    while (iter.hasNext) {
+      val tx = iter.next()
+      transforms += tx
+      tx.addOptions(parser)
+    }
+    transforms
+  }
+
+  /** The [[AnnotationSeq]] generated from command line arguments
+    *
+    * This requires lazy evaluation as subclasses will mixin new command
+    * line options via methods of [[Shell.parser]]
+    */
+  def parse(args: Array[String], initAnnos: AnnotationSeq = Seq.empty): AnnotationSeq = {
+    registeredTransforms
+    registeredLibraries
+    parser
+      .parse(args, initAnnos)
+      .getOrElse(throw new OptionsException("Failed to parse command line options", new IllegalArgumentException))
+  }
+
+}