newMain

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").