https://github.com/yuanqing/stoke

:evergreen_tree: Generate the Abstract Syntax Tree (AST) of a Bash command
https://github.com/yuanqing/stoke

Last synced: 10 days ago
JSON representation

:evergreen_tree: Generate the Abstract Syntax Tree (AST) of a Bash command

• Host: GitHub
• URL: https://github.com/yuanqing/stoke
• Owner: yuanqing
• License: mit
• Created: 2015-02-01T17:25:23.000Z (almost 10 years ago)
• Default Branch: main
• Last Pushed: 2021-01-30T07:42:01.000Z (almost 4 years ago)
• Last Synced: 2024-10-22T11:00:07.932Z (18 days ago)
• Language: JavaScript
• Homepage:
• Size: 15.6 KB
• Stars: 15
• Watchers: 2
• Forks: 2
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Stoke.js [![npm Version](http://img.shields.io/npm/v/stoke.svg?style=flat)](https://npmjs.com/package/stoke) [![Build Status](https://img.shields.io/travis/yuanqing/stoke.svg?branch=master&style=flat)](https://travis-ci.org/yuanqing/stoke) [![Coverage Status](https://img.shields.io/coveralls/yuanqing/stoke.svg?style=flat)](https://coveralls.io/r/yuanqing/stoke) ![Stability Experimental](http://img.shields.io/badge/stability-experimental-red.svg?style=flat)

> Generate the Abstract Syntax Tree (AST) of a [Bash](http://www.gnu.org/software/bash/) command.

- Tokenise a given command based on a subset of Bash’s quoting rules

- Detect malformed commands

- [Extensive tests](https://github.com/yuanqing/stoke/blob/master/test), with [100% coverage](https://coveralls.io/r/yuanqing/stoke)

## Why

This was written mainly:

1. As an exercise in writing a parser based on strict grammar rules

2. As part of a larger project to build a Bash shell from the ground up

## Usage

```js

stoke('echo "foo `echo \'bar baz\'`"');

/* [

 *   {

 *     type: 'unquoted',

 *     body: 'echo'

 *   },

 *   {

 *     type: 'double-quoted',

 *     body: [

 *       {

 *         type: 'unquoted',

 *         body: 'foo '

 *       },

 *       {

 *         type: 'back-quoted',

 *         body: [

 *           {

 *             type: 'unquoted',

 *             body: 'echo'

 *           },

 *           {

 *             type: 'single-quoted',

 *             body: 'bar baz'

 *           }

 *         ]

 *       }

 *     ]

 *   }

 * ]

 */

```

[Read the tests](https://github.com/yuanqing/stoke/blob/master/test) for more usage examples.

### Grammar

The granularity of the AST is at the *token* level. Tokenisation is based on a subset of [Bash’s quoting rules](https://www.gnu.org/software/bash/manual/html_node/Quoting.html). This particular subset of the grammar (specified in [EBNF](http://en.wikipedia.org/wiki/Extended_Backus-Naur_Form)) is as follows:


token         = unquoted | single­-quoted | double­-quoted | back-quoted ;

unquoted      = ? /[^'"` ]+/ ? ;

single­-quoted = “'” , ? /[^']+/ ? , “'” ;

double-­quoted = “"” , { unquoted | back-quoted } , “"” ;

back-quoted   = “`” , { unquoted | single­-quoted | double­-quoted } , “`” ;



(Currently, Stoke does *not* support escape sequences. For example, you currently cannot escape a double-quote character when inside a double-quote block.)

Stoke will throw an error if a given command does not conform to the above grammar rules.

## API

### stoke(str)

See [Usage](#usage).

## Installation

Install via [npm](https://npmjs.com/):

```

$ npm i --save stoke

```

## Changelog

- 0.1.0

  - Initial release

## License

[MIT](https://github.com/yuanqing/stoke/blob/master/LICENSE)