# Options and Arguments

When a command executes, the raw `string[] args` value can be separated into two different categories: options and arguments.

Options are named and must be specified on command-line by name. By default, options are optional, but can be made mandatory.

Arguments are positional and values are specified based by order.

```
mycommand.exe --verbose abc --path:logs/ xyz --message Hello
```

This sample breaks down in the following way:

String | Interpretation
-------|----------
`mycommand.exe` | the name of the command (handled by the operating system. In .NET, this value isn't part of `string[] args`.
`--verbose` | Option. Name = "verbose", value = null
`abc` | Argument (position 0)
`--path:logs/` | Option. Name = "path", value = "logs/"
`xyz` | Argument (position 1)
`--message Hello` | Option. Name = "message", value = "Hello"

## Options

Options have two defining characteristics. They are represented by the @McMaster.Extensions.CommandLineUtils.CommandOption type.

 * Names - options can be identified by multiple names, such as a long name (e.g. "message") or a short name, which is usually a single character.
   An option must have at least one name.
 * Type - options are one of four types
    * No value - options do not have a value. They are either considered "specified" or "absent". These are also sometimes called flags or switches.
    * Single value - an option which must have a single value specified.
    * Multiple values - an option can be specified multiple times with multiple values
    * Single or no value - a special case of "no value" options where an value may or may not be specified.
      They can be specified as `--name` (no value) or `--name:value` or `--name=value`.
      Unlike "single value", these cannot be specified as `--name value` because the space causes amgibuous usage.

Additional properties on @McMaster.Extensions.CommandLineUtils.OptionAttribute can be set to define how the option appears in help text.

### [Using Attributes](#tab/using-attributes)

These examples use @McMaster.Extensions.CommandLineUtils.OptionAttribute to define options.

```csharp
public class MyCommand
{
    [Option]
    public bool Verbose { get; set; }
    // Inferred type = NoValue
    // Inferred names = "-v", "--verbose"
    
    [Option]
    public string Color { get; set; }
    // Inferred type = SingleValue
    // Inferred names = "-c", "--color"
    
    [Option]
    public (bool hasValue, string value) LogLevel { get; set; }
    // Inferred type = SingleOrNoValue
    // Inferred names = "-l", "--log-level"    
    
    [Option]
    public int[] Names { get; set; }
    // Inferred type = MultipleValues
    // Inferred names = "-n", "--names"    
}
```

### [Using Builder API](#tab/using-builder-api)

```csharp
public class Program
{
    public static void Main(string[] args)
    {
        var app = new CommandLineApplication();
        
        var verbose = app.Option("-v|--verbose", "Show verbose output", CommandOptionType.NoValue);
        var color = app.Option("-c|--color <COLOR>", "A color", CommandOptionType.SingleValue);
        var logLevel = app.Option("-l|--log-level[:<LEVEL>]", "The log level", CommandOptionType.SingleOrNoValue);
        var names = app.Option("-n|--names <NAME>", "Names", CommandOptionType.MultipleValue);
    }
}
```