gnu-recutils

Core Commands

| Command | Purpose |

|---------|---------|

| recsel | Select and query records |

| recins | Insert new records |

| recdel | Delete records |

| recset | Modify field values |

| recfix | Validate, check integrity, sort |

| recfmt | Format output with templates |

| recinf | Print information about rec files |

| rec2csv | Convert to CSV |

| csv2rec | Convert from CSV |

Basic File Format

```rec

# Comment line

Field_name: field value

Another_field: another value

Field_name: second record

Another_field: its value

```

Records are separated by blank lines. Field names are case-sensitive and conventionally capitalized.

Multi-line Values

Use + continuation for multi-line content:

```rec

Description: This is the first line

+ and this continues on the second line

+ and a third line too.

```

Or use backslash at end of line:

```rec

Description: This is a long value that \

continues on the next line.

```

Place schema declarations before records:

```rec

%rec: Entity

%key: Id

%mandatory: Id Name

%allowed: Id Name Prototype Description OnLook OnTouch

%type: Prototype rec Entity

%type: Count int

%type: Active bool

%unique: Name

Id: sword

Name: Iron Sword

Count: 1

Active: yes

```

Common Descriptors

| Descriptor | Purpose | Example |

|------------|---------|---------|

| %rec: Type | Names the record type | %rec: Entity |

| %key: field | Primary key (unique, mandatory) | %key: Id |

| %mandatory: f1 f2 | Required fields | %mandatory: Id Name |

| %allowed: f1 f2 | Whitelist of valid fields | %allowed: Id Name Desc |

| %prohibit: f1 | Forbidden fields | %prohibit: Password |

| %unique: field | Field must be unique | %unique: Email |

| %type: field type | Field type constraint | %type: Count int |

| %auto: field | Auto-generated field | %auto: Created_at |

| %sort: field | Default sort order | %sort: Name |

Field Types

| Type | Description | Example Values |

|------|-------------|----------------|

| int | Integer | 42, -7 |

| real | Floating point | 3.14, -2.5 |

| bool | Boolean | yes, no, true, false, 1, 0 |

| line | Single line (no newlines) | Hello world |

| date | ISO 8601 date | 2024-01-15 |

| email | Email address | user@example.com |

| uuid | UUID | 550e8400-e29b-41d4-a716-446655440000 |

| rec Type | Foreign key reference | References another record type |

| enum A B C | Enumeration | One of the listed values |

| regexp /pattern/ | Regex pattern | Must match pattern |

| size N | Max size in bytes | String length limit |

| range MIN MAX | Numeric range | range 1 100 |

Foreign Key References

```rec

%rec: Room

%key: Id

Id: tavern

Name: The Rusty Tavern

%rec: Entity

%key: Id

%type: Room rec Room

Id: mug

Name: Beer Mug

Room: tavern

```

Entity Containment (MUDD)

Entities can be nested using a Container field:

```rec

%rec: Entity

%key: Id

%type: Prototype rec Entity

%type: Container rec Entity

Id: table

Name: Wooden Table

Prototype: furniture

Id: lamp

Name: Brass Lamp

Prototype: object

Container: table

```

The lamp is "on" the table. Recfix validates that Container references exist.

Query Records

```bash

# All records

recsel data.rec

# Filter by field value

recsel -e 'Name = "sword"' data.rec

# Pattern matching

recsel -e 'Name ~ "Iron"' data.rec

# Numeric comparison

recsel -e 'Count > 5' data.rec

# Multiple conditions

recsel -e 'Type = "weapon" && Count > 0' data.rec

# Select specific fields

recsel -p Id,Name data.rec

# Count matching records

recsel -c -e 'Active = yes' data.rec

# Select by record type

recsel -t Entity data.rec

```

Insert Records

```bash

# Insert from stdin

echo -e "Id: axe\nName: Battle Axe" | recins data.rec

# Insert with field values

recins -f Id -v sword -f Name -v "Iron Sword" data.rec

```

Modify Records

```bash

# Update field value

recset -e 'Id = "sword"' -f Count -s 5 data.rec

# Delete field from record

recset -e 'Id = "sword"' -f Obsolete -d data.rec

```

Delete Records

```bash

# Delete matching records

recdel -e 'Count = 0' data.rec

# Delete by record number

recdel -n 3 data.rec

```

Validate

```bash

# Check file integrity

recfix data.rec

# Check and report all errors

recfix --check data.rec

```

Convert Formats

```bash

# To CSV

rec2csv data.rec > data.csv

# From CSV

csv2rec data.csv > data.rec

```

Format Output

```bash

# Custom output format

recsel data.rec | recfmt '{{Id}}: {{Name}}\n'

# Template-based formatting (recfmt reads from stdin)

recsel data.rec | recfmt -f template.fmt

```

Used with -e flag in recsel, recdel, recset:

| Operator | Meaning | Example |

|----------|---------|---------|

| = | Equals | Name = "sword" |

| != | Not equals | Type != "armor" |

| <, >, <=, >= | Numeric comparison | Count > 5 |

| ~ | Regex match | Name ~ "^Iron" |

| && | Logical AND | Type = "weapon" && Rare = yes |

| || | Logical OR | Type = "weapon" || Type = "armor" |

| ! | Logical NOT | ! (Count = 0) |

| #field | Field count (0 if absent) | #Description |

• Use recfix --check before loading data to catch schema violations
• Foreign keys (%type: Field rec OtherType) validate references exist
• Field names start with a letter and contain only [a-zA-Z0-9_]; special fields start with %
• Empty lines separate records; use + continuation for multi-line values
• Comments start with # at the beginning of a line
• For JSON output, pipe through recsel -p and parse with a script

In this project, entity fields use PascalCase (e.g., DescriptionShort, OnAttack). This avoids visual noise from underscores. See data/entities.rec for examples.