dtab 0.1.0__tar.gz

dtab-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: dtab
+Version: 0.1.0
+Summary: Config files made of tab-separated paths. One line is one path into a tree.
+Project-URL: Homepage, https://github.com/RyannDaGreat/dtab
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: fire
+
+<p align="center"><img src="https://raw.githubusercontent.com/RyannDaGreat/dtab/main/assets/logo.jpg" alt="dtab" width="640"></p>
+
+# dtab
+
+Config files made of tab-separated paths. One line is one path into a tree.
+
+```
+objects	l1,l2 light
+deltas	l1	position	x 1	y .5
+	z -2
+```
+
+```python
+import dtab
+dtab.parse(open("scene.dtab").read())
+# {'objects': {'l1': 'light', 'l2': 'light'},
+#  'deltas': {'l1': {'position': {'x': '1', 'y': '.5', 'z': '-2'}}}}
+```
+
+## Why
+
+- Less to look at. No braces, quotes, or commas between values. A file with its tabs aligned reads like pseudocode, and is easy to write by hand, even on paper.
+- Simple. Six rules, one pass, about 70 lines per implementation.
+- Everything is addressable. There are no lists, so every value has a dotted path: `config.deltas.l1.position.x` works with EasyDict in Python and plain property access in JavaScript.
+- You choose the shape. Lines stack, and `c,d` writes one value under several keys, so the same tree can be written wide, deep, or on one line, trading horizontal space for vertical. These are the same file:
+
+  ```
+  a	b	c x
+  a	b	d x
+  ```
+  ```
+  a
+  	b
+  		c x
+  		d x
+  ```
+  ```
+  a	b	c,d x
+  ```
+
+## Rules
+
+- Tabs separate the steps of a path. `deltas	l1	position` walks three keys down. Several tabs in a row count as one, so you can align columns.
+- An entry with a space is `key value`. It sets the key and stays at the same level, so `x 1	y .5` sets two keys.
+- An indented line continues the path of the line above it.
+- Writing a key again replaces it. Writing into an object merges.
+- `a,b` writes the same value under `a` and under `b`.
+- An entry that starts with a space is a comment.
+
+Every value is a string. Cast the ones you need. Keys are identifiers (letters, digits, underscores),
+so attribute access like `config.deltas.l1` works with EasyDict and friends.
+
+## Install
+
+| | |
+|---|---|
+| Python | `pip install dtab` then `import dtab` |
+| JavaScript | `npm install dtab` then `const dtab = require('dtab')`, or `<script src="https://cdn.jsdelivr.net/npm/dtab/dtab.js">` for `window.dtab` |
+| Vim | `Plugin 'RyannDaGreat/dtab'` (Vundle) or `Plug 'RyannDaGreat/dtab'` (vim-plug). Or paste `dtab.vim` into your vimrc. Highlights `*.dtab` and flags bad keys and trailing tabs. |
+
+## API
+
+- `parse(text)` returns nested dicts (Python) or plain objects (JavaScript). Raises on an invalid key, with the line number.
+- `stringify(tree)` writes the tree back out, one key per line.
+- Command line: `dtab scene.dtab` prints the tree as JSON.

dtab-0.1.0/README.md

@@ -0,0 +1,65 @@
+<p align="center"><img src="https://raw.githubusercontent.com/RyannDaGreat/dtab/main/assets/logo.jpg" alt="dtab" width="640"></p>
+
+# dtab
+
+Config files made of tab-separated paths. One line is one path into a tree.
+
+```
+objects	l1,l2 light
+deltas	l1	position	x 1	y .5
+	z -2
+```
+
+```python
+import dtab
+dtab.parse(open("scene.dtab").read())
+# {'objects': {'l1': 'light', 'l2': 'light'},
+#  'deltas': {'l1': {'position': {'x': '1', 'y': '.5', 'z': '-2'}}}}
+```
+
+## Why
+
+- Less to look at. No braces, quotes, or commas between values. A file with its tabs aligned reads like pseudocode, and is easy to write by hand, even on paper.
+- Simple. Six rules, one pass, about 70 lines per implementation.
+- Everything is addressable. There are no lists, so every value has a dotted path: `config.deltas.l1.position.x` works with EasyDict in Python and plain property access in JavaScript.
+- You choose the shape. Lines stack, and `c,d` writes one value under several keys, so the same tree can be written wide, deep, or on one line, trading horizontal space for vertical. These are the same file:
+
+  ```
+  a	b	c x
+  a	b	d x
+  ```
+  ```
+  a
+  	b
+  		c x
+  		d x
+  ```
+  ```
+  a	b	c,d x
+  ```
+
+## Rules
+
+- Tabs separate the steps of a path. `deltas	l1	position` walks three keys down. Several tabs in a row count as one, so you can align columns.
+- An entry with a space is `key value`. It sets the key and stays at the same level, so `x 1	y .5` sets two keys.
+- An indented line continues the path of the line above it.
+- Writing a key again replaces it. Writing into an object merges.
+- `a,b` writes the same value under `a` and under `b`.
+- An entry that starts with a space is a comment.
+
+Every value is a string. Cast the ones you need. Keys are identifiers (letters, digits, underscores),
+so attribute access like `config.deltas.l1` works with EasyDict and friends.
+
+## Install
+
+| | |
+|---|---|
+| Python | `pip install dtab` then `import dtab` |
+| JavaScript | `npm install dtab` then `const dtab = require('dtab')`, or `<script src="https://cdn.jsdelivr.net/npm/dtab/dtab.js">` for `window.dtab` |
+| Vim | `Plugin 'RyannDaGreat/dtab'` (Vundle) or `Plug 'RyannDaGreat/dtab'` (vim-plug). Or paste `dtab.vim` into your vimrc. Highlights `*.dtab` and flags bad keys and trailing tabs. |
+
+## API
+
+- `parse(text)` returns nested dicts (Python) or plain objects (JavaScript). Raises on an invalid key, with the line number.
+- `stringify(tree)` writes the tree back out, one key per line.
+- Command line: `dtab scene.dtab` prints the tree as JSON.

dtab-0.1.0/dtab.egg-info/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: dtab
+Version: 0.1.0
+Summary: Config files made of tab-separated paths. One line is one path into a tree.
+Project-URL: Homepage, https://github.com/RyannDaGreat/dtab
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: fire
+
+<p align="center"><img src="https://raw.githubusercontent.com/RyannDaGreat/dtab/main/assets/logo.jpg" alt="dtab" width="640"></p>
+
+# dtab
+
+Config files made of tab-separated paths. One line is one path into a tree.
+
+```
+objects	l1,l2 light
+deltas	l1	position	x 1	y .5
+	z -2
+```
+
+```python
+import dtab
+dtab.parse(open("scene.dtab").read())
+# {'objects': {'l1': 'light', 'l2': 'light'},
+#  'deltas': {'l1': {'position': {'x': '1', 'y': '.5', 'z': '-2'}}}}
+```
+
+## Why
+
+- Less to look at. No braces, quotes, or commas between values. A file with its tabs aligned reads like pseudocode, and is easy to write by hand, even on paper.
+- Simple. Six rules, one pass, about 70 lines per implementation.
+- Everything is addressable. There are no lists, so every value has a dotted path: `config.deltas.l1.position.x` works with EasyDict in Python and plain property access in JavaScript.
+- You choose the shape. Lines stack, and `c,d` writes one value under several keys, so the same tree can be written wide, deep, or on one line, trading horizontal space for vertical. These are the same file:
+
+  ```
+  a	b	c x
+  a	b	d x
+  ```
+  ```
+  a
+  	b
+  		c x
+  		d x
+  ```
+  ```
+  a	b	c,d x
+  ```
+
+## Rules
+
+- Tabs separate the steps of a path. `deltas	l1	position` walks three keys down. Several tabs in a row count as one, so you can align columns.
+- An entry with a space is `key value`. It sets the key and stays at the same level, so `x 1	y .5` sets two keys.
+- An indented line continues the path of the line above it.
+- Writing a key again replaces it. Writing into an object merges.
+- `a,b` writes the same value under `a` and under `b`.
+- An entry that starts with a space is a comment.
+
+Every value is a string. Cast the ones you need. Keys are identifiers (letters, digits, underscores),
+so attribute access like `config.deltas.l1` works with EasyDict and friends.
+
+## Install
+
+| | |
+|---|---|
+| Python | `pip install dtab` then `import dtab` |
+| JavaScript | `npm install dtab` then `const dtab = require('dtab')`, or `<script src="https://cdn.jsdelivr.net/npm/dtab/dtab.js">` for `window.dtab` |
+| Vim | `Plugin 'RyannDaGreat/dtab'` (Vundle) or `Plug 'RyannDaGreat/dtab'` (vim-plug). Or paste `dtab.vim` into your vimrc. Highlights `*.dtab` and flags bad keys and trailing tabs. |
+
+## API
+
+- `parse(text)` returns nested dicts (Python) or plain objects (JavaScript). Raises on an invalid key, with the line number.
+- `stringify(tree)` writes the tree back out, one key per line.
+- Command line: `dtab scene.dtab` prints the tree as JSON.

dtab-0.1.0/dtab.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+dtab.py
+pyproject.toml
+dtab.egg-info/PKG-INFO
+dtab.egg-info/SOURCES.txt
+dtab.egg-info/dependency_links.txt
+dtab.egg-info/entry_points.txt
+dtab.egg-info/requires.txt
+dtab.egg-info/top_level.txt
+test/test_dtab.py

dtab-0.1.0/dtab.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dtab-0.1.0/dtab.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dtab = dtab:_main

dtab-0.1.0/dtab.egg-info/requires.txt

@@ -0,0 +1 @@
+fire

dtab-0.1.0/dtab.egg-info/top_level.txt

@@ -0,0 +1 @@
+dtab

dtab-0.1.0/dtab.py

@@ -0,0 +1,163 @@
+"""
+dtab: config files made of tab-separated paths. One line is one path into a tree.
+
+    objects	l1,l2 light                ->  {"objects": {"l1": "light", "l2": "light"}}
+    deltas	l1	position	x 1	y .5     ->  {"deltas": {"l1": {"position": {"x": "1", "y": ".5"}}}}
+    	z -2                              ->  continues the path of the line above
+    	 this entry starts with a space, so it is a comment
+
+Rules:
+  - Tabs indent, and separate the steps of a path (several in a row count as one, for alignment).
+    An entry without a space is a key to step into.
+  - An entry with a space is `key value`, split at the first space. It sets the key and stays put.
+  - An indented line continues the path of the line above it.
+  - Writing a key again replaces it; writing into an object merges. Last line wins.
+  - `a,b` writes the same value under a and under b.
+  - An entry starting with a space is a comment. A trailing tab is an empty key that swallows the lines under it.
+  - Keys are identifiers (str.isidentifier), so trees are EasyDict-friendly. Every value is a string.
+
+Single pass, one stack, O(total characters).
+"""
+
+import json
+import re
+
+__version__ = "0.1.0"  # SEMANTIC BINDING: dtab-version (also package.json "version")
+
+KEY_SEPARATOR = ","  # a,b writes the same value under each key
+KEY_RULE = "keys must be identifiers (letters, digits, underscores, not starting with a digit)"
+_TAB_RUN = re.compile(r"\t+")  # Several tabs in a row are one separator, so columns can be aligned
+
+
+def parse(text):
+    """
+    Pure function. Parses dtab text into nested dicts of strings. Raises ValueError, with the line
+    number, on a key that breaks KEY_RULE.
+
+    Args:
+        text (str): dtab source. Whitespace-only lines are ignored.
+
+    Returns:
+        dict
+
+    Examples:
+        >>> parse('objects\\tl1,l2 light\\ndeltas\\tl1\\tposition\\tx 1\\ty .5\\n\\tz -2')
+        {'objects': {'l1': 'light', 'l2': 'light'}, 'deltas': {'l1': {'position': {'x': '1', 'y': '.5', 'z': '-2'}}}}
+        >>> parse('a\\tb 1\\n\\t comment\\na\\tb 2')
+        {'a': {'b': '2'}}
+        >>> parse('a\\tb 1\\nc.d\\te 2')
+        Traceback (most recent call last):
+        ValueError: dtab line 2: invalid key 'c.d': keys must be identifiers (letters, digits, underscores, not starting with a digit)
+    """
+    root = {}
+    stack = [(-1, [root])]  # (indent, nodes that deeper lines nest into)
+    for line_number, line in enumerate(text.split("\n"), 1):
+        if not line.strip():
+            continue
+        indent = len(line) - len(line.lstrip("\t"))
+        while stack[-1][0] >= indent:
+            stack.pop()
+        nodes = stack[-1][1]
+        for entry in _TAB_RUN.split(line[indent:]):
+            key, space, value = entry.partition(" ")
+            if not key:
+                if not space:
+                    nodes = [{}]  # Empty key (trailing tab): everything under it is discarded
+                continue
+            names = _key_names(key, line_number, allow_commas=True)
+            if space:
+                for node in nodes:
+                    for name in names:
+                        node[name] = value
+            else:
+                nodes = [_child(node, name) for node in nodes for name in names]
+        stack.append((indent, nodes))
+    return root
+
+
+def stringify(tree):
+    """
+    Pure function. Writes nested dicts as dtab, one key per line, tab-indented. Leaves are written
+    with str(). Raises ValueError on a key that breaks KEY_RULE or a leaf containing a tab or newline,
+    which dtab cannot represent. parse(stringify(tree)) == tree when every leaf is a str.
+
+    Args:
+        tree (dict): Nested dicts
+
+    Returns:
+        str
+
+    Examples:
+        >>> stringify({'objects': {'l1': 'light'}, 'deltas': {'l1': {'x': 1, 'name': 'a b'}}}).split('\\n')
+        ['objects', '\\tl1 light', 'deltas', '\\tl1', '\\t\\tx 1', '\\t\\tname a b']
+    """
+    lines = []
+    _stringify_into(tree, 0, lines)
+    return "\n".join(lines)
+
+
+def _key_names(key, line_number, allow_commas):
+    """
+    Pure function (raises ValueError). The identifiers a key stands for: `a,b` is two while parsing,
+    and a stringify key must be a single bare identifier.
+
+    Examples:
+        >>> _key_names('l1,l2', 1, True), _key_names('table_bottom', None, False)
+        (['l1', 'l2'], ['table_bottom'])
+        >>> _key_names('a,b', None, False)
+        Traceback (most recent call last):
+        ValueError: dtab: invalid key 'a,b': keys must be identifiers (letters, digits, underscores, not starting with a digit)
+    """
+    names = key.split(KEY_SEPARATOR) if allow_commas else [key]
+    for name in names:
+        if not name.isidentifier():
+            where = " line %d" % line_number if line_number else ""
+            raise ValueError("dtab%s: invalid key %r: %s" % (where, key, KEY_RULE))
+    return names
+
+
+def _child(node, name):
+    """
+    Command (may mutate node). node[name] as a dict to step into, replacing a string value if there is one.
+
+    Examples:
+        >>> n = {'a': 'leaf'}; _child(n, 'a')['x'] = '1'; _child(n, 'b') is n['b']; n
+        True
+        {'a': {'x': '1'}, 'b': {}}
+    """
+    child = node.get(name)
+    if not isinstance(child, dict):
+        child = node[name] = {}
+    return child
+
+
+def _stringify_into(node, depth, lines):
+    """Command (appends to lines). One dtab line per key of node, indented by depth tabs."""
+    for key, value in node.items():
+        [key] = _key_names(str(key), None, allow_commas=False)
+        indent = "\t" * depth
+        if isinstance(value, dict):
+            lines.append(indent + key)
+            _stringify_into(value, depth + 1, lines)
+        else:
+            value = str(value)
+            if "\t" in value or "\n" in value:
+                raise ValueError("dtab: value of %r contains a tab or newline, which dtab cannot represent: %r" % (key, value))
+            lines.append(indent + key + " " + value)
+
+
+def _cli(path):
+    """Command (reads a file). Parses a dtab file and returns it as a JSON string."""
+    with open(path) as file:
+        return json.dumps(parse(file.read()), indent=4)
+
+
+def _main():
+    """Command. Console entry point: dtab FILE prints the tree as JSON."""
+    import fire
+
+    fire.Fire(_cli)
+
+
+if __name__ == "__main__":
+    _main()

dtab-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dtab"
+description = "Config files made of tab-separated paths. One line is one path into a tree."
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = ["fire"]
+dynamic = ["version"]
+
+[project.scripts]
+dtab = "dtab:_main"
+
+[project.urls]
+Homepage = "https://github.com/RyannDaGreat/dtab"
+
+[tool.setuptools]
+py-modules = ["dtab"]
+
+[tool.setuptools.dynamic]
+version = {attr = "dtab.__version__"}

dtab-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dtab-0.1.0/test/test_dtab.py

@@ -0,0 +1,141 @@
+"""
+Tests for dtab. Run with no arguments from the repo root:
+
+    python test/test_dtab.py
+
+Checks:
+  1. dtab.py doctests.
+  2. dtab.py and dtab.js agree with the ORIGINAL Lab-In-A-Cube djson.js (vendored untouched in
+     test/original/, run under node by test/run_original.js with its raw-string leaf option) on every
+     sample except deviations.dtab.
+  3. dtab.py and dtab.js agree with each other on every sample; the deviating samples match their goldens
+     in test/expected/, which were diffed against the original when written. The differences are exactly:
+     blank lines are ignored, an object can overwrite a leaf, comma keys respect line order (in game_config
+     that is one leaf, deltas.initial.l1.intensity, where the original ignored the later `l1	intensity 1`).
+  4. parse(stringify(parse(text))) == parse(text) for every sample.
+  5. The key rule: bad keys are rejected with a line number in parse and in stringify, and Python's
+     str.isidentifier and the JS Unicode regex agree on a set of probes.
+  6. node test/test_dtab.js.
+  7. Vim: the syntax groups over test/samples/highlight.dtab match test/expected/highlight.txt byte by byte
+     (that sample deliberately contains invalid keys, so it is not parsed), and plugin/dtab.vim sets the
+     filetype when the repo is on 'runtimepath', which is what Vundle and vim-plug do.
+
+Needs: python 3, node, vim.
+"""
+
+import doctest
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+HIGHLIGHT_SAMPLE = ROOT / "test" / "samples" / "highlight.dtab"
+SAMPLES = sorted(path for path in (ROOT / "test" / "samples").glob("*.dtab") if path != HIGHLIGHT_SAMPLE)
+DEVIATING = {"deviations.dtab", "game_config.dtab"}
+IDENTIFIER_PROBES = ["café", "变量", "x²", "_x", "0x", "from", "items", "a-b", "ok_1", "ª", "Ⅻ", "℘", "ℕ", "𝔸", "a.b", "é1", "1é"]
+
+sys.path.insert(0, str(ROOT))
+import dtab  # noqa: E402
+
+
+def run(*command):
+    """Query (runs a subprocess). The command's stdout."""
+    return subprocess.run(command, capture_output=True, text=True, check=True, cwd=ROOT).stdout
+
+
+def raises_value_error(function, *fragments):
+    """Query (calls function). Asserts function() raises ValueError mentioning every fragment."""
+    try:
+        function()
+    except ValueError as error:
+        for fragment in fragments:
+            assert fragment in str(error), "error %r does not mention %r" % (str(error), fragment)
+        return
+    raise AssertionError("expected a ValueError mentioning %r" % (fragments,))
+
+
+def test_doctests():
+    failed, _ = doctest.testmod(dtab)
+    assert failed == 0, "dtab.py doctests failed"
+
+
+def test_readers_agree():
+    for path in SAMPLES:
+        python_tree = dtab.parse(path.read_text())
+        js_tree = json.loads(run("node", "dtab.js", str(path)))
+        assert python_tree == js_tree, "%s: dtab.py and dtab.js disagree" % path.name
+        if path.name in DEVIATING:
+            golden = json.loads((ROOT / "test" / "expected" / (path.stem + ".json")).read_text())
+            assert python_tree == golden, "%s: does not match golden" % path.name
+        else:
+            original = json.loads(run("node", "test/run_original.js", str(path)))
+            assert python_tree == original, "%s: does not match the original djson.js" % path.name
+
+
+def test_round_trips():
+    for path in SAMPLES:
+        once = dtab.parse(path.read_text())
+        assert dtab.parse(dtab.stringify(once)) == once, "%s: did not round trip" % path.name
+
+
+def test_key_rule():
+    for text, fragments in [
+        ("a\tcheckpoint.initial 1", ["line 1", "'checkpoint.initial'"]),
+        ("ok 1\n\t2nd 2", ["line 2", "'2nd'"]),
+        ("a-b 1", ["'a-b'"]),
+        ("~scope\n\tx 1", ["'~scope'"]),
+        ("log\t@ e", ["'@'"]),
+        ("a,b.c\tx 1", ["'a,b.c'"]),
+    ]:
+        raises_value_error(lambda: dtab.parse(text), *fragments)
+    assert dtab.parse("items 1\nfrom 2\n_private 3\ncafé 4") == {"items": "1", "from": "2", "_private": "3", "café": "4"}
+    for tree in [{"a b": "1"}, {"a,b": "1"}, {0: "1"}, {"": "1"}, {"a": "x\ty"}, {"a": "x\ny"}]:
+        raises_value_error(lambda: dtab.stringify(tree), "dtab")
+    python_verdicts = [probe.isidentifier() for probe in IDENTIFIER_PROBES]
+    js_verdicts = json.loads(run(
+        "node", "-e",
+        "const d = require('./dtab.js'); console.log(JSON.stringify(%s.map(p => { try { d.parse(p + ' 1'); return true } catch { return false } })))"
+        % json.dumps(IDENTIFIER_PROBES),
+    ))
+    assert python_verdicts == js_verdicts, "identifier rule differs: %s" % [
+        (probe, py, js) for probe, py, js in zip(IDENTIFIER_PROBES, python_verdicts, js_verdicts) if py != js]
+
+
+def test_js_suite():
+    subprocess.run(["node", "test/test_dtab.js"], check=True, cwd=ROOT)
+
+
+def vim(*commands):
+    """Query (runs vim headless). Runs the -c commands in order in a clean vim and returns nothing."""
+    arguments = ["vim", "-N", "-u", "NONE", "-i", "NONE", "-es"]
+    for command in commands:
+        arguments += ["-c", command]
+    subprocess.run(arguments + ["-c", "qa!"], check=True, cwd=ROOT)
+
+
+def test_vim_highlighting():
+    with tempfile.TemporaryDirectory() as directory:
+        out = Path(directory) / "highlights.txt"
+        vim("syntax on", "source dtab.vim", "edit " + str(HIGHLIGHT_SAMPLE),
+            "source test/dump_highlights.vim", "call DumpHighlights('%s')" % out)
+        got = out.read_text()
+    expected = (ROOT / "test" / "expected" / "highlight.txt").read_text()
+    assert got == expected, "vim highlighting differs:\nexpected:\n%s\ngot:\n%s" % (expected, got)
+
+
+def test_vim_plugin_shim():
+    with tempfile.TemporaryDirectory() as directory:
+        out = Path(directory) / "filetype.txt"
+        vim("set rtp+=" + str(ROOT), "runtime! plugin/*.vim", "edit " + str(SAMPLES[0]),
+            "call writefile([&filetype], '%s')" % out)
+        assert out.read_text().strip() == "dtab", "plugin/dtab.vim did not set the filetype"
+
+
+if __name__ == "__main__":
+    for test in [test_doctests, test_readers_agree, test_round_trips, test_key_rule, test_js_suite,
+                 test_vim_highlighting, test_vim_plugin_shim]:
+        test()
+        print("ok  " + test.__name__)
+    print("All dtab tests passed")