From af95c072b4ebc55a96f249024b8dd90085e3c993 Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Wed, 24 Jul 2019 23:51:37 -0500 Subject: [PATCH] Update: add basic featureless settings specifications documentation This was originally defined online, but I had lost the data at some point. The internet archive didn't cache the page and the data lost happened during the time I was changing the website. The specifications were simple enough to be rewritten, but I have done so in haste. Some of the specifications will be documented at a later date. I do not remember what advanced reverse mapping was intended to be, so I replaced it with the custom json-like specification. The goal of the json-like specification is to write it such that it is still valid json (minus any comments). It is currently added to preserve the idea but there are no immediate plans to implement this specification. --- specifications/fss-0000.txt | 36 +++++++++++++++++++++++++ specifications/fss-0001.txt | 38 ++++++++++++++++++++++++++ specifications/fss-0002.txt | 45 +++++++++++++++++++++++++++++++ specifications/fss-0003.txt | 48 +++++++++++++++++++++++++++++++++ specifications/fss-0004.txt | 5 ++++ specifications/fss-0005.txt | 5 ++++ specifications/fss-0006.txt | 5 ++++ specifications/fss-0007.txt | 5 ++++ specifications/fss-0008.txt | 5 ++++ specifications/fss-0009.txt | 5 ++++ specifications/fss-000A.txt | 5 ++++ specifications/fss-000B.txt | 7 +++++ specifications/fss-000C.txt | 3 +++ specifications/fss.txt | 65 +++++++++++++++++++++++++++++++++++++++++++++ 14 files changed, 277 insertions(+) create mode 100644 specifications/fss-0000.txt create mode 100644 specifications/fss-0001.txt create mode 100644 specifications/fss-0002.txt create mode 100644 specifications/fss-0003.txt create mode 100644 specifications/fss-0004.txt create mode 100644 specifications/fss-0005.txt create mode 100644 specifications/fss-0006.txt create mode 100644 specifications/fss-0007.txt create mode 100644 specifications/fss-0008.txt create mode 100644 specifications/fss-0009.txt create mode 100644 specifications/fss-000A.txt create mode 100644 specifications/fss-000B.txt create mode 100644 specifications/fss-000C.txt create mode 100644 specifications/fss.txt diff --git a/specifications/fss-0000.txt b/specifications/fss-0000.txt new file mode 100644 index 0000000..9a8d126 --- /dev/null +++ b/specifications/fss-0000.txt @@ -0,0 +1,36 @@ +Featureless Settings Specification: 0000 - Basic + +Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object. +Whitespace separates an Object from the Content. +An Object may be followed by a newline, in which case means that the Object has no Content. + +Content exists on the same line as the Object. +Content consists of everything following the first non-whitespace character until the newline. +Content includes trailing whitespace before newline is reached. +Content does not include the leading whitespace. +No delimits are supported in the content. + +Key: + \s = whitespace, except newline. + \b = either whitespace or printable, except newline. + \q = non-whitespace or quoteded whitespace, no whitespace outside of quotes. + \n = newline. + * = 0 or more occurrences. + + = one or more occurrences. + +Structure: + \s*\q+\s+\b*\n + +Example: + # fss-0000 + # valid comments are ignored. + "The Object" Content until newline. + Second object set. + +Object would be: + 1) The Object + 2) Second + +Content would be: + 1.1) Content until newline. + 2.1) object set. diff --git a/specifications/fss-0001.txt b/specifications/fss-0001.txt new file mode 100644 index 0000000..5218ae8 --- /dev/null +++ b/specifications/fss-0001.txt @@ -0,0 +1,38 @@ +Featureless Settings Specification: 0001 - Extended + +Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object. +Whitespace separates an Object from the Content. +An Object may be followed by a newline, in which case means that the Object has no Content. + +Content exists on the same line as the Object. +Content of whitespace separated sets until the newline. +Any number of sets may exist in the Content until the newline is reached. + +Key: + \s = whitespace, except newline. + \b = either whitespace or printable, except newline. + \q = non-whitespace or quoteded whitespace, no whitespace outside of quotes. + \n = newline. + * = 0 or more occurrences. + + = one or more occurrences. + ()* = grouping that repeats 0 or more times. + +Structure: + \s*\q+\s+(\s*\q+)*\s*\n + +Example: + # fss-0001 + # valid comments are ignored. + "The Object" Content "content 2" content_3. + Second object set. + +Objects would be: + 1) The Object + 2) Second + +Contents would be: + 1.1) Content + 1.2) content 2 + 1.3) content_3. + 2.1) object + 2.2) set. diff --git a/specifications/fss-0002.txt b/specifications/fss-0002.txt new file mode 100644 index 0000000..b56a84a --- /dev/null +++ b/specifications/fss-0002.txt @@ -0,0 +1,45 @@ +Featureless Settings Specification: 0002 - Basic List + +Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object. +A colon followed by any whitespace until a newline terminates a valid Object. +Non-whitespace may not follow the colon of a valid Object. + +Content exists on every line following a valid object until the end of file (or string) or until the next valid Object is found. +Any content that could be interpreted as a valid Object must have the colon delimited. + +There is no single-quote or double-quote delimitation in this specification. +Only the colon that would result in a valid Object can be delimited. + +Key: + \s = whitespace, except newline. + \o = any printable character, except unescaped ':'. + \l = any printable character or whitespace, except unescaped ':'. + \c = either whitespace or printable, including newline, that not interpretable as an Object. + \n = newline. + * = 0 or more occurrences. + +Structure: + \s*\o\l*:\s*\n\c*\n* + +Example: + # fss-0002 + # valid comments are ignored. + "The Object": + Does not need to be quoted. + This: does not need to be delimited. + This Does\: + Second: + Continues until EOS/EOF. + All whitespace, including newline (and leading whitespace) is part of content. + # Valid comments are still ignored. + +Objects would be: + 1) "The Object" + 2) Second + +Contents would be: + 1.1) Does not need to be quoted. + This: does not need to be delimited. + This Does: + 2.1) Continues until EOS/EOF. + All whitespace, including newline (and leading whitespace) is part of content. diff --git a/specifications/fss-0003.txt b/specifications/fss-0003.txt new file mode 100644 index 0000000..05621fc --- /dev/null +++ b/specifications/fss-0003.txt @@ -0,0 +1,48 @@ +Featureless Settings Specification: 0003 - Extended List + +Each Object starts at the beginning of a line and whitespace to the left of the Object is not treated as an object. +An open-brace ({) followed by any whitespace until a newline terminates a valid Object. +Non-whitespace may not follow the open-brace of a valid Object. + +Content exists on every line following a valid object until the end of file (or string) or until a non-delimited close-brace (}). +Any Content that could be interpreted as an end of content must be delimited if it should be part of the content. +Whitespace may follow a valid close-brace but a terminating newline must be present to designate a valid end of content. + +There is no single-quote or double-quote delimitation in this specification. +Only the open-brance that would result in a valid Object or the close-brace that would terminate valid Content can be delimited. + +Key: + \s = whitespace, except newline. + \o = any printable character, except unescaped '{'. + \l = any printable character or whitespace, except unescaped '}'. + \c = either whitespace or printable, including newline, that not interpretable as an Object. + \n = newline. + * = 0 or more occurrences. + +Structure: + \s*\o\l*{\s*\n\c*\n\s*}\s*\n + +Example: + # fss-0003 + # valid comments are ignored. + "The Object" { + Does not need to be quoted. + This: does not need to be delimited. + \} + } + Second { + Continues until EOS/EOF. + All whitespace, including newline (and leading whitespace) is part of content. + # Valid comments are still ignored. + } + +Objects would be: + 1) "The Object" + 2) Second + +Contents would be: + 1.1) Does not need to be quoted. + This: does not need to be delimited. + } + 2.1) Continues until EOS/EOF. + All whitespace, including newline (and leading whitespace) is part of content. diff --git a/specifications/fss-0004.txt b/specifications/fss-0004.txt new file mode 100644 index 0000000..46ccceb --- /dev/null +++ b/specifications/fss-0004.txt @@ -0,0 +1,5 @@ +Featureless Settings Specification: 0004 - Very Basic List + +This is a fss-0002 Basic List whose Content is then processed as fss-0000 Basic. + +TODO: further document this. diff --git a/specifications/fss-0005.txt b/specifications/fss-0005.txt new file mode 100644 index 0000000..9b1f73e --- /dev/null +++ b/specifications/fss-0005.txt @@ -0,0 +1,5 @@ +Featureless Settings Specification: 0005 - Somewhat Basic List + +This is a fss-0002 Basic List whose Content is then processed as fss-0001 Extended. + +TODO: further document this. diff --git a/specifications/fss-0006.txt b/specifications/fss-0006.txt new file mode 100644 index 0000000..cdd4644 --- /dev/null +++ b/specifications/fss-0006.txt @@ -0,0 +1,5 @@ +Featureless Settings Specification: 0006 - Somewhat Extended List + +This is a fss-0003 Extended List whose Content is then processed as fss-0000 Basic. + +TODO: further document this. diff --git a/specifications/fss-0007.txt b/specifications/fss-0007.txt new file mode 100644 index 0000000..8ede652 --- /dev/null +++ b/specifications/fss-0007.txt @@ -0,0 +1,5 @@ +Featureless Settings Specification: 0007 - Very Extended List + +This is a fss-0003 Extended List whose Content is then processed as fss-0001 Extended. + +TODO: further document this. diff --git a/specifications/fss-0008.txt b/specifications/fss-0008.txt new file mode 100644 index 0000000..53449c9 --- /dev/null +++ b/specifications/fss-0008.txt @@ -0,0 +1,5 @@ +Featureless Settings Specification: 0008 - Embedded List + +This is a fss-0003 Extended List whose Content is then recursively processed as fss-0003 Extended List. + +TODO: further document this. diff --git a/specifications/fss-0009.txt b/specifications/fss-0009.txt new file mode 100644 index 0000000..d7deb81 --- /dev/null +++ b/specifications/fss-0009.txt @@ -0,0 +1,5 @@ +Featureless Settings Specification: 0009 - Reverse Mapping + +This is based off of fss-0000 Basic, except the Object is at the end of the line. + +TODO: further document this. diff --git a/specifications/fss-000A.txt b/specifications/fss-000A.txt new file mode 100644 index 0000000..a6eeeb0 --- /dev/null +++ b/specifications/fss-000A.txt @@ -0,0 +1,5 @@ +Featureless Settings Specification: 000A - Extended Reverse Mapping + +This is based off of fss-0001 Extended, except the Object is at the end of the line. + +TODO: further document this. diff --git a/specifications/fss-000B.txt b/specifications/fss-000B.txt new file mode 100644 index 0000000..4cf31e3 --- /dev/null +++ b/specifications/fss-000B.txt @@ -0,0 +1,7 @@ +Featureless Settings Specification: 000B - Simple Json + +TODO: this will be implemented such that it is as closely FSS compliant form of JSON. +It is not intended to be identical to JSON nor a JSON replacement. +It is intended to be a subset of JSON that follows the FSS practices. +(An FSS format that can be imported as JSON with no functional changes to the data). +This will likely be a more specific form of fss-0008 Embedded List, except additional tweaks added to accommodate JSON requirements. diff --git a/specifications/fss-000C.txt b/specifications/fss-000C.txt new file mode 100644 index 0000000..728ccf9 --- /dev/null +++ b/specifications/fss-000C.txt @@ -0,0 +1,3 @@ +Featureless Settings Specification: 000C - Simple List + +This might be similar to fss-0008 - Embedded List, except it is an fss-0003 Extended List with a (non-recursive) fss-0002 Basic List inside the Content. diff --git a/specifications/fss.txt b/specifications/fss.txt new file mode 100644 index 0000000..97ea0b2 --- /dev/null +++ b/specifications/fss.txt @@ -0,0 +1,65 @@ +Featureless Settings Specifications + +A Keep It Simple Stupid specifications for configuration/settings files. + +This specification defines the following: +- Will consist of numerous different kinds of specification files, depending on the type of information stored. +- As with the practice of "#!/bin/bash", the setting files MUST have the following: "# fss-????" format, such as "# fss-0001". +- With the ? representing the (hexadecimal/base-16) number that represents the particular specification structure. +- All settings specifications must avoid any form of noise, relative to the data being stored. +- ie: XML would be considered anti-KISS due to the extreme level of noise generated by the XML language (not easy to read). +- The settings files are setup so that they produce easy readability on both the console and in a GUI. + +The basic FSS specifications consists of two main parts: an "object" and the "content". +- Object: considered the name or identifier of some particular data. +- Content: the data associated with a given Object; all Content must have an associated Object. + +Objects can include any characters allowed by the specifications. +Contents should allow any data and the specification has to allow it in some way. +The specification may chose, however, how a given Content is represented and parse. +For example, in FSS-0000 (Basic), Content is treated as a single item whereas in FSS-0001 (Extended), Content is broken apart in multiple sub parts. + +Unless explicitly defined by the specification, all specifications are newline sensitive ('\n' only). +Newline characters are only '\n' and are never anything else (\r is not considered newline in any manner). +Whitespaces characters that are printable, such as tabs and spaces must be considered the same type. +Non-printing whitespaces characters are ignored or are treated as placeholders for processing. +In terms of processing, it is recommended that the NULL character is not considered the end of a string, but this is only a suggestion. + +Unless explicitly defined, newlines designate the start of a potential new Object or the potential end of some Content. + +Unless explicitly defined, whitespace may exist to the left of the start of objects. + +Unless explicitly defined, quotes may only be either a single quote or a double quote and only a backslash may be used as a delimiter. + +Unless explicitly defined by the specification, character/data delimits are performed only when required and not unilaterally. +In the case of Objects, delimits would only apply when that object could be potentially identified as an object when it otherwise should not. +For example, FSS-0001 (Extended) needs quotes to group parts that include spaces, if there is no initial quote, then a quote following the data must not be delimited. +Such as these following two lines: + "Object 1" "This is a single quoted Content." \"Additional unquoted Content" + Object_2 This is multiple" Contents and the trailing quote does not need to be delimited. + +Unlike this specification, a more traditional delimit process would have the above two lines instead represented as: + "Object 1" "This is a single quoted Content." \"Additional unquoted Content\" + Object_2 This is multiple\" Contents and the trailing quote does not need to be delimited. + +All specifications are expected to support or be of the character encoding utf-8; however, there is no imposed restriction on supporting or using any other encoding. +Those encodings must only support the appropriate characters required by a given standard for differentiating Objects, Contents, and delimits. + +Unless explicitly defined, comments are designated by the pound symbol '#' but only if only whitespace is to the left of the pound. +There is no support for inline comments. + +The follow specifications are defined in this project. +Each of these specifications has a common name associated with the specification number. +- fss-0000: Basic +- fss-0001: Extended +- fss-0002: Basic List +- fss-0003: Extended List +- fss-0004: Very Basic List +- fss-0005: Somewhat Basic List +- fss-0006: Somewhat Extended List +- fss-0007: Very Extended List +- fss-0008: Embedded List +- fss-0009: Reverse Mapping +- fss-000A: Extended Reverse Mapping +- fss-000B: Simple Json +- fss-000C: Simple List -- 1.8.3.1