# Flag options

## Name

With the name you can specify the name of the flag. The name is also used as
property name for the options object.

## Type

With the `type` you specify the type of the argument. The type can be one of the
following types or any custom types.

- `boolean`
- `string`
- `number`
- `integer`

The `type` option is optional. If no type is specified the flag is a boolean
option without a value. If `type` is set to `boolean` the flag can have a
boolean value.

## Optional value

By default the value is required for all options with an explicitly defined
type. You can make the value optional by setting `optionalValue` to `true`.

## Variadic value

You can make an argument variadic with the `variadic` option. A variadic value
can occur multiple times and is collected in an array.

## List value

If `list` is set to `true`, the argument will be split by `,` and the values
will be stored in an array. You can override the separator with the `separator`
option.

## Aliases

You can specify some aliases for the flag with the `aliases` option.

## Standalone

If `standalone` is set to `true`, this option cannot be combined with other
options.

If the `standalone` option is set to `true`, the option cannot be combined with
other options. If additionally an option action handler is defined, only the
option action handler is executed and not the command action handler.

## Default

The `default` option specifies the default value for the flag when the flag is
not specified on commandline.

## Required

If `required` is set to `true` an error is thrown if the flag is not set on
commandline.

## Depends

You can specify flags which must be provided if a specific flag is set. If
`depends` is set to `["foo", "bar"]`, an error is thrown if one of this flags
are not provided on commandline.

## Conflicts

This is the opposite of the `depends` option. You can specify flags which can
not be provided if a specific flag is set. If `conflicts` is set to
`["foo", "bar"]`, an error is thrown if one of this flags is provided on
commandline.

Conflicts are only checked against explicitly provided flags (as command line
argument or environment variable). A conflicting flag that only has its default
value does not trigger an error.

## Equals sign

If `equalsSign` is set to `true` the option must be called with an equals sign
`--foo=bar`.

This only has an effect for options with an **optional** value. For options with
a **required** value, `equalsSign` has no effect, the option can always be
called with or without an equals sign.

## Collect values

If `collect` is enabled, a flag can be specified multiple times on commandline.
All values will be collected into an array.

```typescript
import { parseFlags } from "@cliffy/flags";

const { flags } = parseFlags(Deno.args, {
  flags: [{
    name: "color",
    type: "string",
    collect: true,
  }],
});

console.log(flags);
```

```console
$ deno run examples/flags/collect.ts --color red --color blue
{ color: ["red", "blue"] }
```

## Map values

You may specify a function to do custom processing of flag values. The callback
function receives one parameter, the user specified value which is already
parsed into the specified type. The return value of this method will be used as
flag value.

If [collect](#collect-values) is enabled the function receives as second
parameter the previous value. This allows you to coerce the option value to the
desired type, or accumulate values, or do entirely custom processing.

```typescript
import { parseFlags, ValidationError } from "@cliffy/flags";

const { flags } = parseFlags(Deno.args, {
  flags: [{
    name: "color",
    type: "string",
    collect: true,
    value(value: string, previous: Array<string>): Array<string> | undefined {
      if (["foo", "bar", "baz"].includes(value)) {
        return [...previous, value];
      }
      // if no value is returned, a default validation error will be thrown.
      // You can use the `ValidationError` to provide a custom error message.
      throw new ValidationError(
        `Option "--value" must be one of "foo", "bar" or "baz", but got "${value}".`,
      );
    },
  }],
});

console.log(flags);
```

```console
$ deno run examples/flags/value.ts --value fooo
error: Uncaught Error: Option "--value" must be one of "foo", "bar" or "baz", but got "fooo".
$ deno run examples/flags/value.ts --value foo
{ value: ["foo"] }
```

## Args

The `args` array can be used if the flag has multiple values. Following options
can be set for each argument:

- [type](#type)
- optional (see [optionalValue](#optional-value))
- [variadic](#variadic-value)
- [list](#list-value)

## Ignore defaults

The `ignoreDefaults` option can be used to ignore the default values from
specific options. The `ignoreDefaults` option is an object. The keys have to
match the option name but the value can be anything (values are ignored).