A composable application trait that includes flag parsing as well as basic application lifecycle (pre- and post- main).
A single command-line flag, instantiated by a com.twitter.app.Flags instance.
A single command-line flag, instantiated by a com.twitter.app.Flags
instance. Its current value can be extracted via apply()
.
Exception thrown upon flag-parsing failure.
Exception thrown upon flag-parsing failure. Should typically lead to process death, since continued execution would run the risk of unexpected behavior on account of incorrectly-interpreted or malformed flag values.
A string name of the flag for which parsing failed.
The underlying java.lang.Throwable that caused this exception.
A type class providing evidence for parsing type T
as a flag value.
A type class providing evidence for parsing type T
as a flag value.
Any class that is to be provided as a flaggable value must have an
accompanying implicit Flaggable
(contained within a companion object of the
class in question) for converting a string to an object of that type. For
instance, to make a hypothetical type called Foo
flaggable:
class Foo { ... } object Foo { implicit val flagOfFoo = new Flaggable[Foo] { def parse(v: String): Foo = { ... } } }
For simple implicit definitions based on existing String => T
functions,
use the Flaggable.mandatory
function:
object Foo { def parse(v: String: Foo = { ... } implicit val ofFoo = Flaggable.mandatory(Foo.parse(_)) }
[1] http://en.wikipedia.org/wiki/Type_class
A simple flags implementation.
A simple flags implementation. We support only two formats:
for flags with optional values (e.g. booleans): -flag, -flag=value for flags with required values: -flag[= ]value
That's it. These can be parsed without ambiguity.
There is no support for mandatory arguments: That is not what flags are for.
Flags.apply
adds a new flag to the flag set, so it is idiomatic
to assign instances of Flags
to a singular flag
val:
val flag = new Flags("myapp") val i = flag("i", 123, "iteration count")
Global flags, detached from a particular Flags
instance but
accessible to all, are defined by com.twitter.app.GlobalFlag.
Subclasses of GlobalFlag (that are defined in libraries) are "global" in the sense that they are accessible by any application that depends on that library.
Subclasses of GlobalFlag (that are defined in libraries) are "global" in the
sense that they are accessible by any application that depends on that library.
Regardless of where in a library a GlobalFlag is defined, a value for it can
be passed as a command-line flag by any binary that includes the library.
The set of defined GlobalFlags can be enumerated (via GlobalFlag.getAll)
by
the application.
object MyFlag extends GlobalFlag("my", "default value", "this is my global flag")
All such global flag declarations in a given classpath are visible to and used by com.twitter.app.App.
A flag's name (as set on the command line) is its fully-qualified classname. For example, the flag
package com.twitter.server object port extends GlobalFlag(8080, "the TCP port to which we bind")
is settable by the command-line flag -com.twitter.server.port
.
Global flags may also be set by Java system properties with keys named in the same way. However, values supplied by flags override those supplied by system properties.
Default Flaggable
implementations.
Load classes in the manner of java.util.ServiceLoader.
Load classes in the manner of java.util.ServiceLoader. It is more resilient to varying Java packaging configurations than ServiceLoader.
A composable application trait that includes flag parsing as well as basic application lifecycle (pre- and post- main). Flag parsing is done via com.twitter.app.Flags, an instance of which is defined in the member
flag
. Applications should be constructed with modularity in mind, and common functionality should be extracted into mixins.Flags should only be constructed in the constructor, and should only be read in the premain or later, after they have been parsed.
Note that a missing
main
is OK: mixins may provide behavior that does not require defining a custommain
method.