# Fixed width records parse

`fixed-width-records-parse` · version 1.0.0 · Structured formats · free, no key needed

Parse fixed-width records with explicit offsets, widths, alignment, padding, Unicode units, and bounded diagnostics.

**Use when you need to: parse fixed width records · decode positional rows to objects · extract named columns from flat records.**

## Decide before calling

Read the [versioned contract](/v1/tools/fixed-width-records-parse/versions/1.0.0) and the supported scope below. Reuse `fixed-width-records-parse@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `fixed-width-records-parse@1.0.0` for parse fixed width records. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- parse fixed width records
- decode positional rows to objects
- extract named columns from flat records
- trim aligned legacy fields
- read utf8 positional records
- convert fixed layout text to records

## Not supported

- format or write fixed-width records
- infer layouts or field widths
- parse delimiter-separated CSV

## Behavior

- Offsets are zero-based and half-open; declared field extents must not overlap; code_point counts Unicode scalar values and utf8_byte counts encoded bytes.
- Declared line_endings is enforced; any accepts LF, CRLF, or CR and normalizes them to records.
- A field beyond a record reports record_too_short; UTF-8 byte boundaries inside a sequence report split_utf8_sequence.
- left alignment removes trailing padding and requires no non-padding after padding; right alignment is symmetric; none preserves bytes/code points.
- Input order determines record, field, and selected-field output order; ties retain declaration order.
- At most 4,096 diagnostics are returned; discovering a 4,097th diagnostic throws limit_exceeded.
- Pure bounded slicing without clock, locale, network, or randomness.

## Input

- `text` (string, required): max length 262144
- `fields` (array of object, required): min items 1; max items 64
- `unit` (one of "code_point", "utf8_byte", required)
- `line_endings` (one of "lf", "crlf", "any", required)

## Output

- `reference_version` (constant "Python 3.13 str slicing; GNU Coreutils cut 9.7", required)
- `lines_in` (integer, required): min 0; max 4096
- `records` (array of object, required): max items 4096
- `errors` (array of object, required): max items 4096

## Limits

- max input bytes: 262144
- max fields: 64
- max rows: 4096
- max diagnostics: 4096
- max output bytes: 1048576

## Example

Request input:

```json
{
  "text": "A  12",
  "fields": [
    {
      "name": "a",
      "offset": 0,
      "width": 3,
      "alignment": "left",
      "padding": " "
    },
    {
      "name": "n",
      "offset": 3,
      "width": 2,
      "alignment": "right",
      "padding": " "
    }
  ],
  "unit": "code_point",
  "line_endings": "lf"
}
```

Response:

```json
{
  "result": {
    "reference_version": "Python 3.13 str slicing; GNU Coreutils cut 9.7",
    "lines_in": 1,
    "records": [
      {
        "a": "A",
        "n": "12"
      }
    ],
    "errors": []
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "fixed-width-records-parse",
  "version": "1.0.0",
  "input": {
    "text": "A  12",
    "fields": [
      {
        "name": "a",
        "offset": 0,
        "width": 3,
        "alignment": "left",
        "padding": " "
      },
      {
        "name": "n",
        "offset": 3,
        "width": 2,
        "alignment": "right",
        "padding": " "
      }
    ],
    "unit": "code_point",
    "line_endings": "lf"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/fixed-width-records-parse/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"text":"A  12","fields":[{"name":"a","offset":0,"width":3,"alignment":"left","padding":" "},{"name":"n","offset":3,"width":2,"alignment":"right","padding":" "}],"unit":"code_point","line_endings":"lf"}'
```

The machine-readable contract is at [/v1/tools/fixed-width-records-parse/versions/1.0.0](/v1/tools/fixed-width-records-parse/versions/1.0.0).

### CLI

```sh
node cli.mjs run fixed-width-records-parse 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Fixed width records slice](/tools/fixed-width-records-slice): Slice selected fixed-width fields with explicit offsets, Unicode units, padding checks, and bounded diagnostics.
- [Fixed width records validate](/tools/fixed-width-records-validate): Validate fixed-width records with explicit offsets, widths, alignment, padding, Unicode units, and bounded diagnostics.
- [Asn1 der primitive decode](/tools/asn1-der-primitive-decode): Decode one universal DER primitive from lowercase hex into typed fields.
- [Gitconfig parse](/tools/gitconfig-parse): Parse git config text into ordered sections, subsections, and multivar entries.
- [Asn1 der parse](/tools/asn1-der-parse): Parse one ASN.1 DER value into a flat schema-free TLV node list.
- [Toml10 format](/tools/toml10-format): Emit canonical TOML 1.0 source from a typed document tree.