# Parse options

## Flags

By default the `parseFlags` method parses all flags and tries to autodetect the
type. With the `flags` option you can specify an Array of flag options. If the
`flags` option is set the `parseFlags` method will throw an error for all
unknown or invalid flags. You can find a list of all possible flag options
[here](./flag_options.md).

## Args

The `args` option accepts an array of `ArgumentOptions` objects that define the
expected positional arguments. When defined, non-flag tokens are validated and
typed as positional arguments instead of being added to the `unknown` array. A
`Error` is thrown if more positional arguments are provided than defined.

See [positional arguments](./index.md#positional-arguments) for usage examples.

## Parse

With the `parse` method you can add a custom handler for handling and parsing
types.

> [!NOTE]
> The `parse` method will be called for all types, which means it overrides also
> all built-in types!

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

parseFlags(Deno.args, {
  flags: [{
    name: "foo",
    type: "float",
  }],
  parse: ({ label, name, value, type }: ArgumentValue) => {
    switch (type) {
      case "float":
        if (isNaN(Number(value))) {
          throw new Error(
            `${label} "${name}" must be of type "${type}", but got "${value}".`,
          );
        }
        return parseFloat(value);
      default:
        throw new Error(`Unknown type "${type}".`);
    }
  },
});
```

```console
$ deno run examples/flags/custom_option_processing.ts --foo 1.2
{ flags: { foo: 1.2 }, unknown: [], literal: [] }

$ deno run examples/flags/custom_option_processing.ts --foo abc
error: Uncaught Error: Option "--foo" must be of type "float", but got "abc".
```

## Option callback

The `option` callback method is called for each parsed option.

## Stop early

If `stopEarly` is enabled, all values starting from the first non option
argument are no longer parsed as options. Values that match an
[expected argument](#args) are typed and added to the `args` array, and all
remaining values are added to the `unknown` array (can be combined with
[stopOnUnknown](#stop-on-unknown)).

Without expected arguments, all values are added to the `unknown` array.

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

const argv = ["--debug-level", "warning", "server", "--port", "80"];
const flags = [{ name: "debug-level", type: "string" }];

const withArgs = parseFlags(argv, {
  stopEarly: true,
  flags,
  args: [
    { name: "script", type: "string" },
    { name: "args", type: "string", variadic: true, optional: true },
  ],
});
// withArgs.args -> [ "server", "--port", "80" ]
// withArgs.unknown -> []

const withoutArgs = parseFlags(argv, { stopEarly: true, flags });
// withoutArgs.unknown -> [ "server", "--port", "80" ]
```

## Stop on unknown

If `stopOnUnknown` is enabled, all values starting from the first unknown option
argument are no longer parsed as options. They are matched against the expected
arguments the same way as with [stopEarly](#stop-early), and everything left
over is added to the `unknown` array.

## Allow empty

If a required option is specified, by default an error is thrown if the command
is invoked without any flags. To disable this behavior you can set `allowEmpty`
to `true`. The default is `false`.

## Dotted

By default, all option names that have dots in their names are converted to
nested objects. For example, `{ "foo.bar": 1 }` becomes
`{ "foo": { "bar": 1 } }`. You can disable this behavior by setting the `dotted`
option to `false`. This is required when parsing command line arguments in
multiple steps (see [parse-context](./index.md#parse-context)).