From 21008f9f02ef1a093060771ba937525ae7ffd5fa Mon Sep 17 00:00:00 2001 From: Scott Date: Fri, 18 Dec 2020 16:57:25 -0500 Subject: [PATCH] Add design-principles and overview sections --- .../partials/design-and-discussion.html | 2 +- src/_includes/partials/design-principles.html | 18 +++ src/_includes/partials/overview.html | 113 ++++++++++++++++++ src/index.html | 2 + 4 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 src/_includes/partials/design-principles.html create mode 100644 src/_includes/partials/overview.html diff --git a/src/_includes/partials/design-and-discussion.html b/src/_includes/partials/design-and-discussion.html index 8b4c3c6..e653617 100644 --- a/src/_includes/partials/design-and-discussion.html +++ b/src/_includes/partials/design-and-discussion.html @@ -1,5 +1,5 @@
-

Design and discussion

+

Design and Discussion

kdl is still extremely new, and discussion about the format should happen over on the diff --git a/src/_includes/partials/design-principles.html b/src/_includes/partials/design-principles.html new file mode 100644 index 0000000..9319dea --- /dev/null +++ b/src/_includes/partials/design-principles.html @@ -0,0 +1,18 @@ +

+

Design Principles

+
    +
  1. Maintainability
    2. +
  2. Flexibility
    3. +
  3. Cognitive simplicity and Learnability
    4. +
  4. Ease of de/serialization
    5. +
  5. Ease of implementation
    6. +
+ +

+ 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.html b/src/_includes/partials/overview.html new file mode 100644 index 0000000..9ad4f5c --- /dev/null +++ b/src/_includes/partials/overview.html @@ -0,0 +1,113 @@ +
+

Overview

+ +

The basic syntax is similar to SDLang:

+ + 
+    
+// This is a node with a single string value
+title "Hello, World"
+
+// Multiple values are supported, too
+bookmarks 12 15 188 1234
+
+// Nodes can have properties
+author "Alex Monad" email="alex@example.com" active=true
+
+// Nodes can be arbitrarily nested
+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"
+
+// Comment formats:
+
+// C++ style
+
+/*
+C style multiline
+*/
+
+tag /*foo=true*/ bar=false
+    
+
+ +

But kdl changes a few details:

+ + 
+    
+// Files must be utf8 encoded!
+smile "😁"
+
+// Instead of anonymous nodes, nodes and properties can be wrapped
+// in "" for arbitrary node names.
+"!@#$@$%Q#$%~@!40" "1.2.3" "!!!!!"=true
+
+// The following is a legal bare identifier:
+foo123~!@#$%^&*.:'|<>/?+ "weeee"
+
+// 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.html b/src/index.html index 506ef16..8d9f6d5 100644 --- a/src/index.html +++ b/src/index.html @@ -10,3 +10,5 @@ title: kdl - Kat's Document Language {% include partials/description.html %} {% include partials/design-and-discussion.html %} +{% include partials/design-principles.html %} +{% include partials/overview.html %}