amie/README.md

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

# 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.
<br>But I've never found a good and easy-to-use amalgamation tool.
<br>That's why I decided to make my own using NodeJS. **Amie** is now alive.
<br>This currently only work with C++ and has very poor features capabilities but I'm working on it, lots of stuff planned!

# Installation
```shell
$ 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:

```shell
$ 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_)

<br>`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.

<br>Here is an example of the _non-file-writing_ version:

```js
'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:

```js
'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!_**
><br>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**.
<br>The defaults are written both in the documentation and in the hash below it.
<br>The only required property is `input`.

```js
/**
 * @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](https://electron.atom.io/)/[NW.js](https://nwjs.io/)?)
- 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](https://github.com/Telokis/Amie/issues). *Only if it wasn't done before*