berkus
/
kdl
mirror of https://github.com/kdl-org/kdl.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update README

This commit is contained in:
Kat Marchán 2023-12-13 00:19:37 -08:00
parent a0d5030e3b
commit 54df7f0cab
No known key found for this signature in database
GPG Key ID: AEB529C08A3C7E9E
1 changed files with 41 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
README.md
View File

@ -7,18 +7,18 @@ XML. It looks like this:
```kdl ```kdl
package { package {
name "my-pkg" name my-pkg
version "1.2.3" version "1.2.3"
dependencies { dependencies {
// Nodes can have standalone values as well as // Nodes can have standalone values as well as
// key/value pairs. // key/value pairs.
lodash "^3.2.1" optional=true alias="underscore" lodash "^3.2.1" optional=#true alias=underscore
} }
scripts { scripts {
// "Raw" and multi-line strings are supported. // "Raw" and multi-line strings are supported.
build r#" build #"
echo "foo" echo "foo"
node -c "console.log('hello, world!');" node -c "console.log('hello, world!');"
echo "foo" > some-file.txt echo "foo" > some-file.txt
@ -33,8 +33,8 @@ package {
// "Slashdash" comments operate at the node level, // "Slashdash" comments operate at the node level,
// with just `/-`. // with just `/-`.
/-this-is-commented { /-this-is-commented {
this "entire" "node" { this entire node {
"is" "gone" is gone
} }
} }
} }
@ -51,7 +51,7 @@ Language](SCHEMA-SPEC.md) loosely based on JSON Schema.
The language is based on [SDLang](https://sdlang.org), with a number of The language is based on [SDLang](https://sdlang.org), with a number of
modifications and clarifications on its syntax and behavior. modifications and clarifications on its syntax and behavior.
The current version of the KDL spec is `1.0.0`. The current version of the KDL spec is `2.0.0-draft.1`.
[Play with it in your browser!](https://kdl-play.danini.dev/) [Play with it in your browser!](https://kdl-play.danini.dev/)
@ -116,7 +116,7 @@ bookmarks 12 15 188 1234
Nodes can have properties. Nodes can have properties.
```kdl ```kdl
author "Alex Monad" email="alex@example.com" active=true author "Alex Monad" email=alex@example.com active=#true
``` ```
And they can have nested child nodes, too! And they can have nested child nodes, too!
@ -141,31 +141,38 @@ node1; node2; node3;
KDL supports 4 data types: KDL supports 4 data types:
* Strings: `"hello world"` * Strings: `"hello world"` or just `foo`
* Numbers: `123.45` * Numbers: `123.45`
* Booleans: `true` and `false` * Booleans: `#true` and `#false`
* Null: `null` * Null: `#null`
#### Strings #### Strings
It supports two different formats for string input: escaped and raw.
It supports three different formats for string input: identifiers, quoted, and raw.
```kdl ```kdl
node "this\nhas\tescapes" node1 this-is-a-string
other r"C:\Users\zkat\" node2 "this\nhas\tescapes"
``` node3 #"C:\Users\zkat\raw\string"#
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 Both types of quoted string can be multiline as-is, without a different
disambiguate literal " characters: syntax. Additionally, these multi-line strings will be "dedented" according to
the indentation of the least-indented line:
```kdl ```kdl
other-raw r#"hello"world"# string "
my
multiline
value
"
```
Raw strings, you can add any number of `#`s before and after the opening and
closing `#` to disambiguate literal `#"` sequences:
```kdl
other-raw ##"hello"#world"##
``` ```
#### Numbers #### Numbers
@ -209,7 +216,7 @@ comments can be nested.
C style multiline C style multiline
*/ */
tag /*foo=true*/ bar=false tag /*foo=#true*/ bar=#false
/*/* /*/*
hello hello
@ -221,13 +228,13 @@ comment out individual nodes, arguments, or children:
```kdl ```kdl
// This entire node and its children are all commented out. // This entire node and its children are all commented out.
/-mynode "foo" key=1 { /-mynode foo key=1 {
a a
b b
c c
} }
mynode /-"commented" "not commented" /-key="value" /-{ mynode /-commented "not commented" /-key=value /-{
a a
b b
} }
@ -242,8 +249,8 @@ specific meanings.
```kdl ```kdl
numbers (u8)10 (i32)20 myfloat=(f32)1.5 { numbers (u8)10 (i32)20 myfloat=(f32)1.5 {
strings (uuid)"123e4567-e89b-12d3-a456-426614174000" (date)"2021-02-03" filter=(regex)r"$\d+" strings (uuid)123e4567-e89b-12d3-a456-426614174000 (date)"2021-02-03" filter=(regex)#"$\d+"#
(author)person name="Alex" (author)person name=Alex
} }
``` ```
@ -256,21 +263,21 @@ title \
// Files must be utf8 encoded! // Files must be utf8 encoded!
smile "😁" smile 😁
// Instead of anonymous nodes, nodes and properties can be wrapped // Instead of anonymous nodes, nodes and properties can be wrapped
// in "" for arbitrary node names. // in "" for arbitrary node names.
"!@#$@$%Q#$%~@!40" "1.2.3" "!!!!!"=true "!@#$@$%\\/()[]Q#$%~@!40" "1.2.3" "#null"=#true
// The following is a legal bare identifier: // Identifiers are very flexible. The following is a legal bare identifier:
foo123~!@#$%^&*.:'|?+ "weeee" <@foo123~!$%^&*.:'|?+>
// And you can also use unicode! // And you can also use unicode!
ノード　お名前="☜(ﾟヮﾟ☜)" ノード　お名前=☜(ﾟヮﾟ☜)
// kdl specifically allows properties and values to be // kdl specifically allows properties and values to be
// interspersed with each other, much like CLI commands. // interspersed with each other, much like CLI commands.
foo bar=true "baz" quux=false 1 2 3 foo bar=#true baz quux=#false 1 2 3
``` ```
## Design Principles ## Design Principles