Page generated from: QSet_Spec_v4.4.md

Set|Files Q-Set Specification

Version 4.4 - The Baseline Standard
Updated: January 2025

What is Q-Set?

Q-Set (Quick SET) is the baseline specification for SET Files. It defines the minimal, guaranteed feature set that all SET file parsers should support.

Philosophy: Q-Set is the solid foundation. Simple, stable, and reliable. If you can read .qset files, you have everything you need for configuration, data tables, and text content.

File Extension: .qset

Relationship to X-Set: Q-Set is complete on its own. X-Set (eXtended SET) provides optional extensions when you need additional capabilities. See XSet_Overview_v4.4.md for details.

What Q-Set Provides

✅ Core Features:

Groups [GROUPNAME] for organizing data
Text groups [{GROUPNAME}] for multi-line content with no escaping
Key-value pairs
Tables with field definitions
Comments for documentation
Pipe-delimited fields (default: |)
Secondary delimiter for nested arrays (default: !)
Simple, predictable parsing

🚫 What Q-Set Does NOT Include:

Custom delimiters (that's X-Set: delimiters extension)
File metadata beyond comments (that's X-Set: needs [THIS-FILE] group)
Advanced features like includes, schemas, validation (those are X-Set extensions)

Note: Q-Set is intentionally minimal. When you need more, graduate to X-Set by adding a [THIS-FILE] group with an X-SET declaration. See XSet_Overview_v4.4.md.

File Structure
Groups
Text Groups
Basic Examples
Best Practices

THE Q-SET SPECIFICATION

1. File Structure

Default Delimiters

Q-Set uses fixed delimiters. These cannot be changed in Q-Set (use X-Set if you need custom delimiters).

Group start: [
Group end: ]
Text group start: [{
Text group end: }]
Field delimiter: | (pipe)
Secondary delimiter: ! (exclamation, for nested arrays)
Escape character: \ (backslash)

File Organization

A Q-Set file consists of:

Filename comment (optional but recommended) - First line of the file
Comments - Any text outside of groups
Groups - Sections containing data

Example:


myconfig.qset

Configuration file for MyApp
Created: 2025-01-22

[DATABASE]
Host|localhost
Port|5432

[APP_SETTINGS]
Theme|dark
Language|en-US

Parsing Rules

Files are parsed line-by-line (newline = LF or CRLF)
Empty lines between groups are ignored
Empty line after group data = end of group
Text outside groups = comments
Lines are trimmed of leading/trailing whitespace
Groups must have unique names within a file

2. Groups

Basic Group Syntax

Format: [GROUPNAME]

Naming Rules:

Letters (a-z, A-Z)
Numbers (0-9)
Hyphens (-)
Underscores (_)
No spaces or special characters
Convention: ALL_CAPS or PascalCase

Example:


[CONFIG]
AppName|MyApplication
Version|1.0.0
Debug|false

[USERS]
{id|username|email}
1|alice|alice@example.com
2|bob|bob@example.com

Group Content Types

Groups can contain:

1. Key-Value Pairs:


[SETTINGS]
Width|1920
Height|1080
Fullscreen|true

2. Tables with Field Definitions:


[EMPLOYEES]
{id|name|department|email}
101|Alice|Engineering|alice@example.com
102|Bob|Sales|bob@example.com
103|Carol|Marketing|carol@example.com

3. Simple Lists:


[ALLOWED_HOSTS]
localhost
127.0.0.1
example.com
api.example.com

4. Delimited Arrays:


[SERIAL_CONFIG]
Protocol|RS232|9600|8|N|1|none

End of Group

A group ends when:

An empty line is encountered
Another group begins (next [GROUPNAME])
End of file

Example:


[DATABASE]
Host|localhost
Port|5432

[APP]
Name|MyApp
Version|1.0

The empty line between [DATABASE] and [APP] ends the DATABASE group.

3. Text Groups

Text groups store multi-line content with no escaping or delimiter processing. This is perfect for licenses, README content, code samples, JSON/XML/HTML blocks, etc.

Syntax

Format: [{GROUPNAME}]

Rules:

Content is preserved exactly as-is
No escape sequences processed
No delimiter processing
Pipe characters | are literal
Ends only at another group marker or EOF
Does NOT end at empty lines (unlike regular groups)

Example:


[{LICENSE}]
MIT License

Copyright (c) 2025 Your Name

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...

[NEXT_GROUP]

Text Groups for Code/Data

Text groups are excellent for embedding code samples or structured data:


[{JSON_CONFIG}]
{
  "database": {
    "host": "localhost",
    "port": 5432
  },
  "cache": {
    "enabled": true,
    "ttl": 3600
  }
}

[{PYTHON_SAMPLE}]
def hello(name):
    print(f"Hello, {name}!")
    return True

[{HTML_TEMPLATE}]
<div class="container">
  <h1>{{title}}</h1>
  <p>{{content}}</p>
</div>

Referencing Text Groups

Text groups can be referenced in regular groups:


[APP_INFO]
Name|MyApp
License|[{LICENSE}]
Template|[{HTML_TEMPLATE}]

[{LICENSE}]
MIT License
Copyright (c) 2025...

[{HTML_TEMPLATE}]
<html>...</html>

When parsing, [{LICENSE}] as a value indicates the parser should retrieve the content of the LICENSE text group.

4. Basic Examples

Example 1: Simple Configuration


config.qset

Application configuration for production

[DATABASE]
Host|db.example.com
Port|5432
Username|app_user
Database|myapp_production

[CACHE]
Host|redis.example.com
Port|6379
TTL|3600

[APP]
Name|MyApplication
Version|2.1.0
Debug|false
LogLevel|INFO

Example 2: User Table


users.qset

User database for MyApp

[USERS]
{id|username|email|role|active}
1|alice|alice@example.com|admin|true
2|bob|bob@example.com|user|true
3|charlie|charlie@example.com|user|false
4|diana|diana@example.com|moderator|true

Example 3: Mixed Content


app.qset

Application data and documentation

[CONFIG]
AppName|MyApp
Version|1.0.0
Author|CodeMonkey
License|[{LICENSE}]

[BUILD]
Command|npm run build
Output|dist/
Entry|src/index.js

[{LICENSE}]
MIT License

Copyright (c) 2025 CodeMonkey

Permission is hereby granted, free of charge...

[{README}]
# MyApp

This is a simple application that demonstrates Q-Set configuration.

## Features
- Fast loading
- Simple config
- Easy to edit

## Installation
npm install

Example 4: Nested Arrays

Using the secondary delimiter ! for nested data:


menu.qset

Application menu structure

[MENU_ITEMS]
{id|label|subitems}
1|File|New!Open!Save!Save As!Exit
2|Edit|Undo!Redo!Cut!Copy!Paste!Preferences
3|View|Zoom In!Zoom Out!Full Screen!Toggle Sidebar
4|Help|Documentation!About!Check for Updates

Parse each field, then split the subitems field on ! to get the nested array.

Example 5: Escape Sequences

When you need literal pipe or backslash characters in data:


expressions.qset

[EXPRESSIONS]
Condition|value > 10 \| value < 5
WindowsPath|C:\\Program Files\\MyApp\\data
Regex|\\d+\\.\\d+

[SETTINGS]
Expression|price \| quantity > 100

The \| becomes a literal pipe, \\ becomes a literal backslash.

5. Best Practices

Naming Conventions

Groups:

Use ALL_CAPS for configuration groups: [DATABASE], [APP_SETTINGS]
Use PascalCase for data groups: [UserProfiles], [OrderItems]
Use descriptive names: [EMAIL_CONFIG] not [EC]

Text Groups:

Use ALL_CAPS: [{LICENSE}], [{README}], [{TEMPLATE}]
Match content type: [{JSON_CONFIG}], [{SQL_SCHEMA}]

Files:

Use lowercase with .qset extension
Descriptive names: database-config.qset, users-table.qset
Include purpose in name: app-production.qset, test-data.qset

File Organization

Add filename as first line - helps identify files when copied/pasted
Group related data together - all database settings in one group
Use comments liberally - explain non-obvious configurations
Add blank lines - visual separation improves readability
Order groups logically - most important/frequently accessed first

Good organization:


myapp-config.qset

Production configuration for MyApp
Last updated: 2025-01-22

Database connection settings
[DATABASE]
Host|db.example.com
Port|5432

Redis cache configuration
[CACHE]
Host|redis.example.com
Port|6379

Application settings
[APP]
Name|MyApp
Version|1.0.0

When to Use Text Groups

Use text groups for:

Multi-line content (licenses, READMEs, documentation)
Code samples (HTML, CSS, JavaScript, Python, etc.)
Structured data (JSON, XML, YAML blocks)
Templates (email templates, HTML layouts)
Content with special characters (avoiding escape sequence hassles)

Use regular groups for:

Configuration key-value pairs
Tabular data (users, products, transactions)
Lists of items
Short, structured data

Validation Tips

Check for unique group names - duplicates cause ambiguity
Validate field counts in tables - ensure rows match field definition
Test escape sequences - verify \| and \\ work as expected
Verify text group boundaries - make sure they end where expected
Check character encoding - Q-Set assumes UTF-8

Security Considerations

Never store plain-text passwords - use environment variables or encrypted values
Be careful with file permissions - restrict access to sensitive configs
Validate input - don't trust user-provided .qset files without validation
Sanitize output - escape text group content before displaying in HTML
Limit file sizes - prevent DoS from extremely large files

Comments

Text outside of groups is ignored and serves as comments:


myfile.qset

This is a comment explaining the file.
It will be ignored by the parser.

[CONFIG]
Key|Value

Another comment here describing the next group.

[DATABASE]
Host|localhost

Documentation pattern:

Text immediately before a group (with no blank line) is considered documentation for that group:


Database connection settings for production environment
[DATABASE]
Host|db.example.com
Port|5432

Field Definitions

For tables, define field names on the first line after the group marker:

Syntax: {field1|field2|field3}


[CONTACTS]
{id|name|email|phone}
1|Alice|alice@example.com|555-1234
2|Bob|bob@example.com|555-5678
3|Carol|carol@example.com|555-9012

Field definitions provide:

Self-documenting data structure
Column order specification
Parser hints for validation
Human readability

Without field definitions:

The parser must assume column positions or use row 1 as headers.

With field definitions:

The parser knows exactly what each field represents.

Escape Sequences

Only needed in regular groups (not in text groups).

Default escape character: \ (backslash)

Common uses:


[SETTINGS]
Expression|value > 10 \| value < 5
WindowsPath|C:\\Program Files\\MyApp\\
Regex|\\d+\\.\\d+

In text groups: No escaping needed at all


[{CODE_SAMPLE}]
if (value | flag) {
    path = C:\Program Files\MyApp\
    regex = \d+\.\d+
}

Everything in the text group is literal - no escape processing.

Moving to X-Set

Q-Set provides everything needed for most configuration and data storage needs. However, when you need additional capabilities, X-Set (eXtended SET) offers optional extensions.

Move to X-Set when you need:

Custom delimiters (use : or ; instead of |)
File metadata and versioning (via [THIS-FILE] group)
File includes (combine multiple .set files)
Schema validation (enforce data types and rules)
Conditional sections (platform-specific configs)
Advanced features from the X-Set extensions catalog

To use X-Set:

Change file extension from .qset to .xset
Add [THIS-FILE] group as the first group
Declare needed extensions via X-SET line
See XSet_Overview_v4.4.md for complete details

Example transition:

Before (Q-Set):


config.qset

[DATABASE]
Host|localhost
Port|5432

After (X-Set with custom delimiter):


config.xset

[THIS-FILE]
X-SET|delimiters:1.0

[DELIMITERS]
Primary|;

[DATABASE]
Host;localhost
Port;5432

Appendix: Quick Reference

File Structure


filename.qset
Comments outside groups
[GROUP]
data
[{TEXT_GROUP}]
multi-line content

Group Types


[REGULAR_GROUP]      # Standard group with delimited data
[{TEXT_GROUP}]       # Multi-line, no escaping

Line Formats


SingleValue          # No delimiter
Key|Value            # Key-value pair
F1|F2|F3             # Array of fields
Menu|Sub1!Sub2!Sub3  # Nested array (! delimiter)

Special Syntax


{field1|field2}      # Field definitions for tables
\|                   # Escaped pipe (literal |)
\\                   # Escaped backslash (literal \)
[{GROUP_REF}]        # Reference to text group

Comments


Any text outside groups is a comment

Documentation immediately before group
[GROUP]

License

This specification is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).

You are free to:

Share — copy and redistribute the material in any medium or format
Adapt — remix, transform, and build upon the material for any purpose, even commercially

Under the following terms:

Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made

Full license text: https://creativecommons.org/licenses/by/4.0/

_End of SET Files Q-Set Specification v4.4_

Questions or feedback?
Visit: https://setfiles.org
GitHub: https://github.com/kirksiqveland/setfile

License:
Creative Commons Attribution 4.0 International (CC BY 4.0)
Copyright (c) 2025 Kirk Siqveland

Page last modified on January 31, 2026, at 07:56 PM

Set|Files Q-Set Specification

What is Q-Set?

What Q-Set Provides

Table of Contents

THE Q-SET SPECIFICATION

1. File Structure

Default Delimiters

File Organization

Parsing Rules

2. Groups

Basic Group Syntax

Group Content Types

End of Group

3. Text Groups

Syntax

Text Groups for Code/Data

Referencing Text Groups

4. Basic Examples

Example 1: Simple Configuration

Example 2: User Table

Example 3: Mixed Content

Example 4: Nested Arrays

Example 5: Escape Sequences

5. Best Practices

Naming Conventions

File Organization

When to Use Text Groups

Validation Tips

Security Considerations

Comments

Field Definitions

Escape Sequences

Moving to X-Set

Appendix: Quick Reference

File Structure

Group Types

Line Formats

Special Syntax

Comments

License