@@ 10,10 10,11 @@ ABOUT
TOOLS
IMPLEMENTATIONS
- https://git.sr.ht/~cricket/ockt - zig ckt parser
+ https://git.sr.ht/~cricket/ockt - ocaml library for ckt
https://git.sr.ht/~cricket/zckt - zig ckt parser
https://gitlab.com/mocchapi/pyckt - python3 ckt parser
-
+ https://github.com/luavixen/cktjs - JSON-style CKT parsing/stringification
+
SYNTAX HIGHLIGHTING
https://git.sr.ht/~cricket/ckt-kak - ckt syntax highlighting for kakoune
@@ 25,5 26,9 @@ LICENSE
read the LICENSE file for more information
+CONTRIBUTING
+ send an email with your patch to ~cricket/ckt@lists.sr.ht
+ feel free to do this if you've implemented ckt and want it listed above too!
+
AUTHORS
do `git shortlog -sne` to show a list of all contributors
@@ 1,129 1,144 @@
-# a totally incomplete / informal specification of ckt :P
-# version 0.0.0
-
-# DEFINITIONS:
-newline = \n (0x0A)
-whitespace = [ space (0x20), \t (0x09), \r (0x0D) ]
-escape sequences = [
- \n = newline (0x0A)
- \r = carriage return (0x0D)
- \t = tab (0x09)
- \" = double quote (0x22)
- \\ = backslash (0x5C)
- \xNN = hexadecimal 8-bit value
-]
-
-# COMMENTS
-# The hash symbol (#) starts a comment, and the comment goes all the way to the end of a line.
-# They can be at the start of a line, or anywhere in the line.
-
-# Every key is a string, and every value is either a string or a table.
-
-# TABLES
-# Tables are surrounded by [ ]
-# The top level is also a table!
-
-# Key-Value pairs are 'record style initializations':
-record style initialization = this is the record style initialization
-initialization with table = [ key = value ]
-
-# Surrounding whitespace is trimmed; so this is equal
-"initialization with table" = [ "key" = "value" ]
-
-# Duplicate keys are overwritten!
-x = 13
-x = 16
-# x now equals 16
-
-# Unspecified keys in record-style initializations are invalid;
-# = value
-# However, empty keys are.
-"" = value
-
-# Bare values are 'list style initializations':
-value1, value2
-this has a list style table = [value 1, value 2]
-
-# Ckt makes no ditinction between tables and lists.
-# The keys of list style initialization is the previous list style key + 1,
-# starting at 0 and counting up in decimal.
-equivelant to list style table = [
- 0 = value 1,
- 1 = value 2
-]
-
-# You can even mix and match record style and list style initializations.
-polyline = [
- color = blue; thickness = 2; npionts = 4
- [ x = 0; y = 0 ]
- [ x = -10; y = 0 ]
- [ x = -10; y = 1 ]
- [ x = 0; y = 1 ]
-]
-
-# In a table, newliens, commas, or semicolons seperate items, and they are mostly interchangable
-seperated = [
- seperated, by, commas; and; by; semicolons
- and
- by
- newlines
-]
-
-# With only one difference:
-# The parser should go through newlines and whitespace until it finds a non-neline, non-whitespace character.
-# If the character is '=' then its a k/v pair; EG
-this is valid
-= value
-
-# This is fine. This should be interpreted the same as "this is valid" = "value"
-# However;
-this is invalid;
-= value
-# This is not valid. It will interpret "this is invalid" and "= value" as two items of a table using list initialization syntax,
-# and will error, as '=' is not allowed in unquoted strings.
-
-# Same goes here:
-this is also valid=
-value
-
-this is not also valid =;
-value
-
-# And of course:
-this too is valid
-=
-value
-
-# STRINGS
-# Strings can be unquoted, quoted, or multiline
-
-# Unquoted strings are not escaped (what you see is what you get)
-this is a bare unquoted string
-this string includes \n which is not interpreted as a newline
-
-# Quoted strings are surrounded by ", and are escaped (see escape sequences under DEFINITIONS)
-"this is a quoted string"
-
-# This are useful if you need a string that includes any of [ ] = , ; | # "
-tag = "#Epic"
-
-# Or if you need escaped characters
-multiple lines quoted = "this string\nspans\nmultiple lines"
-
-# Multiline strings start with a | on every line, and are mostly not escaped.
-multiline string =
- |This string spans multiple lines.
- |Isn't it so cool?
-
-# Aside from escape hatches. A \ before a newline in a multiline string will cause the next line to be on the same.
-# A \ before the EOF should be interpreted as nothing.
-singleline multiline string =
- |This string only spans \
- |a single line.
-
-singleline unquoted string = This string only spans a single line.
-
-# Escape hatches themselves can be escaped.
-escaped escape hatches =
- |This line ends in a single backslash. \\
- |This line ends with two! \\\
+CKT v0.1.0
+By C. C. Piapiac <_c@piapiac.org>
+
+Table of Contents:
+ 1. INTRODUCTION
+ 1.1. PRIOR ART
+ 1.2. EXAMPLE
+
+ 2. SPECIFICATIONS
+ 2.1. COMMENTS
+ 2.2. KEY/VALUE PAIRS
+ 2.3. STRINGS
+ 2.4. TABLES
+
+1. INTRODUCTION
+ CKT is a data format specifically for user-facing configs.
+ CKT aims to be extremely easy to parse (both for humans and computers), and is meant to
+ be obvious and typeable for humans as well.
+
+1.1. PRIOR ART
+ TOML <https://toml.org/>
+ ZZZ <https://github.com/gruebite/zzz/>
+ LUA <https://www.lua.org/>
+
+1.2. EXAMPLE
+ Here is an example based off the example for ini files on wikipedia:
+ ---
+ # Last modified 1 April 2021 by John Doe
+ authors = [ John Doe, Cricket Piapiac ]
+
+ database = [
+ # Use IP address in case network name resolution isn't working
+ server = 192.0.2.62
+ port = 143
+ files = "payroll.dat"
+ ]
+ ---
+
+2. SPECIFICATION
+ CKT documents are UTF-8 encoded text files.
+ "Whitespace" is either a space (0x20), tab character (0x09), or \r (0x0D)
+ "Newline" is a Unix LF (0x0A)
+ "Separators" are Newlines, Semicolons (;) or Commas (,)
+
+2.1. COMMENTS
+ A comment starts with a hash symbol (#) and extends to the end of a line
+ (except when inside a quoted or multiline string).
+ ---
+ # This document only contains a single commment.
+ ---
+
+2.2. KEYS, VALUES
+ Keys and values pairs make up the bulk of a ckt file. They are separated by separators.
+ Keys must be a string, and values must be a string or table.
+
+ There are two way to declare key/value pairs; record style and list style.
+
+ In record style, keys are on the left of an equals sign (=) and values are on the right. There can
+ be separators between the equals sign and the value, but not between the key and equals sign.
+ ---
+ key = value
+ another =
+ here is the value
+ ---
+
+ In list style, there is just a bare value, separated by a separator.
+ ---
+ value1
+ value2
+ ---
+ The keys of the value is the key of the previous list style value plus 1, with the first bare style
+ value's being key being equal to 0.
+ ---
+ # Equivalent to the above
+ 0 = value1
+ 1 = value2
+ ---
+
+ You can mix and match and list and record style initializers.
+ ---
+ polyline = [
+ colour = blue; thickness = 2; npoints = 4
+ [ x = 0; y = 0 ]
+ [ x = -10; y = 0 ]
+ [ x = -10; y = 1 ]
+ [ x = 0; y = 1 ]
+ ]
+ ---
+
+2.3. STRINGS
+ Strings can be unquoted, quoted, or multiline.
+
+ Unquoted strings don't have any quotations surrounding them, and the whitespace around them is
+ trimmed. They cannot contain any special characters (Separators, equal signs (=), brackets ([, ]) ]
+ ---
+ key = this is an unquoted string
+ ---
+
+ Quoted strings have un-escaped quotation marks surrounding them. They can contain any characters
+ aside from newlines.
+ ---
+ "key" = "this is a quoted string"
+ ---
+ Quoted strings can also contain nice espace sequences:
+ ----------------------------------------------------------
+ \n | newline | (0x0A)
+ \r | carriage return | (0x0D)
+ \t | tab | (0x09)
+ \" | double quote | (0x22)
+ \xNN | hexadecimal 8 bit character | (0xNN)
+ \uNNNN | hexadecimal 16 bit unicode character | (0xNNNN)
+ ----------------------------------------------------------
+ Such as..
+ ---
+ newlines = "this is one line\nthis is another"
+ quotes = "this string has \"quotation marks\" in it!"
+ ---
+
+ Multiline strings have start with a pipe symbol (|) and go till the end of a line. The newline at
+ the end of the line is included in the string, except for on the final line.
+
+ A backslash (\) before the end of a line in a multiline string will cause the content on the next
+ line to be on the same line.
+ ---
+ multiline string =
+ |this string has multiple lines!
+ |it also has "quotation marks" in it.
+ |it can include # any [ characters ].
+
+ other multiline string =
+ |this string is \
+ |only on one line.
+ ---
+
+2.4. TABLES
+ Tables are surrounded by [ and ], and contain key/value pairs.
+ CKT files are also tables, surrounded by the start and end of the file rather than a [ and ].
+
+ ---
+ table = [
+ cat = "meow"
+ dog = "woof"
+ ]
+ ---