evm2term/README.md

Translates from Egg Virtual Machine (JSON) to a summarized AST term

## Installation

```
npm i -g evm2term
```

## Usage

```
Usage: evm2term [options] <json file containing the ast>

Converts an Egg AST to a term representation

Options:
  -V, --version  output the version number
  -i, --indent
  -h, --help     display help for command
```

## Description

Provides an executable `evm2term` that summarizes an AST stored in a json file.
Currently only there is a description file `egg-ast-description.js` giving support 
to the ASTs provided by the `egg` compiler used in the classes of the subject *[Language Processors](https://ull-esit-gradoii-pl.github.io/practicas/index.html)*:

For instance, for this Egg program:

```
➜ cat cat examples/summult.egg
```
```ruby
+(a,*(4,5))
```

The AST generated by the any parser  is usually a long JSON:
```
➜  eggc examples/summult.egg       
➜  evm2term git:(generic) ✗ cat examples/summult.json
```
```json
{
  "type": "apply",
  "operator": {
    "type": "word",
    "offset": 0,
    "lineBreaks": 0,
    "line": 1,
    "col": 1,
    "name": "+"
  },
  "args": [
    {
      "type": "word",
      "offset": 2,
      "lineBreaks": 0,
      "line": 1,
      "col": 3,
      "name": "a"
    },
    {
      "type": "apply",
      "operator": {
        "type": "word",
        "offset": 4,
        "lineBreaks": 0,
        "line": 1,
        "col": 5,
        "name": "*"
      },
      "args": [
        {
          "type": "value",
          "value": 4,
          "raw": "4"
        },
        {
          "type": "value",
          "value": 5,
          "raw": "5"
        }
      ]
    }
  ]
}
```

You can get the shape of the AST using `evm2term`:

```
✗ evm2term examples/summult.json
apply(op:word{"+"},args:[word{"a"},apply(op:word{"*"},args:[value{4},value{5}])])
```


## The Term Language to Summarize ASTs

`Term` is a DSL to summarize ASTs. Here is an attempt to describe the language:

```
term -> ('NAME' ':')? 'TYPE' '(' term (',' term)* ')'
  | leaf
leaf -> ('NAME' ':')? 'TYPE' ('{' 'ATTRIBUTE' '}')?
```

* Token `'NAME'` is the name of the child in the node, 
* Token `'TYPE'` represents the type of the node, 
* The token `'ATTRIBUTE'` is the JSON stringify of a single attribute of the leaf node. 

To summarize the AST the following rules are followed: 

* Only the type of the node is shown
* Only one selected attribute of a leaf is shown (Between curly brackets)
* Array n-ary nodes are allowed (and they go between brackets)

## Trick

The syntax of the output seems to be legal ruby. You get syntax highlighting by saving the output with the `.rb` extension

## Future Work

By adding a configuration JS file following the pattern in [egg-ast-description.js](egg-ast-description.js), the program  can be used to work with different ASTs.

* Write more AST descriptions for different JS transpilers (esprima, babel, etc.)