~cricket/ckt

ref: d1e4fca31c02ed254fd2b6847a1013bfcf27f810 ckt/SPEC -rw-r--r-- 4.5 KiB
d1e4fca3c piapiac new specification a month ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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"
    ]
    ---