~cricket/ckt

d1e4fca31c02ed254fd2b6847a1013bfcf27f810 — c piapiac a month ago 69b215d
new specification

* a more readable specification (see SPEC)
* includes some updates to the README (cktjs, CONTRIBUTING)
2 files changed, 151 insertions(+), 131 deletions(-)

M README
M SPEC
M README => README +7 -2
@@ 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

M SPEC => SPEC +144 -129
@@ 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"
    ]
    ---