GNU Recutils

GNU recutils is a set of tools for managing human-readable, plain-text databases. Records are stored in .rec files with a simple field: value syntax.

Quick Reference

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.

Schema Definitions (%rec Descriptors)

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.

Common Operations

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

Expression Syntax

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 NOT	`! (Count = 0)`
`#field`	Field count (0 if absent)	`#Description`

Tips

•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

MUDD Naming Convention

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