Page generated from: SetFile_Spec_v4_0.md
Version 4.0
Updated: November 2025
This specification is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).
Copyright (c) 2025 Kirk Siqveland
You are free to:
Under the following terms:
Full license text: https://creativecommons.org/licenses/by/4.0/
Implementations of this specification may use any license of the implementer's choosing.
For implementation guidance, examples, and patterns, see:
Set File Implementation Guide v4.0
Set files (.set file extension) are machine-readable and human-readable data files designed for configuration files, structured data, and any scenario requiring both machine-parseability and human-editability.
Set files are used for storing variable format settings, configuration data, and structured information in a format that is easy for both humans to read and edit, and for programs to parse and process.
The primary convention with Set files is pipe-delimited fields, though the specification allows the pipe delimiter to be replaced with a different delimiter when needed or desired.
Human First
Set files prioritize human readability over parsing efficiency.
Simple Specification
The core rules fit on a few pages.
Complex features are optional extensions, not core requirements.
Flexible Implementation
Parse as much or as little as you need.
A minimal parser can be written in ~50 lines of code. Advanced features are available when needed.
Convention Over Enforcement
The format enables patterns but doesn't mandate them.
Implementations choose their own conventions to match their environment.
No Magic
Everything is explicit and visible. No hidden behaviors, no surprising type coercion, no implicit conversions.
Good fits:
Poor fits:
.set - Standard Set file (may use any features).qset - Suggests minimal/simple implementation (conventionally uses only sections 2-4)Note: The "q" in .qset denotes a simplified or "quick" implementation, but functionally both extensions use the same format and specification.
This specification defines the complete Set file format. Implementations may choose to support:
This section defines the absolute minimum requirements for a SET file and parser. Everything in this section is required for basic compliance.
A Set file is organized into:
Typically a Set file consists of:
Example:
myconfig.set
This file contains application configuration.
Created: 2025-11-27
[DATABASE]
Host|localhost
Port|5432
[APP_SETTINGS]
Theme|dark
Language|en-US
[PROTOCOL]
RS232|9600|8|N|1|OffGroups are the fundamental data containers in Set files.
Syntax: [GROUPNAME]
Naming Rules:
Examples:
[DATABASE] ✓[App_Settings] ✓[USER-LIST] ✓[Config 2] ✗ not good (contains space)[My.Config] ✗ not good (contains period)Groups contain data stored by line
Key-Value Pairs:
[SETTINGS]
Key|Value
AnotherKey|Another ValuePositional Fields:
[USERS]
{id|name|email}
1|Alice|alice@example.com
2|Bob|bob@example.comLines in a set file may end with a single LF character or a LF and a CR (line-feed and carriage return) Group contents are always separated by the defined delimiter, typically a pipe - "|"
Groups end when:
[EOG])[EOG] marker is presentExamples:
[SETTINGS]
Key|Value
[ANOTHER_GROUP][SETTINGS]
Key|Value
[EOG]
[ANOTHER_GROUP]Both examples are equivalent. The [EOG] marker is optional but recommended for clarity.
Text blocks store multi-line content without any delimiter processing or escape sequences.
Syntax: [{GROUPNAME}]
Content Rules:
[{GROUPNAME}] and the end marker is preserved exactly[EOG], another group marker, or end of fileExample:
[{LICENSE_TEXT}]
MIT License
Copyright (c) 2025 Kirk Siqveland
Permission is hereby granted, free of charge...
[EOG]Regular groups can reference text blocks using the syntax [{GROUPNAME}] as a value.
Example:
[APP_INFO]
Name|My Application
License|[{LICENSE_TEXT}]
[{LICENSE_TEXT}]
MIT License
Copyright (c) 2025...When parsing, the value [{LICENSE_TEXT}] should be replaced with the content of the [{LICENSE_TEXT}] text block.
Rules:
Default Delimiter: | (pipe character, ASCII 124)
Delimiter|:[]:{}:|:\:…: line in the [THIS-FILE] GroupDelimiter|:[]:{}:#:\:…: Notice # in place of |By default the pipe character "|" separates:
Do not begin or end lines with delimiters - this would shift all field positions.
Escape sequences are only needed in regular groups, not in text blocks.
The default Escape Character: \ (backslash)
Primary Use: Escape the field delimiter within data
Syntax: \|
Example:
[SETTINGS]
Expression|value > 10 \| value < 5
Path|C:\Program Files\App\data.txtThe \| escapes the pipe character so it's treated as literal text, not a field separator.
Edge Case - Field Ending with Backslash:
If a field value ends with a backslash, add a space before the delimiter to prevent ambiguity:
[PATHS]
WindowsPath|C:\Program Files\App\ |NextFieldThe space after the trailing backslash prevents \| from being interpreted as an escaped delimiter.
In Text Blocks: No escaping is needed. Everything is literal.
[{CODE_SAMPLE}]
if (value | flag) {
path = C:\Program Files\App\
}
[EOG]All pipes and backslashes in the text block above are literal - no escaping required.
Note on Character Encoding:
Since Set files use UTF-8 encoding by default, Unicode characters can be included directly without escape sequences:
[MESSAGES]
Welcome|Café ☕
Greeting|你好世界
Symbol|★ ♥ ✓
[EOG]For alternative methods of representing special characters, see Section 7 (Implementation Patterns).
Text Outside Groups:
Any text outside of group markers is ignored by parsers and serves as comments or documentation.
myconfig.set
This is a comment.
It will be ignored by parsers.
[DATABASE]
Host|localhostDocumentation Before Groups:
Text immediately before a group marker (with no blank line) is considered documentation for that group.
Database connection settings for production
[DATABASE]
Host|prod.example.com
Port|5432Unreferenced Text Blocks:
Text blocks that are not referenced anywhere can serve as coherent comment blocks.
[{NOTES}]
These are internal notes.
Not referenced by any group,
so effectively a comment.
[EOG][EOG]Groups using positional fields should define field names on the first line after the group marker.
Syntax: {field1|field2|field3}
Example:
[USERS]
{id|username|email|role}
1|alice|alice@example.com|admin
2|bob|bob@example.com|userField definitions are optional but strongly recommended for clarity and validation.
Syntax: [EOF]
The [EOF] marker is optional. End of file is implicit when the file ends.
This section describes the recommended conventions for configuring parser behavior and storing file metadata.
Convention: The first line of the file should be the filename.
myconfig.set
[SETTINGS]This helps identify the file when contents are copied, embedded, or transmitted separately from filesystem metadata.
[THIS-FILE] GroupParser configuration and file metadata should be stored in a group, typically named [THIS-FILE].
Example:
myconfig.set
[THIS-FILE]
Version|4.0
Created|2025-11-27
Author|Kirk Siqveland
Delimiters|:[]:{}:|:\:…:
Encode|UTF-8
Localize|NFC|en-US|LTR
[EOG]
[SETTINGS]
AppName|My AppRecommended keys for [THIS-FILE] group:
Specifies custom delimiter set for the entire file.
Format: Delimiters|:[]:{}:|:\:…:
How to Read the Delimiter Definition:
The delimiter definition line uses a self-describing format. The first character(s) define how to parse the rest of the line.
Example: :[]:{}:|:\:…:
Breaking this down:
: [] : {} : | : \ : … :
^ ^^ ^ ^^ ^ ^ ^ ^ ^ ^
| | | | | | | | | └─ Optional trailing delimiter
| | | | | | | | └──── Ellipsis marker
| | | | | | | └─────── Delimiter
| | | | | | └────────── Escape character
| | | | | └───────────── Delimiter
| | | | └──────────────── Field delimiter
| | | └──────────────────── Delimiter
| | └─────────────────────── Text block brackets
| └─────────────────────────── Delimiter
└────────────────────────────── Group header bracketsReading process:
:) is the preamble delimiter - used only to parse this line[] = Group header brackets{} = Text block brackets| = Field delimiter (used throughout the file)\ = Escape character… = Ellipsis markerCustom Example:
[THIS-FILE]
Delimiters|;[];{};,;\;...;
[EOG]This sets:
;[]{}, (comma instead of pipe)\... (three periods instead of single character)Default: If not specified, assumes :[]:{}:|:\:…:
Character encoding for the file.
Format: Encode|UTF-8
Common values:
UTF-8 (default and recommended)UTF-16ASCIIISO-8859-1Default: UTF-8
Internationalization settings affecting text processing, sorting, and comparison.
Format: Localize|NORMALIZATION|LOCALE|DIRECTION
Components:
Default: NFC|en-US|LTR
Examples:
Localize|NFC|en-US|LTR # English (US), left-to-right
Localize|NFC|ar-SA|RTL # Arabic, right-to-left
Localize|NFC|multi|AUTO # Multiple languages, auto-detectCommon metadata keys:
Version - Specification version or file format versionCreated - Creation dateModified - Last modification dateAuthor - File creatorCopyright - Copyright noticeDescription - File description or purposeThese are conventions only. Implementations may define their own metadata keys.
The [THIS-FILE] group should be placed:
This is conventional, not required. The group can be placed anywhere in the file. However, if alternative delimiters are defined, they may not be available until the parser has read the [THIS-FILE] group, causing errors.
Regular groups contain delimited data with positional fields - similar to CSV but more readable.
Syntax: [GROUPNAME]
Structure:
[GROUPNAME]
{field1|field2|field3} ← Optional field definition
value1|value2|value3 ← Data records
value1|value2|value3
[EOG] ← Optional end markerExample:
[EMPLOYEES]
{id|first_name|last_name|department|hire_date}
101|Alice|Smith|Engineering|2023-01-15
102|Bob|Jones|Marketing|2023-02-20
103|Carol|White|Engineering|2023-03-10
[EOG]Rules:
value1||value3Field Order: Field order is significant. Each line must match the field definition order.
The same [GROUPNAME] syntax works when used for key-value pairs instead of positional fields.
Structure:
[GROUPNAME]
Key1|Value1
Key2|Value2
Key3|Value3
[EOG]Example:
[DATABASE_CONFIG]
Host|localhost
Port|5432
Database|myapp
Username|admin
Password|secret123
MaxConnections|100
Timeout|30
[EOG]Key Naming Rules: Keys follow the same rules as group names:
Value Rules:
| is the valueKey|Key|[{TEXTBLOCK}]Distinguishing Key-Value from Positional data: There is no syntactic difference. The distinction is semantic:
{field|names} definition → positional fieldsText blocks store raw, unprocessed multi-line content. All content beginning the line after the [{GROUPNAME}] all the way to the [EOG] is stored as exact text (including non-printing characters).
Syntax: [{GROUPNAME}]
Structure:
[{GROUPNAME}]
Raw text content here.
Everything preserved exactly.
No escaping needed!
[EOG]Characteristics:
Use Cases:
Example:
[{README}]
# My Application
## Installation
bash
npm install my-app
## Usage
Run the application with: `./myapp --config=settings.set`
For more information, see the documentation.
[EOG]Content Boundaries: Text block content ends at:
[EOG] markerText blocks can be referenced in regular group values.
Syntax: Use [{GROUPNAME}] as a value
Example:
[APP_INFO]
Name|My Application
Version|2.0.0
Description|[{APP_DESCRIPTION}]
License|[{LICENSE_TEXT}]
Readme|[{README}]
[EOG]
[{APP_DESCRIPTION}]
A powerful tool for managing workflows.
Features include:
- Task tracking
- Team collaboration
- Real-time sync
[EOG]
[{LICENSE_TEXT}]
MIT License
Copyright (c) 2025 Kirk Siqveland
[EOG]
[{README}]
See documentation at: https://example.com/docs
[EOG]Parser Behavior:
When parsing, the value [{APP_DESCRIPTION}] should be replaced with the full content of the text block named APP_DESCRIPTION.
Reference Rules:
[{NAME}] syntax)Multiple References: The same text block can be referenced by multiple groups:
[CONFIG_EN]
Welcome|[{WELCOME_TEXT}]
[CONFIG_ES]
Welcome|[{BIENVENIDA_TEXT}]
[{WELCOME_TEXT}]
Welcome to our application!
[EOG]
[{BIENVENIDA_TEXT}]
¡Bienvenido a nuestra aplicación!
[EOG]A single Set file can contain any combination of group types:
myapp.set
[THIS-FILE]
Version|4.0
Created|2025-11-27
[DATABASE]
Host|localhost
Port|5432
[USERS]
{id|username|email}
1|alice|alice@example.com
2|bob|bob@example.com
[{LICENSE}]
MIT License
Copyright (c) 2025...
[EOG]This section describes advanced features that extend the minimum specification. Implementations may choose to support some, all, or none of these features.
:::)Note: The preamble delimiter (: by default) can be replaced using the Delimiter definition in [THIS-FILE].
Fields prefixed with ::: allow a single field to be added to a single line, eliminating the need for a large number of empty fields in a typical table definition.
Syntax: :::fieldname:value
The ::: marker is followed by the field name, then the preamble delimiter (: by default), then the value.
Example:
[USERS]
{id|username|email|role}
1|alice|alice@example.com|admin
2|bob|bob@example.com|user|:::temp_note:Pending verification
3|charlie|charlie@example.com|userIn line 2, the temp_note field is added just for that record without modifying the field definition. Other records don't need to have empty values for this field.
Use Cases:
Multiple single-use fields on one line:
[CONTACTS]
{id|name|email}
1|Alice|alice@example.com
2|Bob|bob@example.com|:::phone:555-1234|:::department:Engineering
3|Carol|carol@example.comWith custom preamble delimiter:
If your [THIS-FILE] defines delimiters as ;[];{};,;\;...;, then single-use fields would use ;:
[DATA]
{id|value}
1|100
2|200;;;note;Special caseThe ellipsis character … (or three periods ...) indicates "remaining fields are empty."
Example:
[CONTACTS]
{id|name|phone|email|address|city|state|zip}
1|Alice|555-1234|alice@example.com|…
2|Bob|555-5678|…Is equivalent to:
1|Alice|555-1234|alice@example.com||||
2|Bob|555-5678|||||Rules:
For individual lines that contain instances of the standard delimiter, you can override the delimiter for just that line.
Syntax: Line starts with preamble delimiter followed by the single-use delimiter
Example:
[SETTINGS]
AppName|My Application
Port|8080
:!URL!https://example.com/api?param1=value|param2=value|param3=value
:!Expression!(a | b) & (c | d) | (e | f)!notes!Additional field
Database|localhost
[EOG]How it works:
: (the preamble delimiter from [THIS-FILE])! (the single-use delimiter for this line only)! instead of | as field delimiterUse cases:
Without single-line override:
URL|https://example.com/api?param1=value\|param2=value\|param3=valueWith single-line override:
:!URL!https://example.com/api?param1=value|param2=value|param3=valueMuch more readable!
The default delimiter is | (pipe), but the entire file can use custom delimiters via the [THIS-FILE] configuration.
Example:
myconfig.set
[THIS-FILE]
Delimiters|;[];{};,;\;...;
[EOG]
[SETTINGS]
Key,Value
Another,Value
[EOG]This changes the field delimiter from | to , (comma) for the entire file.
When to use alternative delimiters:
Recommendations:
Beyond the basic Localize setting, implementations may support:
Multiple Locale Support:
[THIS-FILE]
Localize|NFC|multi|AUTO
LocaleDetails|en-US,es-ES,fr-FR
[EOG]Collation Rules:
[THIS-FILE]
Localize|NFC|en-US|LTR
Collation|unicode
CaseSensitive|true
[EOG]Bidirectional Text: For mixed LTR/RTL content, implementations may embed Unicode bidirectional control characters or provide directionality hints per-field.
These are implementation-specific extensions and not part of the core specification.
Set File Implementation Guide v4.0
Comprehensive guide covering:
End of Set File Format Specification v4.0
Questions or feedback?
Visit: https://github.com/kirksiqveland/setfile
License:
Creative Commons Attribution 4.0 International (CC BY 4.0)
Copyright (c) 2025 Kirk Siqveland