https://github.com/escherize/silo-spec
A file format to pack and unpack directory trees
https://github.com/escherize/silo-spec
Last synced: 5 months ago
JSON representation
A file format to pack and unpack directory trees
- Host: GitHub
- URL: https://github.com/escherize/silo-spec
- Owner: escherize
- Created: 2025-08-21T03:37:08.000Z (11 months ago)
- Default Branch: master
- Last Pushed: 2025-08-21T03:44:48.000Z (11 months ago)
- Last Synced: 2025-10-06T03:59:02.089Z (9 months ago)
- Size: 4.88 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Silo File Format Specification v0.2
## 1. Purpose
A single UTF-8 plaintext file that represents a complete directory tree. Optimized for hand-writing and inspection.
## 2. Terminology
Key words MUST, SHOULD, MAY are per RFC 2119/8174.
## 3. Overview
A Silo file is a sequence of file sections. Each section starts with a file declaration line, followed by the file’s content lines. A fixed delimiter string identifies declaration lines. Blank lines outside sections are ignored.
## 4. Delimiter
- The delimiter MUST be a non-empty sequence of one or more Unicode characters that are not ASCII space (0x20), horizontal tab (0x09), line feed (0x0A), or carriage return (0x0D). Emoji and symbols are allowed (e.g., 🌾, ❖❖❖, ::, ===, ***).
- The delimiter is auto-detected from the first non-blank line, which MUST be a valid file declaration.
- All declarations in the file MUST use the exact same delimiter string. Matching is byte-exact in UTF-8.
- Writers MUST choose a delimiter such that no content line in the file begins with . If a collision would occur, choose a different delimiter.
## 5. File declaration
Syntax:
```
```
Rules:
- is one ASCII space (0x20).
- is a POSIX-style relative path using /.
- Paths MUST NOT be absolute, contain .., or contain NUL.
- Duplicate s MUST be rejected.
## 6. Content
- All lines after a declaration up to the next declaration belong to that file.
- Content is included verbatim.
- Each file’s content MUST end with a newline. Readers MUST behave as if a trailing \n is present. Writers SHOULD include it.
- Readers MUST accept \n and \r\n; delivered content uses \n.
## 7. Collisions
- A line starting with is always interpreted as a file declaration.
- Writers MUST choose a delimiter such that no content line begins with .
- If a collision would occur, writers MUST choose a different delimiter.
## 8. Ignored lines
- Blank or whitespace-only lines outside any section are ignored.
- Blank lines inside a section are preserved.
## 9. Directories
- Directories are implicit. Implementations MUST create intermediate directories as needed for each .
## 10. Media type and extension
- Suggested media type: application/vnd.silo.tree
- Suggested extension: .silo
## 11. Security considerations
- Reject absolute paths, .., and drive letters.
- Impose limits (file count, path length, file size).
- Write atomically with safe permissions.
## 12. Errors
Implementations MUST error on:
- Inconsistent delimiter string.
- Duplicate .
- Disallowed (absolute, .., empty, or .).
## 13. ABNF (informative)
ABNF cannot enforce "same delimiter string" globally and is limited for Unicode classes; prose above is normative.
```abnf
silo = *blank-line *(section *blank-line)
section = file-decl *content-line
file-decl = delim SP path-chars EOL
delim = 1*delim-char ; any non-whitespace Unicode scalar value
; delim-char is any Unicode scalar value except SPACE, TAB, CR, LF
; (expressed in prose; UTF-8 byte sequences omitted for brevity)
path-chars = 1*path-char
path-char = %x21-7E except %x20 ; visible ASCII except space
content-line = *VCHAR EOL
blank-line = *WSP EOL
SP = %x20
EOL = %x0A / (%x0D %x0A)
VCHAR = %x21-7E
WSP = %x20 / %x09
```
## 14. Reference parsing algorithm (normative)
```
normalize EOL to "\n"; read UTF-8
skip leading blank/whitespace-only lines
read first non-blank line L
let i = index of first ASCII space (0x20) in L
require i > 0
DELIM = L[0:i] ; must contain no SPACE/TAB/CR/LF
PATH = L[i+1:] ; must be non-empty
current = new file(PATH)
for each subsequent line:
if line starts with DELIM + " ":
finalize current; start new file(PATH = text after space)
else:
append line to current file content verbatim
on close of a section, ensure content ends with "\n"
validate paths and duplicates
```
## 15. Writer guidelines
- Prefer a short delimiter like > or 🌾. If any content would start with , switch to another sequence (e.g., ===, ***, ->, ❖❖).
- End the container file with \n.
## 16. Example
Using 🌾 to demonstrate a non-ASCII delimiter:
``` silo
🌾 src/util.py
a = 1
🌾 hi.py
from src.util import a
print(a)
🌾 config/settings.json
{ "debug": true }
```
Yields three files:
- src/util.py with content: `a = 1\n`
- hi.py with content: `from src.util import a\nprint(a)\n`
- config/settings.json with content: `{ "debug": true }`
## 17. Conformance
A "Silo reader" MUST implement Sections 4–12. A "Silo writer" MUST implement Sections 4–8 and SHOULD follow Section 15.