# gizlang/flags

a command line's words and flags, by one rule for every tool. A flag that takes a value is `--name value` or `--name=value`, a switch is `--name` (one listed as `--name=` may also say how: `--think=low`), and a flag may be given more than once (Flags.all).

```gizlang
import * as Flags from "gizlang/flags";
```

## Types

### `Flags`

```gizlang
type Flags = { words: Vec<string>; names: Vec<string>; values: Vec<string>; }
```

The words of a command line in their order, and its flags with their values ("" for a bare switch), in theirs.

- `words`: `Vec<string>`
- `names`: `Vec<string>`
- `values`: `Vec<string>`

## Functions

### `without`

```gizlang
function without(given: Vec<string>, names: Vec<string>): Vec<string>
```

`given` without the valued flags `names`, in either form (`--name VALUE` or `--name=VALUE`): a command line to
hand on with those flags set anew.

Effects: fail, read, write, alloc.

### `parse`

```gizlang
function parse(given: Vec<string>, valued: Vec<string>, switches: Vec<string>, others: bool = false, leading: bool = false): Flags throws string
```

The words and flags of `given`: `valued` are the flags that take a value, `switches` those that take none (one
listed as "--name=" takes `--name` or `--name=value`, never the next word). A word
that starts with "--" and is neither fails, unless `others`: then it stays among the words as it is, so a later
parse with the other flags reads them. The words after `--`, and with `leading` the words from the first word on (a
program's own arguments), are words as they are.

Effects: fail, alloc.

## Methods

### `Flags.has`

```gizlang
function Flags.has(self: Flags, name: string): bool
```

Whether flag `name` was given.

Effects: fail.

### `Flags.all`

```gizlang
function Flags.all(self: Flags, name: string): Vec<string>
```

The values of every use of flag `name`, in order.

Effects: fail, alloc.

### `Flags.text`

```gizlang
function Flags.text(self: Flags, name: string, otherwise: string): string
```

The value of flag `name`'s first use, or `otherwise`.

Effects: fail.

### `Flags.whole`

```gizlang
function Flags.whole(self: Flags, name: string, otherwise: i64): i64 throws string
```

Flag `name`'s value as a whole number of 0 or more, or `otherwise`.

Effects: fail, alloc.

### `Flags.real`

```gizlang
function Flags.real(self: Flags, name: string, otherwise: f64): f64 throws string
```

Flag `name`'s value as a number, or `otherwise`.

Effects: fail, alloc.

