Abjure NPM | npm.io

Abjure

This package is a command line interface utility that can transpile a source directory into a build directory but with some special features in regards to javascript files. It will look for special comment lines and either "comment in" or "comment out" those sections based on some simple patterns. The main idea is that this feature allows for special imports between javascript files that wouldn't normally be able to import or export their code. This allows the developer a type of on-demand special intellisense.

Setup

This project can be installed globally as a CLI utility using npm install -g abjure. Alternatively, it can be installed locally, typically as a development dependency, with npm install --save-dev abjure. To invoke the locally installed version, use npx abjure [options] [command], where [options] and [command] would be replaced with some basic parameters.

Options:
  -V, --version            output the version number
  -s, --skip               skip greeting
  -l, --log                enable verbose logging
  -h, --help               display help for command

Commands:
  build <source> <target>  build special comments from source directory to target directory
  help [command]           display help for command

The easiest way to use this package is to register it as a build script in your package.json file. For example, if you want to target a src folder and transpile it to a build folder, use the following script:

{
  "scripts": {
    "build": "abjure build \"./src\" \"./build\""
  }
}

Then, running npm run build will transpile everything in the src folder into the build folder in the root of your project.

The "--skip" flag will skip the large logo and version/website logging. The "--log" flag will enable verbose logging - any file or folder that is copied, edited, or deleted will be logged.

Using a file watching script in conjunction with this project is highly recommended. The idea is that whenever a file is changed, added, or deleted within your main source folder, your project should rebuild automatically. Here's an example using Chokidar-CLI:

{
  "scripts": {
    "build": "abjure build \"./src\" \"./build\"",
    "watch": "chokidar \"./src\" -c \"npm run build\""
  }
}

Running npm run watch with the above script configuration will start the watcher, and whenever a file is changed within the src folder, the build script will run.

Usage

For inserting and removing multiple lines, start with /*+++*/ for inserting code and /*---*/ for removing code. End these sections with /*...*/. Everything between these lines will either be inserted (whereby double slash comments will be removed from the start of the line) or removed (whereby double slash comments will be added to the start of the line). Note that these lines only need to start with these patterns (ignoring any leading space or tab characters), which can be helpful for extra comments.

For inserting and removing single lines, start with // /*++*/ for inserting code and /*--*/ for removing code. These sections don't require any ending pattern.

For inserting and removing inline code, start with /*+*/ /* for inserting code and /*-*/ for removing code. These patterns can be inserted anywhere in a line of code, and will change into /*+*/ for insertion and /*-*/ /* for removal. Ending these parts of a line with /*.*/ can help clean up lingering block quotes in both the source file or the transpiled result.

Example: look at the following example source code:

// multiline insertion
/*+++*/
// console.log('this will be inserted at build!')
/*...*/

// multiline removal
/*---*/
console.log('this will be removed at build!')
/*...*/

// single line insertion
// /*++*/ console.log('this will be inserted at build!')

// single line removal
/*--*/ console.log('this will be removed at build!')

// inline insertion and removal
console.log(/*+*/ /* 'this will be inserted at build!' /*.*/ /*-*/ 'this will be removed at build!' /*.*/)

When the project builds, the code will turn into the following:

// multiline insertion
/*+++*/
console.log('this will be inserted at build!')
/*...*/

// multiline removal
/*---*/
// console.log('this will be removed at build!')
/*...*/

// single line insertion
/*++*/ console.log('this will be inserted at build!')

// single line removal
// /*--*/ console.log('this will be removed at build!')

// inline insertion and removal
console.log(/*+*/ 'this will be inserted at build!' /*.*/ /*-*/ /* 'this will be removed at build!' /*.*/)

As a side note, I thought it'd be worthwhile to mention that - for convenience - these patterns are meant to be typed using only one hand on a number pad.

Examples

Here are a couple of projects that I designed which make use of Abjure:

Morphmaster: An electron boilerplate application with CLI build utilities based off AngularJS and Bootstrap.
Morphmaster-Web: A web application boilerplate with CLI build utilities based off AngularJS and Bootstrap.

Known Issues

One issue with the single line and inline methods is that they will usually behave poorly with anything but the default vscode code formatter for javascript files, as most code formatters will push code that appears after a block quote, which is anything starting with /* and ending with */, to a new line.