Merge branch 'develop' into unstable

# Conflicts:
#	README.md

.editorconfig

@@ -4,6 +4,6 @@ root = true
 end_of_line = lf
 indent_style = tab
 
-[*.{md,yml}]
+[*.{md,yml,yaml}]
 indent_style = space
 indent_size = 2

.github/ISSUE_TEMPLATE/bug_report.md

@@ -35,7 +35,7 @@ If applicable, add screenshots to help explain your problem.
 **please complete the following information:**
 
 - `rustc --version`: [e.g. 1.53.0]
-- Crate version (if applicable): [e.g. 0.0.9]
+- Crate version (if applicable): [e.g. 0.0.10]
 
 **Additional context**
 Add any other context about the problem here.

.gitignore

@@ -1 +1,2 @@
 /target
+docs/_build

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - epub
+  - pdf
+  - htmlzip
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.8
+  install:
+  - requirements: docs/requirements.txt

.vscode/settings.json

@@ -8,8 +8,10 @@
 		"FIXME",
 		"TODO",
 		"XXX",
-		"todo!"
+		"todo!",
+		"TK"
 	],
 	"todo-tree.regex.regex": "(($TAGS)|^\\s*- \\[ \\])",
-	"rust-analyzer.cargo.allFeatures": true
+	"rust-analyzer.cargo.allFeatures": true,
+	"restructuredtext.confPath": "${workspaceFolder}\\docs"
 }

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 <!-- markdownlint-disable no-trailing-punctuation -->
 
+## 0.0.10
+
+2021-07-29
+
+* **Breaking:**
+  * `Decoded` is now `DataLiteral` and so on.
+  * Renamed `Float` variants to `Decimal`
+    > as these can very much be parsed as arbitrary-precision numbers, depending on the implementation.
+  * Changed number literals to reject additional leading zeroes
+    > as these could be mistaken for octal input.
+  * Added additional lexer tokens `InvalidZeroPrefixedDecimal` and `InvalidZeroPrefixedInteger`,
+    > which allow formatting and better error diagnostics involving these now-invalid tokens.
+
+* Features:
+  * `smartstring::validate` is now re-exported as `validate`.
+    > You should call this to ensure the memory layout is correct!
+  * Added diagnostics for (always invalid) zero-prefixed decimals and integers.
+
 ## 0.0.9
 
 2021-07-15

Cargo.toml

@@ -1,13 +1,13 @@
 [package]
 name = "taml"
-version = "0.0.9"
+version = "0.0.10"
 authors = ["Tamme Schichler <tamme@schichler.dev>"]
 edition = "2018"
 description = "A kind-to-humans configuration language."
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/Tamschi/taml"
-homepage = "https://github.com/Tamschi/taml/tree/v0.0.9"
-documentation = "https://docs.rs/taml/0.0.9"
+homepage = "https://github.com/Tamschi/taml/tree/v0.0.10"
+documentation = "https://docs.rs/taml/0.0.10"
 keywords = ["structured", "humane", "configuration", "parser"]
 categories = ["parser-implementations"]
 readme = "README.md"
@@ -35,17 +35,17 @@ enum_properties = "^0.3.0"
 gnaw = "0.0.2"
 indexmap = "^1.6.2" # public #TODO: Preserving the order should be an optional feature.
 lazy-transform-str = "0.0.6"
-logos = "0.12.0" # public (through trait implementation on Token. Is there a way to not publish this?)
-smartstring = "0.2.7" # public
-try_match = "0.2.2"
+logos = "^0.12.0" # public (through trait implementation on Token. Is there a way to not publish this?)
+smartstring = "^0.2.9" # public
+try_match = "^0.2.2"
 
 # Minimum version working with try_match starting with Rust 1.47.0.
 # SEE: https://github.com/rust-lang/rust/issues/77789, https://github.com/dtolnay/syn/issues/906, https://github.com/dtolnay/syn/releases/tag/1.0.44
-syn = { version = "1.0.44", default-features = false }
+syn = { version = "^1.0.44", default-features = false }
 
 [dev-dependencies]
-cargo-husky = "1.5.0"
-doc-comment = "0.3.3"
-git_info = "0.1.2"
-version-sync = "0.9.1"
-wasm-bindgen-test = "0.3.24"
+cargo-husky = "^1.5.0"
+doc-comment = "^0.3.3"
+git_info = "^0.1.2"
+version-sync = "^0.9.1"
+wasm-bindgen-test = "^0.3.24"

README.md

@@ -6,7 +6,7 @@
 
 ![Rust 1.53](https://img.shields.io/static/v1?logo=Rust&label=&message=1.53&color=grey)
 [![CI](https://github.com/Tamschi/taml/workflows/CI/badge.svg?branch=unstable)](https://github.com/Tamschi/taml/actions?query=workflow%3ACI+branch%3Aunstable)
-![Crates.io - License](https://img.shields.io/crates/l/taml/0.0.9)
+![Crates.io - License](https://img.shields.io/crates/l/taml/0.0.10)
 
 [![GitHub](https://img.shields.io/static/v1?logo=GitHub&label=&message=%20&color=grey)](https://github.com/Tamschi/taml)
 [![open issues](https://img.shields.io/github/issues-raw/Tamschi/taml)](https://github.com/Tamschi/taml/issues)
@@ -29,6 +29,8 @@ That said, I believe that for human-written files, TAML offers a great balance b
 A command line validator and formatter is available in the [`taml-cli`] crate.  
 Serde-intergration can be found in [`serde_taml`].
 
+See <https://taml.schichler.dev> for documentation on the format itself.
+
 [`taml-cli`]: https://github.com/Tamschi/taml-cli
 [`serde_taml`]: https://github.com/Tamschi/serde_taml/
 
@@ -65,80 +67,6 @@ dual licensed as above, without any additional terms or conditions.
 
 ## [Changelog](CHANGELOG.md)
 
-## The grammar
-
-TAML (always UTF-8 where applicable) can represent much of the [Serde data model](https://serde.rs/data-model.html) verbatim and is self-describing, as follows:
-
-- [`bool`](https://doc.rust-lang.org/stable/std/primitive.bool.html) is represented as enum with the unit values `true` and `false`,
-- all integers are base 10 with optional preceding `-`.
-  - You can (try to) deserialize them as any primitive Rust integer.
-  - When deserialized as any, the result is the smallest fitting unsigned or signed integer type.
-- all floats are base 10 with infix `.` (meaning at least one leading and trailing digit is necessary, each).
-  - Deserializing as any results in an f64.
-- [`char`](https://doc.rust-lang.org/stable/std/primitive.char.html) matches Rust: `'🦀'`
-- **byte array**s are unsupported,
-- **option**s are flattened.
-  - This means only the [`Some(_)`](https://doc.rust-lang.org/stable/std/option/enum.Option.html#variant.Some)-variant can be present in **seq**s.
-  - Use `#[serde(default)]` to parse missing **struct** keys as [`None`](https://doc.rust-lang.org/stable/std/option/enum.Option.html#variant.None).
-- [`unit`](https://doc.rust-lang.org/stable/std/primitive.unit.html) and **unit struct**s are written as **empty seq**.
-- a **unit variant** is written as the variant key: `Yes`
-- **newtype struct**s are flattened,
-- **newtype variant**s are written as key followed by a **seq**: `No("impossible!")`
-- **seq**:
-  - either inline (*in a single line*) similar to Rust tuples:
-
-    ```taml
-    ((a, b, c), (d, e)) // seqs can be directly nested this way, but then cannot contain structures.
-    ```
-
-  - in heading paths:
-
-    ```taml
-    # path.with.a.[list].inside
-    ```
-
-  - or as tabular section:
-
-    ```taml
-    # path.to.[[list]]
-    1
-    2
-    3
-    4
-    "five"
-
-    # [[vectors].{a, b, c, d}]
-    1.0, 2.0, 3.0, 4.0
-    1.1, 2.1, 3.1, 4.1
-    2.1, 2.2, 3.2, 4.2
-    3.1, 3.2, 3.3, 4.3
-    4.1, 4.2, 4.3, 4.4
-    ```
-
-- **tuple** and **tuple_struct**: as **seq**, but with length validation
-- **tuple_variant**: as key directly followed by an inline **seq**, with length validation
-- **map**s, **struct**s and **struct_variant**s are written as sections containing key-value-pairs (one per line), possibly with subsections.
-  - Example:
-
-    ```taml
-    # path.to.structure
-    key: Value
-    `another key`: 1.0
-
-    ## structured_variant:VariantKey
-    `nested\`field`: "nested`field"
-    ```
-
-  - Unlike most Serde formats, **TAML by default errors out on unexpected *struct* or *struct_variant* fields!**
-
-    However, you can collect them in a **map** by adding a field with the name `"taml::extra_fields"`. Use [`#[serde(rename = "taml::extra_fields")]`](https://serde.rs/field-attrs.html#rename) or equivalent.
-
-<!--
-If you intend to write a custom parser for this format, please validate it against the sample files in `tests/samples`. (TODO: Create those.)
--->
-
-TODO: Describe headings.
-
 ## Versioning
 
 `taml` strictly follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) with the following exceptions:

SECURITY.md

@@ -2,11 +2,11 @@
 
 ## Supported Versions
 
-| Version | Supported          | ***Initial*** Reason for Removal                                                                             |
-| ------- | ------------------ | ------------------------------------------------------------------------------------------------------------ |
-| 0.0.8-9 | :white_check_mark: |                                                                                                              |
-| 0.0.7   | :shipit:           | Detailed spans for "decoded" values (`<…:…>`) use local positions in this version, which wasn't intentional. |
-| 0.0.1-6 | :white_check_mark: |                                                                                                              |
+| Version  | Supported          | ***Initial*** Reason for Removal                                                                             |
+| -------- | ------------------ | ------------------------------------------------------------------------------------------------------------ |
+| 0.0.8-10 | :white_check_mark: |                                                                                                              |
+| 0.0.7    | :shipit:           | Detailed spans for "decoded" values (`<…:…>`) use local positions in this version, which wasn't intentional. |
+| 0.0.1-6  | :white_check_mark: |                                                                                                              |
 
 Faulty versions are [yanked](https://doc.rust-lang.org/cargo/commands/cargo-yank.html), where possible after a Semver-compatible update is made available, and added to the table above as unsupported.  
 They are also marked with an additional `v….….…-yanked` tag in Git to make them easily recognisable, but original release tags are not removed.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,56 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+import sphinx_rtd_theme
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'TAML'
+copyright = '2021, Tamme Schichler'
+author = 'Tamme Schichler'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+pygments_style = 'sphinx'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+html_js_files = ['js/expand_tabs.js']

docs/diagnostics.rst

@@ -0,0 +1,2 @@
+TAML Diagnostics
+================

docs/formatting.rst

@@ -0,0 +1,5 @@
+Formatting TAML
+===============
+
+As a general rule, TAML code in this documentation follows the recommended formatting rules and would stay unchanged if ``taml fmt`` was used on it.
+Exceptions are explicitly noted.