grunt-clopp

clopp is a cross-language omni-functional preprocessor designed to make building for multiple targets easy

Getting Started

This plugin requires Grunt ~0.4.5

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-clopp --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-clopp');

clopp

Introduction

clopp is a tool that you can add to your toolchain which will allow you to do certain things at compile time of your project. It is designed to be run in a fully fledged production environment.

Why would you want to do things at compile time with JavaScript?

Valid question. There are several use-cases for this kind of thing:

If you have multiple build targets (i.e. a production environment, staging environment, dev environment), you can easily use specific pieces of code per build target.
If you want to disable pieces of code while developing, but want them actived when your app gets compiled, clopp can do that for you.
If you have large chunks of text that you do not want in your development files, but do need in your files when it's compiled, you can easily include a file & clopp does the trick!
If you have any experience with other preprocessors (such as the one in C++), you will understand how useful macros (or other definitions) are.
You can clopp it like it's hot... hehehehe

What languages does clopp support?

JavaScript
TypeScript
HTML (and JavaScript inside HTML, obviously!)
CSS / LESS / SASS
C / C# / C++
Java
PHP

Here is a short example of what clopp can do for you.

// #define fooFactor 3
 
// #ifdef fooFactor
function Foo(a, b)
{
    return a + b * fooFactor;
}
// #endif

Turns into this at compile time:

function Foo(a, b)
{
    return a + b * 3;
}

Configuring clopp

Configuring your files that need to be preprocessed

clopp, as of now, "only" supports the standard Grunt files configuration. We recommend you use the files array format, but also support the object format and the compact format. There is one catch though. The destination needs to be a folder that already exists if you decide to omit inline preprocessing. If you choose to do inline preprocessing (which is further explained down below), clopp will omit your destination folder. It is in the to-do list to have this fixed, luckily.

Here is an example of a basic configuration of clopp using the array format:

grunt.initConfig({
    clopp: 
    {
        preprocess: 
        {
            files:
            [
                { src: 'sourceFile.js', dest: '/destination/' }
            ]
        }
    }
});

Configuring options for the preprocessor

You can configure a lot of options in the preprocessor. Here's the ones that you can define:

options.inline

Type: boolean Default value: false

This is probably the most controversial option you can enable. If you set this to true, the preprocessing will happen in your source files. This is potentionally very dangerous. It can cause severe code loss in your projects if you don't take the right safety precautions.

If you set this to true, you do not have to configure any destination folder anymore.

options.context

Type: object Default value: {} (empty object)

This is an option that you will probably need in your configuration. It allows you to set the context in which the preprocessor operates. It's an object which contains #defines that clopp will use as if you used the #define statement in your source code. Sorry if that explanation is a bit weird, but please try understand this example configuration of options.context:

grunt.initConfig({
    clopp: 
    {
        preprocess: 
        {
            options: {
                context: {
                    myDefinition: "myValue",
                }
            },
            files:
            [
                { src: 'sourceFile.js', dest: '/destination/' }
            ]
        }
    }
});