From 22a1cdca4c45e216cf12c593abbdba30b311f081 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kat=20March=C3=A1n?= Date: Fri, 18 Dec 2020 16:53:43 -0800 Subject: [PATCH] clean up readme --- README.md | 199 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 126 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index bd80cc9..e88cc60 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,15 @@ # kdl - Kat's Document Language -kdl is a document language, mostly based on [SDLang](https://sdlang.org), with -xml-like semantics that looks like you're invoking a bunch of CLI commands! +kdl is a document language with xml-like semantics that looks like you're +invoking a bunch of CLI commands! It's meant to be used both as a serialization format and a configuration language, and is relatively light on syntax compared to XML. -This repository is the place for discussing the [specification](SPEC.md). +There's a living [specification](SPEC.md), as well as +[implementations](#implementations). The language is based on +[SDLang](https://sdlang.org), with a number of modifications and +clarifications on its syntax and behavior. ## Design and Discussion @@ -22,56 +25,155 @@ to jump in and give us your 2 cents! 1. Ease of de/serialization 1. Ease of implementation -These are the guiding principles behind the design of KDL, in order of -importance. These principles will hopefully be useful in tie-breaking and -otherwise directing specific decisions when it comes down to it. They are -intentionally vague when it comes to specifics, but more concrete definitions -for each one will be settled on as the project matures. - ## Implementations * Rust: [kdl-rs](https://github.com/kdl-org/kdl-rs) ## Overview -The basic syntax is similar to SDLang: +### Basics + +A KDL node is a node name, followed by zero or more "arguments", and +children. ```kdl -// This is a node with a single string value title "Hello, World" +``` -// Multiple values are supported, too +You can also have multiple values in a single node! + +```kdl bookmarks 12 15 188 1234 +``` -// Nodes can have properties +Nodes can have properties. + +```kdl author "Alex Monad" email="alex@example.com" active=true +``` -// Nodes can be arbitrarily nested +And they can have nested child nodes, too! + +```kdl contents { section "First section" { paragraph "This is the first paragraph" paragraph "This is the second paragraph" } } +``` -// Nodes can be separated into multiple lines -title \ - "Some title" +Nodes without children are terminated by a newline, a semicolon, or the end of +a file stream: -// Comment formats: +```kdl +node1; node2; node3; +``` -// C++ style +### Values + +KDL supports 4 data types: + +* Strings: `"hello world"` +* Numbers: `123.45` +* Booleans: `true` and `false` +* Null: `null` + +#### Strings +It supports two different formats for string input: escaped and raw. + +```kdl +node "this\nhas\tescapes" +other r"C:\Users\zkat\" +``` +Both types of string can be multiline as-is, without a different syntax: + +```kdl +string "my +multiline +value" +``` + +And for raw strings, you can add any number of # after the r and the last " to +disambiguate literal " characters: + +```kdl +other-raw r#"hello"world"# +``` + +#### Numbers + +There's 4 ways to represent numbers in KDL. KDL does not prescribe any +representation for these numbers, and it's entirely up to individual +implementations whether to represent all numbers with a single type, or to +have different representations for different forms. + +KDL has regular decimal-radix numbers, with optional decimal part, as well as +an optional exponent. + +```kdl +num 1.234e-42 +``` + +And using the appropriate prefix, you can also enter hexadecimal, octal, and +binary literals: + +```kdl +my-hex 0xdeadbeef +my-octal 0o755 +my-binary 0b10101101 +``` + +Finally, all numbers can have underscores to help readability: + +```kdl +bignum 1_000_000 +``` + +### Comments + +KDL supports C-style comments, both line-based and multiline. Multiline +comments can be nested. + +```kdl +// C style /* C style multiline */ tag /*foo=true*/ bar=false + +/*/* +hello +*/*/ ``` -But kdl changes a few details: +On top of that, KDL supports `/-` "slashdash" comments, which can be used to +comment out individual nodes, arguments, or children: ```kdl +// This entire node and its children are all commented out. +/-mynode "foo" key=1 { + a + b + c +} + +mynode /-"commented" "not commented" /-key="value" /-{ + a + b +} +``` + +### More Details + +```kdl +// Nodes can be separated into multiple lines +title \ + "Some title" + + // Files must be utf8 encoded! smile "😁" @@ -80,65 +182,16 @@ smile "😁" "!@#$@$%Q#$%~@!40" "1.2.3" "!!!!!"=true // The following is a legal bare identifier: -foo123~!@#$%^&*.:'|<>/?+ "weeee" +foo123~!@#$%^&*.:'|/?+ "weeee" + +// And you can also use unicode! +ノード　お名前＝"☜(ﾟヮﾟ☜)" // kdl specifically allows properties and values to be // interspersed with each other, much like CLI commands. foo bar=true "baz" quux=false 1 2 3 - -// strings can be multiline as-is, without a different syntax. -string "my -multiline -value" - -// raw/unescaped strings use the "r" prefix on string literals and -// otherwise behave the same, including multiline support. -raw r"C:\Users\kdl" - -// You can add any number of # after the r and the last " to -// disambiguate literal " characters. -other-raw r#"hello"world"# - -// There is a single decimal number type, much like JSON's. -num 1.234e-42 - -// Numbers can have underscores to help readability: -bignum 1_000_000 - -// There is additional support for literal hexadecimal, octal, and binary input. -my-hex 0xdeadbeef -my-octal 0o755 -my-binary 0b1010_1101 - -// You can comment out individual nodes with /-. In the case below, everything -// up until the closing `}` becomes commented. -/-mynode "foo" key=1 { - a - b - c -} - -// You can apply /- ("slashdash") comments to individual values, properties, -// or child blocks, too: -mynode /-"commented" "not commented" /-key="value" /-{ - a - b -} - ``` -The following SDLang features are removed altogether: - -* "Anonymous" nodes -* Binary data literals -* Date/time formats -* `on` and `off` booleans -* Backtick strings -* Semicolons -* Namespaces with `:` -* Shell style (`#`) and Lua-style (`--`) comments -* Distinction between 32/64/128-bit numbers. There's just numbers. - ## License Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.