package app
- Alphabetic
- Public
- All
Type Members
-
trait
App
extends Closable with CloseAwaitably
A composable application trait that includes flag parsing as well as basic application lifecycle (pre- and post- main).
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.
object MyApp extends App { val n = flag("n", 100, "Number of items to process") def main() { for (i <- 0 until n()) process(i) } }
Note that a missing
main
is OK: mixins may provide behavior that does not require defining a custommain
method. -
class
Flag
[T] extends AnyRef
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.
The current value can be extracted via apply(), get, and getWithDefault. Local-scoped modifications of their values, which can be useful for tests, can be done by calls to let and letClear.
Using a
String
-typed Flag,myFlag
, which is unset and has a default value of "DEFAULT" as an example:myFlag.isDefined // => false myFlag.get // => None myFlag.getWithDefault // => Some("DEFAULT") myFlag() // => "DEFAULT" myFlag.let("a value") { myFlag.isDefined // => true myFlag.get // => Some("a value") myFlag.getWithDefault // => Some("a value") myFlag() // => "a value" myFlag.letClear { myFlag.isDefined // => false myFlag.get // => None myFlag.getWithDefault // => Some("DEFAULT") myFlag() // => "DEFAULT" } }
- See also
com.twitter.app.Flags for information on how flags can be set by the command line.
-
case class
FlagParseException
(message: String, cause: Throwable = null) extends Exception with Product with Serializable
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.
- message
A string name of the flag for which parsing failed.
- cause
The underlying java.lang.Throwable that caused this exception.
- class FlagUndefinedException extends Exception
- case class FlagUsageError (usage: String) extends Exception with Product with Serializable
- class FlagValueRequiredException extends Exception
-
abstract
class
Flaggable
[T] extends AnyRef
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 calledFoo
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 theFlaggable.mandatory
function:object Foo { def parse(v: String: Foo = { ... } implicit val ofFoo = Flaggable.mandatory(Foo.parse(_)) }
[1] http://en.wikipedia.org/wiki/Type_class
-
class
Flags
extends AnyRef
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 ofFlags
to a singularflag
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. -
abstract
class
GlobalFlag
[T] extends Flag[T]
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.A GlobalFlag must be declared as an
object
(see below for Java):import com.twitter.app.GlobalFlag object myFlag extends GlobalFlag[String]("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 import com.twitter.app.GlobalFlag object port extends GlobalFlag[Int](8080, "the TCP port to which we bind")
is settable by the command-line flag
-com.twitter.server.port=8080
.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.
- Annotations
- @GlobalFlagVisible()
- class GlobalFlagVisible extends Annotation with Annotation with ClassfileAnnotation
- abstract class JavaGlobalFlag [T] extends GlobalFlag[T]
Value Members
- object App
- object Flag
-
object
Flaggable
Default
Flaggable
implementations. - object Flags
- object GlobalFlag
-
object
LoadService
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.