# linegauge/plugin

> Every export of linegauge/plugin, with its signature and doc comment: setOverrides, overrides, problems, validate, register, CONTRACT and 1 more, plus 3 types.

Source: https://linegauge.interlace.tools/docs/api/plugin

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { setOverrides, overrides, problems, … } from 'linegauge/plugin';
```

## Functions

### overrides

Every override currently registered, by plugin name — what `linegauge check` prints.

```ts
function overrides(): ReadonlyMap<string, Record<string, WidthOverride>>;
```

**Returns** `ReadonlyMap<string, Record<string, WidthOverride>>`

### problems

Everything wrong with a plugin document, in the family's vocabulary. Empty means it registers.

```ts
function problems(plugin: unknown): Problem[];
```

| Parameter | Type |
| :-- | :-- |
| `plugin` | `unknown` |

**Returns** `Problem[]`

### register

Register a plugin's width overrides. Later registrations win over earlier ones, and over the
built-in tables — which is the point: the built-in answer is right for most terminals and the
user is the authority on theirs.

```ts
function register(plugin: unknown): void;
```

| Parameter | Type |
| :-- | :-- |
| `plugin` | `unknown` |

**Returns** `void`

### setOverrides

Later registrations win, which is the point: the user is the authority on their terminal.

An empty table **removes** the plugin rather than recording that it contributes nothing.
`overrides()` is what `linegauge check` prints and what a caller inspects, and a name in it
with no ranges under it reads as *this plugin is active* when the truth is the opposite.

The seam in `width.ts` is installed only while something is registered, so the last plugin
leaving puts `measure` back on the path with no call in it at all.

```ts
function setOverrides(name: string, widths: Record<string, WidthOverride>): void;
```

| Parameter | Type |
| :-- | :-- |
| `name` | `string` |
| `widths` | `Record<string, WidthOverride>` |

**Returns** `void`

### validate

Throws on the first problem, in the family's vocabulary.

```ts
function validate(plugin: unknown): asserts plugin is Plugin;
```

| Parameter | Type |
| :-- | :-- |
| `plugin` | `unknown` |

**Returns** `asserts plugin is Plugin`

## Classes

### PluginError

A refused plugin says what is wrong and what to do about it — the family's one vocabulary.

```ts
class PluginError extends Error {
    readonly code: PluginErrorCode;
    readonly fix: string;
    constructor(code: PluginErrorCode, message: string, fix: string);
}
```

## Constants

### CONTRACT

The plugin contract version. One number for the family — the same `1` flagstaff, caique,
closeout and paratext declare, written out rather than imported for the reason above.

```ts
const CONTRACT = 1;
```

## Interfaces

### Plugin

The keys linegauge reads. Declared structurally: any object with these fields is a plugin
here, whatever else it carries.

```ts
interface Plugin {
    name: string;
    contract?: number;
    /** Width overrides by name. The key is the author's label; see {@link validate}. */
    widths?: Record<string, WidthOverride>;
}
```

### WidthOverride

One plugin-supplied width override: the column count a set of code-point ranges occupies.

```ts
interface WidthOverride {
    /** Inclusive `[low, high]` code-point pairs. */
    ranges: readonly (readonly [number, number])[];
    /** 0 for a zero-width mark, 1 narrow, 2 wide. */
    columns: number;
    /** Which terminal or font disagrees, and how it was measured. Required; see the file comment. */
    why: string;
}
```

## Types

### PluginErrorCode

Two codes, both already in the family's vocabulary
(`scripts/plugin-error-vocabulary-lock.test.ts`).

```ts
type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT' | 'E_NO_CONTRIBUTION';
```