🤖 AI-Generated Project: This project was realized as a test of GitHub Copilot Agent, and as such, 99% of the code, documentation and is AI-generated. It demonstrates the capabilities of AI-assisted software development for creating complete, functional programming language implementations.
⚠️ IN OTHER WORDS: Use at your own risk! — lampmaker
🌐 Try the Interactive Demo | 📁 GitHub Repository
TSON (Typed Structured Object Notation) is a human-friendly, compact superset of JSON designed for structured data representation. It introduces concise notation for tables, arrays, and blocks while preserving full compatibility with JSON.
- 🔄 100% JSON Compatible - All valid JSON is valid TSON
- 📋 Structured Tables - First-class support for tabular data
- 🗺️ Map Tables - Convert tables to key-value object maps
- 🔢 Matrices - 2D arrays without headers
- 📝 Text Blocks - Multiline strings without escaping
- 🏷️ Unquoted Keys - Cleaner syntax for simple identifiers
- 🎯 Type Declarations - Explicit
array,table,matrix,textblocks
name: "Alice"
age: 30
active: true
Parses to:
{
name: "Alice",
age: 30,
active: true
}colors: array {
red
green
blue
}
Parses to:
{
colors: ["red", "green", "blue"]
}strokes: table {
x, y, pressure;
10, 20, 0.3;
11, 22, 0.4;
}
Parses to:
{
strokes: [
{ x: 10, y: 20, pressure: 0.3 },
{ x: 11, y: 22, pressure: 0.4 }
]
}robots: maptable {
id, shape, count;
fast, circle, 2;
slow, square, 1;
}
Parses to:
{
robots: {
fast: { shape: "circle", count: 2 },
slow: { shape: "square", count: 1 }
}
}points: matrix {
1, 2, 3
4, 5, 6
}
Parses to:
{
points: [
[1, 2, 3],
[4, 5, 6]
]
}description: text {
This is a multiline
paragraph with no
quotes or escaping needed.
}
Parses to:
{
description: "This is a multiline\nparagraph with no\nquotes or escaping needed."
}
⚠️ Important: Text blocks always require braces (text { ... }), even when using indented block syntax. This prevents ambiguity when multiline text contains colons, tabs, or other characters that could be misinterpreted as TSON syntax.
# Safe - no ambiguity possible
content: text {
name: John
age: 30
details: sensitive info
}
# Indented blocks work for other types
data: table
key value
a 1
b 2
npm install tsonimport { TSONParser } from 'tson';
import { TSONCreator } from 'tson/creator';
const parser = new TSONParser();
// Parse TSON text
const result = parser.parse(`
name: Alice
scores: array { 95, 87, 92 }
data: table {
x, y;
1, 2;
3, 4;
}
`);
console.log(result);
// Output: {
// name: "Alice",
// scores: [95, 87, 92],
// data: [{x: 1, y: 2}, {x: 3, y: 4}]
// }// Check for syntax errors
const errors = parser.check(tsonText);
if (errors.length === 0) {
console.log('✅ Valid TSON');
} else {
console.log('❌ Errors:', errors);
}<!DOCTYPE html>
<html>
<head>
<script type="module">
import { TSONParser } from './src/tson.js';
const parser = new TSONParser();
const result = parser.parse('name: "World"');
console.log(result); // { name: "World" }
</script>
</head>
</html>Critical: Block types must be placed directly after the colon with no line breaks:
# ✅ CORRECT - Block type immediately follows colon
robots: maptable {
key shape speed
fast circle 10
slow square 5
}
scores: table {
name grade
Alice 95
Bob 87
}
matrix: matrix {
1 2 3
4 5 6
}
# ❌ INCORRECT - Block type on new line
robots:
maptable {
key shape speed
fast circle 10
}
Why this matters: TSON parsers expect the block type declaration to be part of the key-value assignment. Placing it on a new line creates ambiguous syntax.
- All standard JSON syntax works unchanged
- Objects:
{ "key": "value" } - Arrays:
[1, 2, 3] - Primitives: strings, numbers, booleans, null
name: "Alice" # Instead of "name": "Alice"
age: 30 # Numbers, booleans auto-parsed
# Full-line comments
# Indented comments also work
name: "Alice"
array { ... }- Collection of valuestable { ... }- Tabular data with headersmaptable { ... }- Table converted to object mapmatrix { ... }- 2D array without headerstext { ... }- Multiline string block
📝 Text Block Requirements: Unlike other block types, text blocks always require braces for safety. This prevents ambiguity when text content contains TSON syntax characters like colons
:, tabs, or nested structures.
Most block types support both braced and indented syntax:
# Braced syntax
data: table {
name age
Alice 30
Bob 25
}
# Indented syntax (same result)
data: table
name age
Alice 30
Bob 25
# Text blocks ALWAYS need braces (for safety)
content: text {
This can contain: colons and tabs safely
Without being misinterpreted as TSON syntax
}
- Tables/Matrices: Columns separated by spaces or commas
- Rows: Separated by newlines or semicolons
; - Objects: Commas optional outside arrays
Parses TSON text and returns the resulting object. Returns null if there are syntax errors.
Validates TSON text and returns an array of error messages. Empty array means valid syntax.
The TSONCreator class converts JavaScript objects back to TSON format with configurable formatting options.
import { TSONCreator } from 'tson/creator';
const creator = new TSONCreator({
// Indentation settings
indentType: 'spaces', // 'spaces' | 'tabs'
indentSize: 2, // number of spaces (ignored for tabs)
// Block formatting
blockStyle: 'indented', // 'indented' | 'braced'
// Table formatting
tableDelimiter: 'space', // 'space' | 'comma'
// Quoting behavior
quoteKeys: 'minimal', // 'minimal' | 'always' | 'never'
quoteValues: 'minimal', // 'minimal' | 'always' | 'never'
// Structure detection thresholds
arrayThreshold: 3, // Convert to array block if >=3 items
tableThreshold: 2, // Convert to table if >=2 objects with shared keys
// Missing property handling
fillMissingProperties: false, // Fill missing table columns with null
missingValue: null // Value to use for missing properties
});Converts a JavaScript object to TSON format.
const creator = new TSONCreator();
const data = {
name: 'Alice',
age: 30,
workdays: { monday: true, tuesday: false },
scores: [95, 87, 92]
};
const tsonString = creator.stringify(data);
console.log(tsonString);
// Output:
// name: Alice
// age: 30
// workdays:
// monday: true
// tuesday: false
// scores: array
// 95
// 87
// 92Spaces (default):
const creator = new TSONCreator({ indentType: 'spaces', indentSize: 2 });
// Output uses 2 spaces for indentationTabs:
const creator = new TSONCreator({ indentType: 'tabs' });
// Output uses tab characters for indentationCustom spacing:
const creator = new TSONCreator({ indentType: 'spaces', indentSize: 4 });
// Output uses 4 spaces for indentationdocs/tson_2.2.md- Complete formal specification and EBNF grammardocs/REVISIONS.md- Version history and change tracking
# Clone the repository
git clone https://github.com/yourusername/tson.git
cd tson
# Test the parser and creator
node test_indentation.js
# Open the interactive demo
# Open index.html in your browser├── src/
│ ├── tson.js # Main TSON parser
│ └── tson-creator.js # TSON creator for bidirectional conversion
├── docs/
│ ├── tson_2.2.md # Formal specification
│ ├── REVISIONS.md # Version history
│ └── changes.txt # Change log
├── test/
├── index.html # Interactive browser demo
├── package.json
├── changes.txt # Change log
├── TESTING_GUIDE.md # Testing instructions
└── README.md
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
- JSON - The original data format
- YAML - Another human-readable data format
- TOML - Configuration file format
TSON 2.2 - Making structured data more human-friendly while staying JSON-compatible.