Introduction

GNU recutils is a set of tools and libraries to access human-editable, text-based databases called recfiles. The data is stored as a sequence of records, each record containing an arbitrary number of named fields. Recfiles are human-readable, human-writable and still easy to parse and to manipulate automatically.

recfile Format

1. Fields : The key–value pairs which comprise the data.

• Example: Name: hamzeh
• The separator between the field name and the field value is a colon followed by a blank character (space and tabs, but not newlines)
• A field name is a sequence of alphanumeric characters plus underscores (_), starting with a letter or the character %. (regex: [a-zA-Z%][a-zA-Z0-9_]*)
• Field names are case-sensitive. Foo and foo are different field names.

2. Records : The main entities of a recfile.

• Example:

Name: hamzeh
Phone: 00989111111111
Email: h.nasajpour@pantherx.org

• It is possible for several fields in a record to share the same name or/and the field value.
• A record cannot be empty, so the minimum size for a record is 1.
• The maximum number of fields for a record is only limited by the available physical resources.
• Records are separated by one or more blank lines.

3. Comments : Information for humans’ benefit only.

• Any line having an # (ASCII 0x23) character in the first column is a comment line.
• Unlike some file formats, comments in recfiles must be complete lines. You cannot start a comment in the middle of a line.

4. Record Description : Describing different types of records. Certain properties of a set of records can be specified by preceding them with a record descriptor. A record descriptor is itself a record, and uses fields with some predefined names to store properties.

• %rec: The most basic property that can be specified for a set of records is their type. The special field name %rec is used for that purpose:
• %type
• %doc As well as a name, it is a good idea to provide a description of the record set. This is sometimes called the record set’s documentation and is specified using the %doc field.
• Record Sets Properties Besides determining the type of record that follows in the stream, record descriptors can be used to describe other properties of those records. This can be done by using special fields, which have special names from a predefined set.

recfile Sample (contacts.rec):

• A Contacts db file.
• It has three fields.
• Name and Phone field are mandatory and they can’t be empty.
• Email field is optional.

# -*- mode: rec -*-
%rec: Contact
%mandatory: Name Phone

Name: hamzeh
Phone: 00989111111111
Phone: 00989123456789
Email: h.nasajpour@pantherx.org

Name: hadi
Phone: 00989222222222

# End of contacts.rec

recutils Commands

1. recinf - reads the given rec files (or the data from standard input if no file is specified) and prints a summary of the record types contained in the input.

$ recinf contacts.rec
2 Contact

2. recfix - check a recfile for errors:

$ recfix contacts.rec

3. recsel - recsel reads the given rec files (or the data in the standard input if no file is specified) and prints out records (or part of records) based upon some criteria specified by the user.

$ recsel contacts.rec
Name: hamzeh
Phone: 00989111111111
Phone: 00989123456789
Email: h.nasajpour@pantherx.org

Name: hadi
Phone: 00989222222222

$ recsel -e "Name = 'hamzeh'" -P Phone contacts.rec
00989111111111
00989123456789

$ recsel -e "Name = 'hamzeh'" -P Email,Phone contacts.rec
h.nasajpour@pantherx.org
00989111111111
00989123456789

4. recins - adds new records to a rec file or to rec data read from standard input.

$ recins -f Name -v Alex -f Phone -v 9898111222333 contacts.rec

$ recsel contacts.rec
Name: Alex
Phone: 9898111222333 

Name: hamzeh
Phone: 00989111111111
Phone: 00989123456789
Email: h.nasajpour@pantherx.org

Name: hadi
Phone: 00989222222222

5. more commands

Reference:

https://www.gnu.org/software/recutils/manual/