Difference betweeen WithArgument and WithOption

[bstordrup]

I feel that the difference between WithArgument and WithOption is a bit unclear as I cannot completely see the difference between them.

Both take a generic type TParam which indicates that they both support a value being added after, i.e. leading to the name way to add them on command line.

So this

   .AddCommand()
      .WithArgument<int>("--loops", "Number of loops to perform")
      .WithOption<int>("--delay", "Delay in milliseconds")

would end up to be specified in command line as

    MyCommand --loops 25 --delay 123

Very little difference ;-)

But if the purpose of WithOption is to make a switch like parameter, then there would IMO be no need for a TParam generic type, because it would automatically resolve to a bool and result in something being turned on (or off).

Like this

   .AddCommand()
      .WithArgument<int>("--loops", "Number of loops to perform")
      .WithOption("--simulate-hard-work", "Inserts delays in the loop to simulate hard  work")

would end up on command line as

    MyCommand --loops 25 --simulate-hard-work

and result in a slower operation than

    MyCommand --loops 25

[peteraritchie]

I can see your confusion.

The terms stem from System.CommandLine where an "argument" is value accepted from the command line and an "option" is special argument prefixed the - or -- and an optional argument or arguments. An option is really a fixed name argument and an optional variable/value argument. ConsoleApplicationBuilder doesn't really reveal that an option is a name plus an argument because it's simpler to configure them with a type and the fixed name.

System.CommandLine re-uses these concepts and terms from UNIX/Linux.

What may be more confusing is that the argument name isn't used on the command line (i.e. it's not a fixed name). Your example:

   .AddCommand()
      .WithArgument<int>("--loops", "Number of loops to perform")
      .WithOption<int>("--delay", "Delay in milliseconds")

Would actually be called like this:

MyCommand 25 --delay 123

The "--loops" is used only in the generated help text and you wouldn't include the "--" the name. You'd normally do something like this (following System.CommandLine conventions):

   .AddCommand()
      .WithArgument<int>("loops", "Number of loops to perform")
      .WithOption<int>("--delay", "Delay in milliseconds")

"--loops" isn't used on the command line at all. Which would produce the following help output (if you passed only -h on the command line):

Description:
  Example command

Usage:
  MyCommand <loops> [options]

Arguments:
  <loops>  Number of loops to perform.

Options:
  --delay <delay>  Delay in milliseconds
  --version        Show version information
  -?, -h, --help   Show help and usage information

[bstordrup]

Thank you for clarifying.

The fact that the Argument name is not used on the command line, does that make the arguments positional, i.e. they are read in that sequence?

So

   .AddCommand()
      .WithArgument<int>("arg1", "description")
      .WithArgument<string>("arg2", "description2")

would be called as

    MyCommand 12 Test