From 41aa674e57e70d0a18174f5799e087351c200a2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kat=20March=C3=A1n?= Date: Sat, 19 Dec 2020 20:50:28 -0800 Subject: [PATCH] update content a bit --- src/_includes/partials/description.md | 10 +- .../partials/design-and-discussion.md | 7 +- src/_includes/partials/design-principles.md | 6 - src/_includes/partials/overview.md | 183 ++++++++++++------ src/index.md | 4 +- 5 files changed, 132 insertions(+), 78 deletions(-) diff --git a/src/_includes/partials/description.md b/src/_includes/partials/description.md index 22f2f5a..233b5f5 100644 --- a/src/_includes/partials/description.md +++ b/src/_includes/partials/description.md @@ -1,10 +1,14 @@
-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. +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. +
diff --git a/src/_includes/partials/design-and-discussion.md b/src/_includes/partials/design-and-discussion.md index 4d6d253..516b083 100644 --- a/src/_includes/partials/design-and-discussion.md +++ b/src/_includes/partials/design-and-discussion.md @@ -2,9 +2,8 @@ ## Design and Discussion -kdl is still extremely new, and discussion about the format should happen -over on the -[discussions](https://github.com/kdoclang/kdl/discussions) page -in the Github repo. Feel free to jump in and give us your 2 cents! +KDL is still extremely new, and discussion about the format should happen over +on the [discussions](https://github.com/kdl-org/kdl/discussions) page in the +Github repo. Feel free to jump in and give us your 2 cents! diff --git a/src/_includes/partials/design-principles.md b/src/_includes/partials/design-principles.md index 7e730b5..087b104 100644 --- a/src/_includes/partials/design-principles.md +++ b/src/_includes/partials/design-principles.md @@ -8,10 +8,4 @@ 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. - diff --git a/src/_includes/partials/overview.md b/src/_includes/partials/overview.md index 33674a0..eb7e155 100644 --- a/src/_includes/partials/overview.md +++ b/src/_includes/partials/overview.md @@ -2,44 +2,149 @@ ## 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 "😁" @@ -48,62 +153,14 @@ 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. - diff --git a/src/index.md b/src/index.md index 7402818..045fbe2 100644 --- a/src/index.md +++ b/src/index.md @@ -1,10 +1,10 @@ --- layout: base.html -title: kdl - Kat's Document Language +title: KDL - KDL Document Language ---
-

kdl - Kat's Document Language

+

KDL - KDL Document Language

{% include partials/description.md %}