@@ 10,10 10,11 @@ ABOUT
- 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
https://git.sr.ht/~cricket/ckt-kak - ckt syntax highlighting for kakoune
@@ 25,5 26,9 @@ LICENSE
read the LICENSE file for more information
+ send an email with your patch to ~email@example.com
+ feel free to do this if you've implemented ckt and want it listed above too!
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
-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
-# 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 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':
-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
-# 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
-# This is fine. This should be interpreted the same as "this is valid" = "value"
-this is invalid;
-# 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=
-this is not also valid =;
-# And of course:
-this too is valid
-# 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! \\\
+By C. C. Piapiac <firstname.lastname@example.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
+ 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/>
+ 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"
+ 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 (,)
+ 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.
+ 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 ]
+ 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.
+ 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"