Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/burodepeper/lib-ass

Agile Semantics Syntax
https://github.com/burodepeper/lib-ass

Last synced: 3 days ago
JSON representation

Agile Semantics Syntax

Host: GitHub
URL: https://github.com/burodepeper/lib-ass
Owner: burodepeper
Created: 2015-10-03T09:25:53.000Z (about 9 years ago)
Default Branch: master
Last Pushed: 2019-05-22T10:54:49.000Z (over 5 years ago)
Last Synced: 2024-10-08T09:07:38.996Z (about 1 month ago)
Language: CoffeeScript
Homepage:
Size: 14.6 KB
Stars: 3
Watchers: 3
Forks: 1
Open Issues: 2
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

README

# lib-ass

Use **Agile Semantics Syntax** (ASS) to describe and parse any syntax or grammar in a convenient nested structure. `lib-ass` will convert your `.ass` files into a convenient `JSON`-object, and from there it is up to you.

[language-markdown](https://atom.io/packages/language-markdown/), where `lib-ass` originated from, makes heave use of `ASS` to increase the speed and flexibility of writing automated tests.

---

## Introduction

Read up on [semantics](https://en.wikipedia.org/wiki/Semantics), and then let's look at a simple example.

```ass
"height: 188cm" {
attribute {
"height": key
": "
"188cm": value
}
}
```

We took the string `height: 188cm`, said it was an `attribute`, and then we split up the contents of the string, and described them into a `key` and a `value` part. We can even go a step further; the `value` consists of two separate semantic elements: an amount and a unit. Let's update our spec:

```ass
"height: 188cm" {
attribute {
"height": name
": "
"188cm" {
value {
"188": amount
"cm": unit
}
}
}
}
```

I have swapped the output `"188cm": value` for a new _input_, described it as a `value` as we did before, but now, I've also specified an `amount` and a `unit`.

When `lib-ass` parses this information, it checks its validity, and then converts it to a json-object with every scope resolved on every token. I used two new terms there, `scope` and `token`. Let's look at the semantic structure of our first `ass-test` to see what I mean by them.

```
{
{
:

:
}
}
```

I'm not a native English speaker, but in this context, `scope` can be described as a _meaning_, and `token` can be described as a _thing_. So if we translate the pseudo-code above to a 'normal' sentence, we'd get something like:

> My `` is a `` and consists of ``, `` and ``. `` is also a ``, and `` is also a ``.

The most interesting thing about this is that `` is part of `` AND ``; scope-3 is just more specific than scope-1. We can now describe our `` (or output) in the following way:

- ``: `` and ``
- ``: ``
- ``: `` and ``

And that is exactly what `lib-ass` creates from our input, but then in the form of `json`. Whatever you do with that data is up to you. Along with the main library, it is our intention to release several ready-to-go implementations of automated tests that can be run.

---

## Syntax

### File format

An `.ass` file is a plain-text file that can contain `tests`, `comments` and blank lines. Comments are lines that start with a `#` (with optional leading whitespace). Tests are defined below. It is good practice (though optional) to separate your tests with at least a single blank line.

### Test formats

The syntax used in an `.ass` file consists of only a few forms. You can technically infinitely nest and combine these forms.

There are two test formats: the single-line `` format, and the multi-line `` format. Both of them can be preceded by an optional ``.

#### ``

```
(optional)
:
```

#### ``

```
(optional)
{

}
```

To specify an input `` that consists of multiple lines, you can concatenate ``s by using the following syntax:

```
+
+
{

}
```

### Data formats

#### ``

An id is a line that starts with a `@` and ends at the end of the line. Any character is (technically) allowed in an ``.

#### ``

A group is a series of objects, grouped together between curly braces. Each object starts on a new line. Indentation within a group is optional, though highly recommended.

The possible objects in a group are: ``, `` and ``. Blank lines and comments may also be part of a ``.

A test with a single `` could look like this:

```
(optional)
{

}
```

#### ``

A `` is a literal string, that depicts _meaning_.

#### ``

A token is a string that starts and ends with either a single or a double quote, that depicts _content_.

---

## An advanced example

The following example describes a piece of `scss` code in `.ass` and the `.json` (just the first bit, I'm lazy) it is converted to. At first glance, the `ASS` looks verbose, and I will immediately admit that it is. But it is also as verbose as you decide to make it. The good thing however is that repeating patterns do not rely on their contexts, and thus can be easily copy-and-pasted. Also, as a personal preference, I've describes several parts more verbose than they need to be; as an example, but also because it helps readibility and eases the re-usability of sections.

```css
article {
font: 12px/18px sans-serif;
color: #000000;

p:not(:last-child) {
margin-bottom: 9px;
}
}
```

```ass
@scss-example
"article {" +
" font: 12px/18px sans-serif;" +
" color: #000000;" +
"" +
" p:not(:last-child) {" +
" margin-bottom: 9px;" +
" }" +
"}" {
scss {
"article" {
selector {
"article": html-tag
}
}
" "
"{": punctuation

"font: 12px/18px sans-serif;" {
declaration {
"font": property
":": punctuation
" "
"12px" {
value {
size {
"12": amount
"px": unit
}
}
}
"/": punctuation
"18px" {
value {
size {
"18": amount
"px": unit
}
}
}
" "
"sans-serif": font-family
";": punctuation
}
}

"color: #000000;" {
declaration {
"color": property
":": punctuation
" "
"#000000" {
value {
color {
rgb {
"#": punctuation
"00": red
"00": green
"00": blue
}
}
}
}
";": punctuation
}
}

# This is an empty line
""

"p:not(:last-child)" {
selector {
"p": html-tag
":not(:last-child)" {
pseudo-selector {
":": punctuation
"not": name
"(": punctuation
":last-child" {
pseudo-value {
":": punctuation
"last-child"
}
}
")": punctuation
}
}
}
}
" "
"{": punctuation

"margin-bottom: 9px;" {
declaration {
"margin-bottom": property
":": punctuation
" "
"9px" {
value {
size {
"9": amount
"px": unit
}
}
}
";": punctuation
}
}

"}": punctuation
"}": punctuation
}
}
```

```json
{
"id": "scss-example",
"tokens": [
{
"value": "article",
"scopes": ["scss", "selector", "html-tag"]
},
{
"value": " ",
"scopes": ["scss"]
},
{
"value": "{",
"scopes": ["scss", "punctuation"]
},
{
"value": "font",
"scopes": ["scss", "declaration", "property"]
},
{
"value": ":",
"scopes": ["scss", "declaration", "punctuation"]
},
{
"value": " ",
"scopes": ["scss", "declaration"]
},
{
"value": "12",
"scopes": ["scss", "declaration", "value", "size", "amount"]
},
{
"value": "px",
"scopes": ["scss", "declaration", "value", "size", "unit"]
},
{
"value": "",
"scopes": ["scss", "declaration", "punctuation"]
},
{
"value": "18",
"scopes": ["scss", "declaration", "value", "size", "amount"]
},
{
"value": "px",
"scopes": ["scss", "declaration", "value", "size", "unit"]
}
]
}
```

etc.