klishta v1.0.2

Welcome to Klishta

Klishta is a data transfer file format. In this document, we will look at how to format a Klishta file. This repository contains a compiler to understand Klishta files in JavaScript.

Using the compiler

This repository contains a compiler to parse a string in the Klishta file format into JavaScript. This will create an object of values rendered from the Klishta format.

Installation

Using NPM, run the following command in the root directory of the project you are working on:

npm install klishta

This will install the latest version of the Klishta compiler. You can then import the module as so:

import Klishta from 'klishta';

You can then pass the Klishta file to the Klishta command and you will receive an object with two properties:

type: If successful, this will come back as "success". Otherwise, "error". content: If successful, this will contain an object with the parsed data. If an error, it will return the error message as a string.

About the Klishta file format

Important Terms

The Structure of a Klishta File

Klishta uses a beautifully simple file structure.

Making a Paired Collection

For illustration purposes, let's say that we are making a Paired Collection that describes a group of fictional characters from Shakespeare's play "Macbeth". To make the Paired Collection, we would use:

Characters (
    Macbeth	=	(
	    Name		=	Macbeth 			||
	    Married		=	bool_yes			||
		Children	=	is_null				||
		Other Relatives	=	(
			*	Lady Macbeth		||
			*	King Duncan			||
			*	Malcolm				||
			*	Donalbain			||
		)
	)
	Banquo	=	(
		Name		=		Banquo				||
		Married		=		unknown				||
		Children	=	(
			* Fleance ||
		)
		Other Relatives	=	is_null			||
	)
	Fay		=	(
		Name		=		Fay $!(First Witch)!$	||
		Married		=		bool_no						||
		Children	=		is_null						||
		Other Relatives	=	(
			*	Oonagh		||
			*	Kylock		||
		)
	)
)

Now, let's take a full look at the syntax involved. First, we will look at Paired Collections and then at Unkeyed Collections. Most of the syntax is shared between both, so it is recommended to read about Paired Collections first as this will give you the knowledge needed to also make Unkeyed Collections.

Paired Collections

To start, let's create the first Paired Collection - the Characters Collection. As it's at the top-most level (it doesn't have any parent of its own), we initiate it with the collection's name and then an opening parenthesis. We must then add a closing parenthesis: we may optionally put this a couple of lines under our first. Note: You can also put them all in the same line - Klishta will accept either format.

Characters	()

OR

Characters (
)

For the sake of this tutorial, we will use the line spaces as it makes it friendlier to human readers.

Properties and Values

Each Paired Collection can have a group of properties, and values. These are determined by writing the property followed by an equals mark.

Name		=		Macbeth		||

Properties must end with a || line. This tells Klishta that the value has now been set.

Special values

It is hoped that Klishta will be a file format that can be translated into multiple programming languages and, to help with this goal, Klishta uses special characters that are then converted depending on what language it is being compiled to. For example, in JavaScript booleans are written as true or false, but in Python they are written as True or False (notice the difference in capitalisation) or, for a more extreme example, in JavaScript when the value is empty, it is called null while in Python it is called None.

To accommodate for these sorts of differences, Klishta is intended to use a shared value, irrespective of the language it is being compiled to.

Explicitly setting characters

As we have seen, Klishta uses parenthesis to create new objects. However, what if we want to use parenthesis inside a key, or value, and don't want the system to get confused into thinking its an object, when really it's just part of the value? Similarly, what if we want to use an equals sign, a vertical bar, or an asterisk?

Klishta includes an explicit indicator to tell the system to ignore special characters it encounters, in between the explicit indicators.

For example:

Fay (First Witch)

By default, the system would see ( as being the start of a new object and ) as being the end of said object.

To circumvent this, wrap the value as such:

Fay $!(First Witch)!$

This tells the system to ignore any of the special characters in between the dollar-sign-explanation pairing. You could also choose to do it as such:

Fay $!(!$First Witch$!)!$

Or:

$!Fay (First Witch)!$

The choice is yours. The indicator will only work when the dollar sign and exclamation point are next to each other, and the closing !$ will only work if an opening one $! has already been established.

If you end up needing to use !$ or $! as those actual characters, you can wrap each of the exclamation points and dollar signs in those symbols (only matters if they appear right next to each other; otherwise feel free to use dollar signs and exclamation points as you would normally without needing any special formatting)

Unkeyed Collections

If they appear at the top-most level, unkeyed collections can be declared with an unnamed set of parenthesis

(
    * Macbeth 			||
    * Hamlet 			||
    * Romeo & Juliet 	||
)

Or they can take a named parenthesis.

Shakespeare Plays (
    * Macbeth 			||
    * Hamlet			||
    * Romeo & Juliet	||
)

The choice is yours.

Listing elements in an unkeyed collection

To list an element within an unkeyed collection, use the asterisk symbol before each element and, as usual, close the element by a set of vertical bars.

* Macbeth			||
* Hamlet			||
* Romeo & Juliet	||

Sub collections

Unkeyed Collections can contain both Paired Collections as child elements, or other Unkeyed Collections.

(
    * Fair is Foul		||
    Macbeth	=	(
		Genee	=	Tragedy	||
	)
)

You can optionally give them an ID or not.

Mixing Collection Types

Paired Collections and Unkeyed Collections can be mixed freely, depending on your use case scenario. For example, here when talking about Fay, it mentions her siblings as being Other Relatives (i.e. the three witches - named here for example, even if their names remain a mystery in the original play)

Fay		=	(
		Name		=		Fay $!(First Witch)!$	||
		Married		=		bool_no						||
		Children	=		is_null						||
		Other Relatives	=	(
			*	Oonagh		||
			*	Kylock		||
		)
	)

Here, we have added an Unkeyed Collection within a Paired Collection while in our previous example we had a Paired Collection inside an Unkeyed Collection.