sh-syntax

A WASM shell parser and formatter with bash support, based on mvdan/sh

TOC

• Usage
  • Install
  • API
    • node
    • browser
• Benchmark
• Sponsors
• Backers
• Changelog
• License

Usage

Install

# yarn
yarn add sh-syntax

# npm
npm i sh-syntax

API

node

import { parse, print } from 'sh-syntax'

const text = "echo 'Hello World!'"
const ast = await parse(text)
const newText = await print(ast, {
  // `originalText` is required for now, hope we will find better solution later
  originalText: text,
})

browser

import { getProcessor } from 'sh-syntax'

// choose your own way to load the WASM file

// with `fetch`
const processor = getProcessor(() =>
  fetch('http://cdn.jsdelivr.net/npm/sh-syntax@latest/main.wasm'),
)

// with `wasm?init` via `vite`
import initWasm from 'sh-syntax/wasm?init'
const processor = getProcessor(initWasm)

const parse = (text, options) => processor(text, options)

const print = (textOrAst, options) => {
  if (typeof textOrAst === 'string') {
    return processor(textOrAst, {
      ...options,
      print: true,
    })
  }
  return processor(textOrAst, options)
}

// just like node again
const text = "echo 'Hello World!'"
const ast = await parse(text)
const newText = await print(ast, { originalText: text })

Benchmark

clk: ~2.81 GHz
cpu: Apple M1 Max
runtime: node 18.20.8 (arm64-darwin)

benchmark                   avg (min … max) p75 / p99    (min … top 1%)
------------------------------------------- -------------------------------
sh-syntax                     18.33 ms/iter  18.56 ms   ▃        ▃█
                      (17.48 ms … 20.83 ms)  19.09 ms ▂▂█    ▂   ██▂  ▂ ▂
                    ( 28.52 kb …   9.82 mb) 890.46 kb ███▆▆▁▁█▁▁▆███▁▆█▁█▆▆
                  5.07 ipc (  1.22% stalls)  99.36% L1 data cache
         56.96M cycles 288.57M instructions  39.27% retired LD/ST (113.32M)

sh-syntax (synckit)           18.38 ms/iter  18.82 ms ▂▂▂           ▂▂ █▂
                      (17.63 ms … 19.06 ms)  19.04 ms ███▅          ██ ██▅▅
                    (291.31 kb … 312.45 kb) 292.09 kb ████▇▇▇▇▁▁▁▁▇▁██▇████
                  1.11 ipc ( 11.51% stalls)  40.34% L1 data cache
        434.86k cycles 484.78k instructions  19.58% retired LD/ST ( 94.92k)

mvdan-sh                      79.47 ms/iter  78.95 ms  █
                     (71.22 ms … 126.09 ms)  80.84 ms ▅█ ▅▅▅    ▅    ▅▅▅  ▅
                    (  8.18 mb …   9.70 mb)   8.83 mb ██▁███▁▁▁▁█▁▁▁▁███▁▁█
                  5.18 ipc (  1.05% stalls)  99.04% L1 data cache
        249.41M cycles   1.29G instructions  34.41% retired LD/ST (444.42M)

summary
  sh-syntax
   1x faster than sh-syntax (synckit)
   4.34x faster than mvdan-sh

See benchmark for more details.

You can try it with running node benchmark by yourself. Here is the benchmark source code.

Sponsors

| 1stG | RxTS | UnTS | | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | | | |

Backers

| 1stG | RxTS | UnTS | | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | | | |

Changelog

Detailed changes for each release are documented in CHANGELOG.md.

License

MIT © JounQin@1stG.me