sh-syntax

README

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