newMain

scala.annotation.newMain
See thenewMain companion object
final class newMain extends MainAnnotation[FromString, Any]

The annotation that designates a main function. Main functions are entry points for Scala programs. They can be called through a command line interface by using the scala command, followed by their name and, optionally, their parameters.

The parameters of a main function may have any type T, as long as there exists a given util.CommandLineParser.FromString[T] in the scope. It will be used for parsing the string given as input into the correct argument type. These types already have parsers defined:

  • String,
  • Boolean,
  • Byte, Short, Int, Long, Float, Double.

The parameters of a main function may be passed either by position, or by name. Passing an argument positionally means that you give the arguments in the same order as the function's signature. Passing an argument by name means that you give the argument right after giving its name. Considering the function @newMain def foo(i: Int, str: String), we may have arguments passed:

  • by position: scala foo 1 abc,
  • by name: scala foo -i 1 --str abc or scala foo --str abc -i 1.

A mixture of both is also possible: scala foo --str abc 1 is equivalent to all previous examples.

Note that main function overloading is not currently supported, i.e. you cannot define two main methods that have the same name in the same project.

Special arguments are used to display help regarding a main function: --help and -h. If used as argument, the program will display some useful information about the main function. This help directly uses the ScalaDoc comment associated with the function, more precisely its description and the description of the parameters documented with @param. Note that if a parameter is named help or h, or if one of the parameters has as alias one of those names, the help displaying will be disabled for that argument. For example, for @newMain def foo(help: Boolean), scala foo -h will display the help, but scala foo --help will fail, as it will expect a Boolean value after --help.

Parameters may be given annotations to add functionalities to the main function:

  • main.alias adds other names to a parameter. For example, if a parameter node has as aliases otherNode and n, it may be addressed using --node, --otherNode or -n.

Here is an example of a main function with annotated parameters: @newMain def foo(@newMain.alias("x") number: Int, @newMain.alias("explanation") s: String). The following commands are equivalent:

  • scala foo --number 1 -s abc
  • scala foo -x 1 -s abc
  • scala foo --number 1 --explanation abc
  • scala foo -x 1 --explanation abc

Boolean parameters are considered flags that do not require the "true" or "false" value to be passed. For example, @newMain def foo(i: Boolean) can be called as foo (where i=false) or foo -i (where i=true).

The special -- marker can be used to indicate that all following arguments are passed verbatim as positional parameters. For example, @newMain def foo(args: String*) can be called as scala foo a b -- -c -d which implies that args=Seq("a", "b", "-c", "-d").

Attributes

Companion:
object
Graph
Supertypes
class Object
trait Matchable
class Any

Members list

Concise view

Value members

Concrete methods

def argGetter[T](param: Parameter, arg: String, defaultArgument: Option[() => T])(using p: FromString[T]): () => T

The getter for the idxth argument of type T

The getter for the idxth argument of type T

Attributes

defaultArgument

Optional lambda to instantiate the default argument

idx

The index of the argument

Process the command arguments before parsing them.

Process the command arguments before parsing them.

Return Some of the sequence of arguments that will be parsed to be passed to the main method. This sequence needs to have the same length as the number of parameters of the main method (i.e. info.parameters.size). If there is a varags parameter, then the sequence must be at least of length info.parameters.size - 1.

Returns None if the arguments are invalid and parsing and run should be stopped.

Attributes

args

The command line arguments

info

The information about the command (name, documentation and info about parameters)

def run(execProgram: () => Any): Unit

Run program if all arguments are valid if all arguments are valid

Run program if all arguments are valid if all arguments are valid

Attributes

program

A function containing the call to the main method and instantiation of its arguments

def varargGetter[T](param: Parameter, args: Seq[String])(using p: FromString[T]): () => Seq[T]

The getter for a final varargs argument of type T*

The getter for a final varargs argument of type T*

Attributes