The Enclst is a notation rule and API for humans to write a list structure concisely compared to JSON which is illegal syntax prone.
This is for what humans write a list of data with attributes and title string that a computer handles the data. Typically the data is something ID like a URL of a website or a content ID of YouTube.
JSON is a rich notation enough to represent general objects including lists. There is no difficulty for a computer program to handle a JSON. However it comes to humans, it is NOT easy to write a no-error JSON string. When you try to write JSON by hand, you may notice the following pitfalls:
- Prohibition of dangling commas
- String escaping
Even when experienced software engineers (like me :-) write a JSON by hand carefully, it's impossible to keep writing without any errors. Furthermore, asking non-engineering end users to input error-free JSON is unreasonable.
This is exactly my motivation for creating enclst. JSON is impossible for a non-engineer end user. A more succinct alternative must be necessary.
So, the Enclst Notation is designed to avoid both:
- The end of the item's comma.
- string escaping
The major pitfall of JSON has gone away.
An Enclst is a multi-line string separated by line breaks. The first line is interpreted as the title string for the entire enclst, followed by the ItemList separated by a blank line illustrated as follow:
In your application with our libraries, you can get an Enclst object from a string or text file following this Notation. The Enclst object has the following members:
- The Title string, is the same as the Title mentioned above.
- The ItemList array of Item object which is an object representation of the Items mentioned above.
The ItemList is a multi-line string that is the remainder of Enclst followed by The Title and a blank separator line, and each low is one Item.
An Item is consist of Value and Title separated by the first vertical bar "|".
In your application with our libraries, The Item object has the following members:
- The Title string, is the same as the Title mentioned above.
- The Value object which is an object representation of the Value mentioned above.
The Value part consists of comma "," separated string values.
Each value must not contain the following a couple of characters:
- commna ","
- vertical line "|"
This limited restriction allows Enclst to be written in a very simple.
In your application with our libraries, you can refer to each value in two ways, by positional and by name as follow:
These values can be referred to as positional values of a value of an item with a library like as:
item.value.positional[0] // equal "value0"
A value containing an equal sign can refer to the right side using the left side as a name with a library as follows:
item.value.positional // equal ["value0", "val=kerokero", "attr=gerogero", "value"]
item.value.named["val"] // equal "kerokero"
item.value.named["attr"] // equal "gerogero"
Note that a URL that includes parameters is interpreted as a named parameter, but it is not your expected. So refer to the named parameter only if you are intended, otherwise, refer to a positional parameter.
item.value.positional[0] // equal "https://iret.media/?s=HA+Proxy+%E7%99%" and it must be your intention.
item.value.named["https://iret.media/?s"] // equal "HA+Proxy+%E7%99%" but it must be not your intention.
The first vertical line "|" in the Item string is recognized as the separator which separates Value and Title.
Because of this, each value string can't include the vertical bar "|". In fact, many of the specifications for meaningful strings, such as URL strings, explicitly prohibit them from containing bar "|", and many meaningful ID strings are also not intended to contain vertical bars. Therefore, I believe that there are few situations where this restriction will cause trouble.
On the other hand, title strings essentially use arbitrary characters and vertical bars are often used as well. Other common notations, such as JSON, require tedious escaping to include vertical bars in strings.
However, thanks to the aforementioned limitations, Enclst notation allows vertical bars without troublesome escaping to be used inside title strings.
The Title is the second half of the item string separated by the first vertical bar "|". This string can be used as an explanation, a headline, etc. of values.
As mentioned in the section Separator, the title string is designed for any escaping is not needed. Even commas "," and vertical lines "|", you can use them without escaping. This is exactly the benefit of using value limits.
https://www.bhg.com/gardening/plant-dictionary/ | Titles like this, |also| OK!
More detail of Enclst Notation is available here.
A hierarchical list is expressed as a link of the Enclist.
Following features are available in our libraries:
- Function to guess if a value is for the enclst file or not.
- Function to create child enclist indicated by the value for the enclist file mentioned above.
A following JSON expressing a list of youtube contents;
{
"title": "Antonio Pappano",
"items": [
{ "text": "Wagner: \"Das Rheingold\" - Pappano, K. Warner, London 2005 Part 1", "content": "cwpxogKjDH0"},
{ "text": "Wagner: \"Das Rheingold\" - Pappano, K. Warner, London 2005 Part 2", "content": "7yIDvqY8VTE"},
{ "text": "\"Die Walküre\" - Proms 2005 - Antonio Pappano", "content": "Vq-2PVXfOv4"},
{ "text": "Wagner - \"Parsifal\" (Antonio Pappano) ACT 1", "content": "FChG1jb_Y&t"},
{ "text": "Wagner - \"Parsifal\" (Antonio Pappano) ACT 2", "content": "W048GbyGKPs"},
{ "text": "Wagner - \"Parsifal\" (Antonio Pappano) ACT 3", "content": "GkN9KfpIKA8"}
]
}
can be written in Enclst as follows:
Antonio Pappano
cwpxogKjDH0 | Wagner: "Das Rheingold" - Pappano, K. Warner, London 2005 Part 1
7yIDvqY8VTE | Wagner: "Das Rheingold" - Pappano, K. Warner, London 2005 Part 2
Vq-2PVXfOv4 | "Die Walküre" - Proms 2005 - Antonio Pappano
FChG1jb_Y&t | Wagner - "Parsifal" (Antonio Pappano) ACT 1
W048GbyGKPs | Wagner - "Parsifal" (Antonio Pappano) ACT 2
GkN9KfpIKA8 | Wagner - "Parsifal" (Antonio Pappano) ACT 3
No more redundant parentheses, quotes, escape sequences, and commas, much more succinct. Even non-engineers can handwrite it in this notation rule.
- Repository: Enclist-core-js
- Document: jsdoc
- Class diagram:
- Repository: enclst_core_dart
- Document: dart doc
EncycloList: A Web application to display the list of Items that consists of a website URL and a its title, and opens the URL in which selected Item.
- British Newspapers: displaying enclst is here
- Journal Française: displaying enclst is here
- more examples…
HS: A Web application to display the list of Items that consists of a youtube contents ID and its title, and play the contents in which selected Item.
- Nouvelle Francais: displaying enclst is here.
- TV Programs: displaying enclst is here.
- more examples…