Skip to content

Latest commit

 

History

History
192 lines (132 loc) · 9.46 KB

README.md

File metadata and controls

192 lines (132 loc) · 9.46 KB
Raw

Enclst

What is this?

The Enclst is a notation rule and API for humans to write a list structure concisely compared to JSON which is illegal syntax prone.

What is this for?

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.

Why not JSON?

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.

Enclst Notation

The Structure of the Enclst.

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.

ItemList

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.

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.

Value

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:

Positional

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"

Named

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.

Separator

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.

Title

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!

For more details

More detail of Enclst Notation is available here.

Structured List

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.

How concise the Enclst is

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.

Libraries

JavaScript

uml

Dart

Application examples

For Website URL

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.

documentation

document

examples

For Youtube Contents

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.

examples