Amie

Amalgamation Made Insanely Easy. A tool to easily amalgamate stuff!

Why?

I'm an experienced C++ developer and I really love sharing amalgamated versions of my libraries. But I've never found a good and easy-to-use amalgamation tool. That's why I decided to make my own using NodeJS. Amie is now alive. This currently only work with C++ and has very poor features capabilities but I'm working on it, lots of stuff planned!

Installation

$ npm i --save amie

Wow that was easy!

Command line

Amie is shipped with a command line utility in case you want to do it outside of nodejs. The usage is pretty simple and mimics the behavior of GCC:

$ amie -h

  Usage: amie [options] <inputFile>

  Options:

    -h, --help                      output usage information
    -V, --version                   output the version number
    -o, --output <file>             The file to output to. If not set, will print on stdout
    -I, --include-path <directory>  Additional directories to search for include files
    -v, --verbose                   Sets the program to output more logs

This CLI uses NodeJS internally. In case you need to use it without NodeJS, simply use the executable version. (to come)

Usage

Amie exports a single function with the following signature:

amie (options : AmieOptions, callback : Function)

callback will be called like so: callback(err, result) where err will evaluate to false if everything went fine and result will be the whole amalgamated string.

Here is an example of the non-file-writing version:

'use strict';

// Start by require-ing the module
const amie = require('amie');

// This one is handy when dealing with paths
const path = require('path');

// Then you call it with an options object.
// The list of default options can be seen below
amie({
    input: path.join(__dirname, '..', '/test_cpp/main.cpp')
}, (err, result) => {

    // If something bad happened, err will evaluate to true.
    console.log(err);

    // result now contains the content of the amalgamated file. You can write it.
    console.log(result);
});

If you want Amie to automatically output the result to a file, just specify a output property to the options object:

'use strict';

const amie = require('amie');
const path = require('path');

amie({
    input: path.join(__dirname, '..', '/test_cpp/main.cpp'),
    output: path.join(__dirname, 'output.cpp')
}, (err, result) => {
    console.log(err);
    console.log(result);
});

Amie will automatically create output if it doesn't exist.

Bonus! If an error occurs while Amie is trying to write output (If you don't have the permisisons, for example) it will call callback with err but also with result containing the amalgamated result so you may handle it yourself.

Options

This is the documentation of the options object passed to Amie. The defaults are written both in the documentation and in the hash below it. The only required property is input.

/**
 * @typedef {Object} AmieOptions
 * 
 * @property {String} [output=''] Path to the file to write.
 *                                If evaluates to false, a string will be returned instead.
 * @property {String} input Path to the file to read
 * @property {Boolean} [fromString=false] Should input be considered as cpp content?
 *                                        If false, considered to be a path.
 * @property {Array} [includePaths=[]] Paths to additional include directories.
 * @property {Boolean} [caching=true] Should Amie cache files or not?
 */
 {
    'output': '',
    'input': '',
    'fromString': false,
    'includePaths': [],
    'caching': true
};

Current TODO list

• ~~Support for string input~~
• ~~Support for file output~~
• ~~Ability to specify additional include directories (-I in gcc)~~
• Ability to add special comments that will generate stuff. (For example, a way to have a template and all files being based on this template)
• ~~Caching system to avoid reading too many files.~~
• Loop include handling. (Max depth?)
• ~~Make a CLI version of Amie.~~
• Make an executable version of Amie (Electron/NW.js?)
• Allow support for multiple languages based on meta configuration files.
• Add support for amalgamating system include (why not?)
• Mini-preprocessor to avoid writting ignored files

Issues/Feature requests

If you have found an issue with Amie or if you wish something was possible, feel free to open an issue here. Only if it wasn't done before