https://github.com/escherize/tortise_spec
https://github.com/escherize/tortise_spec
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/escherize/tortise_spec
- Owner: escherize
- Created: 2025-08-20T03:00:14.000Z (11 months ago)
- Default Branch: master
- Last Pushed: 2025-08-21T02:13:42.000Z (11 months ago)
- Last Synced: 2025-10-06T03:59:04.281Z (9 months ago)
- Size: 3.91 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
. 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.tortise.tree
- Suggested extension: .tortise
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.
tortise = *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:
``` tortise
🐢 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 “Tortise reader” MUST implement Sections 4–12. A “Tortise writer” MUST implement Sections 4–8 and SHOULD follow Section 15.