semi-parser

A collection of tools for roughly (but quickly) parsing CSS, HTML and JavaScript.

∅  Version: 0.0.6
∅  NPM: https://www.npmjs.com/package/@0bdx/semi-parser
∅  Repo: https://github.com/0bdx/semi-parser
∅  Homepage: https://0bdx.com/semi-parser

@TODO add an overview

Installation

npm i @0bdx/semi-parser

Require an LTS Node version (v14.0.0+).

Usage

@TODO add the redactJs() description

import { equal } from 'assert';
import { redactJs } from '@0bdx/semi-parser';

// In this JavaScript source code, we'd like to replace the identifier
// `foo` with `ok`, without changing the comment, or the string 'foo',
const source = `let foo = 'foo'; console.log(foo); // displays "foo"`;
console.log(`source:\n    ${source}`);

// Define a simple regular expression which finds "foo" multiple times.
// The `g` flag makes exec() search repeatedly - tinyurl.com/mr2puud2
const rx = /foo/g;

// "foo" appears four times in `source`, ending at 7, 14, 32 and 51.
const endPositions = [];
while (rx.exec(source)) endPositions.push(rx.lastIndex);
equal(endPositions.join(), '7,14,32,51');

// Fill the string with dashes, and replace the comment with spaces.
const result = redactJs(source); // no 2nd argument, so default options
equal(result, "let foo = '---'; console.log(foo);                  ");

// "foo" only appears twice in `result`, ending at positions 7 and 32.
// Fill an array with the parts of `source` which do not contain "foo".
let parts = [], from = 0;
while (rx.exec(result)) {
    const endPos = rx.lastIndex;
    parts.push(source.slice(from, endPos - 3)); // 'foo' length is 3
    from = endPos;
}
parts.push(source.slice(from)); // the part after the final "foo"

// Join the parts into a string, with 'ok' placed between each part.
const replaced = parts.join('ok');
equal(replaced, `let ok = 'foo'; console.log(ok); // displays "foo"`);
console.log(`replaced:\n    ${replaced}`);

You can find the redactJs() example in the src/redact-js/ directory, and run it using:
npm run example-1

Contributing

Set up your development machine

1. Check your Git version:
   git --version # should be 'git version 2.20.1' or greater
2. Check your Node version:
   node --version # should be 'v14.0.0' or greater
3. Check your global TypeScript version:
   tsc --version # should be 'Version 4.9.4' or greater
   There are no actual .ts files in this project, but TypeScript can infer types from the JavaScript code and JSDoc comments.
   • VS Code uses tsserver to highlight errors in src/ JavaScript files
   • tsc is needed to generate the semi-parser.d.ts type declaration

Set up VS Code

1. Check your VS Code version:
   code --version # should be '1.74.3' or greater
2. Install and enable the jeremyljackson.vs-docblock extension.
3. Install and enable the dnamsons.kimbie-dark-plus theme.

Set up the repo locally

Clone the repository, and cd into it.
git clone [email protected]:0bdx/semi-parser.git && cd semi-parser

Install Rollup, the only dependency.
npm i
Rollup 3.10.1 adds 2 packages, 2.5 MB, 29 items.

Open semi-parser in VS Code.
code .

Handy dev commands

Run all tests on the in-development source code:
npm test

Run each example, one by one:
npm run example:1
npm run example:2

Or run all the examples:
npm run examples

Build semi-parser.js and semi-parser.d.ts:
npm run build:production
npm run build:typings

Run all tests on the built semi-parser.js file:
npm run preflight:test

Check that semi-parser.js uses all types correctly:
npm run preflight:types

Or run all the build and preflight steps in one line, eg before committing:
npm run build && npm run preflight

Display what will be published:
npm publish --dry-run

Publish to npmjs.com/package/@0bdx/semi-parser:
npm publish