New main annotation design

[nicolasstucki]

We are in the process of improving the @main annotation using the main annotation generalization scala.annotation.MainAnnotation. The current prototype can be found in #14841 as scala.annotation.newMain/@newMain.

The aim of this main annotation is to be simple to use out of the box. Easy for newcomers and have some degree of flexibility for more advanced use cases. Libraries/applications that want advanced customization of main annotations can implement their own MainAnnotation.

Note that we will merge #14841 even if it is not the final design. This will allow you to test it and provide concrete feedback (bugs or design suggestions).

This discussion section will split different pieces of the design into separate sub-discussions.

[nicolasstucki]

Named arguments

The main annotation supports named arguments. The question is which is the format of a name.

Option 1 (current design)

The current design provides long and short names based

• Short name: if matches the following regex -[a-zA-Z]
• Long name: if matches the following regex --[a-zA-Z][a-zA-Z0-9]+
• Illegal name: if matches the following regex --[a-zA-Z]|-[a-zA-Z][a-zA-Z0-9]+

Parameters with a name with a single character expect a short name argument and parameters with more than one character expect a long name argument.

Note that we want to interpret names starting with - or -- as names but we want -3 to be parsed as a positional argument.

Option 2

Do not have named arguments. Consider this an advanced use case that another implementation can add.

[julienrf]

Could you please expand a little bit more on how it works? If I have the following:

@newMain def run(foo: String, bar: Int): Unit = ()

Are the following invocations valid?

1. xxx 42 (positional arguments)
2. --foo xxx 42 (foo is passed as a named argument)
3. --bar 42 xxx (bar is passed as a named argument, and foo is passed as a positional argument, but note that the order of the arguments does not match the order of the parameters)

In my opinion, inferring the name of the command-line argument from the parameter name is too limited. Also, it is not clear how to deal with mixing positional and named arguments at the same time. Instead, I would stick to positional parameters (option 2 “do not have named arguments”).

More generally, what you are trying to achieve with @newMain is to derive a command-line API from a Scala method signature. I don’t think Scala method signatures are an appropriate “data structure” to model command-line APIs (in general), because there is no convenient way to indicate whether an argument should be named or positional, and there is no convenient way to describe a lot of other details of the command-line API (such as parameter aliases, or the fact that some parameters are exclusive, also some parameters are just flags with no value, etc.). So, I would stick to the simple model of deriving positional command-line arguments from the annotated method signature.

[nicolasstucki]

The current design allows all 3 options stated above.

The rules are as follows, for each argument starting from the first

• If the argument is named, take that value
• Otherwise take the next available positional argument

[nicolasstucki]

In my opinion, inferring the name of the command-line argument from the parameter name is too limited

Indeed, it is too limited in the general case. The design try to remain as simple as possible for the users. It should be s simple out of the box experience that does not require lots of investment for the user of the main annotation.

Other more advanced implementations of MainAnnotation can provide fully customizable command-line arguments such as exclusive arguments.

[nicolasstucki]

Flags are available. See #14977 (comment).

[julienrf]

I think it would be extremely helpful to explain better the problem you want to solve with @newMain (I am not talking about MainAnnotation), and to compare your solution with alternative solutions (such as user-land libraries like decline).

[nicolasstucki]

Aliases

Option 1 (current design)

Have an @alias("name") annotation in the newMain module.

@newMain def f(@alias("i") input: String): Unit = ...

This main method can be called as with arguments arg, --input arg or -i arg.

The named arguments rules apply to aliases.

Option 2

Do not support aliases.

They might not be needed as much as we would think. Another main annotation implementation could exist with advanced support for parameter aliasing.

Aliases introduce some overhead at runtime and complexity in the implementation. These could be avoided.

[julienrf]

As explained above, I would vote for not supporting aliases.

[nicolasstucki]

Named argument escape

The idea is to have a way to pass -i or --input as the argument itself.

@newMain def f(inputs: String*): Unit = ...

For example in f -- -i would be called with inputs = Seq("-i").

Current design

We add the -- to state that all following arguments must be handled positionally even if they match a name.

[nicolasstucki]

Argument parsers

Parsers are used to convert the string argument into a value of some type.

Current design

We use scala.util.CommandLineParser.FromString from the current @main implementation.

Currently, this provides parsers for String, Boolean, Byte, Short, Int, Long, Float, and Double.

Note: Seems we missed FromString[Char]. We could add it.

[nicolasstucki]

Flags

Flags are optional named parameters with no argument values.

For example prog -f to enable f.
This is, if the main is called with -f the value of f will be true. Otherwise, if -f is not an argument, the value of f will be false.

Technically, the -f inserts a "true" for its argument and the lack of -f inserts a "false". This value is then parsed by the boolean parser.

Option 1

Have a @flag annotation in the newMain module that can annotate boolean parameters.

@newMain def f(@flag f: Boolean): Unit = ...

With this design, we can still have an unannotated boolean parameter that can receive "true" and "false".

Option 2 (current design)

Make all boolean parameters flag parameters.

@newMain def f(f: Boolean): Unit = ...

With this design, we cannot have boolean parameters that can receive "true" and "false". We could have a proxy type for boolean values that would expect those values.

Option 3

Do not support flags. Consider this an advanced use case that another implementation can add.

[nicolasstucki]

Default help

The idea is to generate a default help message if the main is called with --help or -h.

Option 1 (current design)

Print default help message if --help or -h flags are set.
Help can be overridden by adding a parameter named help and h (possibly using an alias).

Option 2

Print default help message if --help or -h flags are set.
Add an argument to the main annotation to enable or disable the default help message.
@main(defaultHelp = false)

Option 3

Do not provide help.

[nicolasstucki]

Compound flags

We could extend the design of #14977 (comment) to support compound flags -xyz that desugar into -x -y -z.

[nicolasstucki]

This would only work for flags with short names