Description
@oznetmaster commented on Thu Mar 19 2015
In the help display for the console options, every option is prefaced by --. Also, the all show an = as the separator for option and value.
However, Options.cs indicates in its internal documentation:
// Options are extracted either from the current option by looking for
// the option name followed by an '=' or ':', or is taken from the
// following option IFF:
// - The current option does not contain a '=' or a ':'
// - The current option requires a value (i.e. not a Option type of ':')
//
// The `name' used in the option format string does NOT include any leading
// option indicator, such as '-', '--', or '/'. All three of these are
// permitted/required on any named option.
//
// Option bundling is permitted so long as:
// - '-' is used to start the option group
// - all of the bundled options are a single character
// - at most one of the bundled options accepts a value, and the value
// provided starts from the next character to the end of the string.
//
// This allows specifying '-a -b -c' as '-abc', and specifying '-D name=value'
// as '-Dname=value'.
//
// Option processing is disabled by specifying "--". All options after "--"
// are returned by OptionSet.Parse() unchanged and unprocessed.
This indicates that either = or : can be used to separate options from their values, and that each option should start with a single -, not --. In fact, it appears that a -- will actually inhibit further option processing.
This has left me very confused. I have always used a single - in front of the option anme, and always used a : to separate options from their values.
Is this a documentation issue (both the help text and the online documentation), or is it a functional/implementation issue?
@CharliePoole commented on Thu Mar 19 2015
Yes, = or : are both available. They may be used interchangeably on the command-line, although they have different meanings when used in the option definition.
Option bundling is a feature that comes to us from Linux, where the distinction between - and -- is quite important. It's a bit confusing to Windows users, so we haven't said much about it in the help.
In fact, we only have two single-character options, -v and -h. Neither of them take an argument. You can type nunit-console -vh or nunit-console -hv and the help is displayed. If you use --vh, that's invalid. You can also use -help and --help (or /help on Windows).
All of this is the fallout of the fact that we are using a general-purpose class for our command-line options. Mono.Options is widely used in open source mono and .NET applications and it has a lot more capability than we use at the moment.
If you'd like to propose some changes in how we explain (or don't explain) this to the users, please assign this issue to yourself and write up what you think we should do here.
@oznetmaster commented on Thu Mar 19 2015
Something is very confused here. When I use single hyphen options (for EVERY option) they work perfectly. When I use double hyphen, they do not work! Which seems to agree with the documentation in the options.cs help file.
@CharliePoole commented on Thu Mar 19 2015
Yes, single hyphen should work for every option. Double-hyphen should work as well. What doesn't work?
@oznetmaster commented on Thu Mar 19 2015
Apparently the issue is that I left a space between the – and the option name (accidently), and that has a whole different meaning :(
Also, I discovered that / can also be used to specify the option.
I will think on how to document this. Perhaps it should only be in the online documentation, and not the help text.
@rprouse commented on Thu Mar 19 2015
@oznetmaster, can we close this now? It is fairly common for other programs that I know of to accept variants of - -- and / for the command lines. Is there still an issue?
@oznetmaster commented on Thu Mar 19 2015
This is a documentation issue. That is what is being discussed now. Neither the option prefix, nor the option/value separator, is documented correctly. And I use many programs in which no variants are accepted for either item, so documentation does seem in order here.
@rprouse commented on Thu Mar 19 2015
OK, I've labelled the issue accordingly.