coz

Flexible generator, which makes your project clean and maintainable.

// Define rendering rule.
module.exports = {
  path: 'have-a-nice-day.txt', // File path to write
  tmpl: '.have-a-nice-day.txt.hbs', // Template file
  force: true, // Overwrite each time
  mode: '444',  // As readyonly file
  data: require('./my-datasource.json') // Data to render
}

Save this as .my-first-bud.bud , then running

$ coz render ".my-first-bud.bud"

will do the magic.

About coz

What's This?

The basic idea of coz is that creating files from files.

1. Writing a meta file called .bud file.
2. Running coz render command.
3. Files will be generated!

What For?

Automation. Generating files makes your project clean and maintainable.

You can define a single datasource and distribute it in various forms.

For example,

• Generate Javascript and Python entity from database definition.
• Generate Web API document and Swift client entity from json schema objects.
• Generate skelton test case files from project files.

Why This?

• Lightweight and fast
  • coz does nothing bud file templating, it's very fast.
• Unopinionated and flexible
• coz could be used to any kind of strings files.
  • Bunch of options to manipulate files.
• Could be used by CLI or programmatically.
  • Simple and extensible
• coz provides ways to customize, like registering your own template engine.

Getting started

Requirements

• node.js

Installation

coz is available as an npm package.

# Install coz as a global module.
$ npm install coz -g

Or you can install it without -g option and use Programmatic API. For more details, see tutorial section "01 - Installing coz".

Quickstart

.who-likes-what.txt.bud (bud file)

/**
 * .who-likes-what.txt.bud
 * This is a bud file for "examples/01-minimum-demo"
 */

// Exports as a Node.js module.
module.exports = {

    // Template string. By default, parsed by Handlebars engine.
    tmpl: '{{#each members}}Hi, my name is {{@key}}. I like {{this}}.\n{{/each}}',

    // Overwrite when already existing.
    force: true,

    // File path to write out.
    path: 'who-likes-what.txt',

    // File permission.
    mode: '444',

    // Data to render.
    data: {
        members: {
            "Mai": "apple",
            "Tom": "Orange",
            "Rita": "Banana"
        }
    }
};

As you see, .bud file is actuary a JavaScript file and could be exported a Node.js module.

Save this file as .who-likes-what.txt.bud and then, run:

# Render the bud file
$ coz render ".who-likes-what.txt.bud"

This will generate a file named who-likes-what.txt.

For more details, see tutorial section "02 - Rendering bud files".

coz provides programmatic API which enables you to execute coz commands from Node.js program.

#!/usr/bin/env node

/**
 * run_rendering.js
 * This is an executable file for "examples/04-from-programmatic-api/run_rendering.js"
 */

var coz = require('coz');

// Render .bud files.
coz.render([
    '**/.*.bud'
], function (err) {
    console.log(err ? err : 'Done!');
});

For more details, see tutorial section "[04 - Using programmatic API][04_using_programmatic_a_p_i_url]".

Specifications

Bud File Specification

A bud contains file meta data like witch template to use, where to render it, what permission to give, and so on.

You can specify bud data by writing .bud file, which is actually a javascript file and could be written in Node.js format.

module.exports = {
  path: 'my_file.txt',
  tmpl: '.my_file.txt.hbs',
  data: require('./.my_data')
}

And bud could be an array like:

module.exports = [
  { path: 'my_file.txt', /* ... */ },
  { path: 'my_other_file.txt', /* ... */ },
]

Or an async function.

module.exports = function(callback){
  myAsync((data) => {
   let error = null
   callback(err, data)
  })
}

For more details, see tutorial section "03 - Mastering coz bud".

Supported Properties

List of properties configurable in bud files.

| Name | Type | Default | Description | | ----- | ----- | ----- | ----- | | engine | string|object | 'handlebars' | Template engine name or engine itself | | cwd | string | process.cwd() | Working directory path | | data | object | | Data which template render with | | mkdirp | boolean | false | Make parent directories if needed | | setup | object | | Optional settings for template engine | | force | boolean | false | Should overwrite file when already exists, or not | | mode | string|number | '644' | Permission of generated files. (eg., '444' for readonly files) | | path | string | | Destination file path. If not provided, guess from bud file path | | tmpl | string|function | 'json' | Template file path or registered template name or template function |

Tutorials

• 01 Installing Coz
• 02 Rendering Bud Files
• 03 Mastering Coz Bud
• 04 Using Programmatic Ap I
• 05 Customizing Coz

About this project

Author

• Taka Okunishi

Donation

Support this project and others by okunishinishi via gratipay.

License

This software is released under the MIT License.

Links

• coz-examples