Stoke.js

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

• Tokenise a given command based on a subset of Bash’s quoting rules
• Detect malformed commands
• Extensive tests, with 100% coverage

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

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 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. This particular subset of the grammar (specified in EBNF) 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.

Installation

Install via npm:

$ npm i --save stoke

Changelog

• 0.1.0
  • Initial release

License

MIT