1 | coz
|
2 | ==========
|
3 |
|
4 |
|
5 | This file is generated by ape-tmpl. Do not update manually.
|
6 | --->
|
7 |
|
8 |
|
9 | <a name="badges"></a>
|
10 |
|
11 | [![Build Status][bd_travis_shield_url]][bd_travis_url]
|
12 | [![Code Climate][bd_codeclimate_shield_url]][bd_codeclimate_url]
|
13 | [![Code Coverage][bd_codeclimate_coverage_shield_url]][bd_codeclimate_url]
|
14 | [![Dependency Status][bd_gemnasium_shield_url]][bd_gemnasium_url]
|
15 | [![npm Version][bd_npm_shield_url]][bd_npm_url]
|
16 |
|
17 | [bd_repo_url]: https://github.com/coz-repo/coz
|
18 | [bd_travis_url]: http://travis-ci.org/coz-repo/coz
|
19 | [bd_travis_shield_url]: http://img.shields.io/travis/coz-repo/coz.svg?style=flat
|
20 | [bd_travis_com_url]: http://travis-ci.com/coz-repo/coz
|
21 | [bd_travis_com_shield_url]: https://api.travis-ci.com/coz-repo/coz.svg?token=
|
22 | [bd_license_url]: https://github.com/coz-repo/coz/blob/master/LICENSE
|
23 | [bd_codeclimate_url]: http://codeclimate.com/github/coz-repo/coz
|
24 | [bd_codeclimate_shield_url]: http://img.shields.io/codeclimate/github/coz-repo/coz.svg?style=flat
|
25 | [bd_codeclimate_coverage_shield_url]: http://img.shields.io/codeclimate/coverage/github/coz-repo/coz.svg?style=flat
|
26 | [bd_gemnasium_url]: https://gemnasium.com/coz-repo/coz
|
27 | [bd_gemnasium_shield_url]: https://gemnasium.com/coz-repo/coz.svg
|
28 | [bd_npm_url]: http://www.npmjs.org/package/coz
|
29 | [bd_npm_shield_url]: http://img.shields.io/npm/v/coz.svg?style=flat
|
30 | [bd_standard_url]: http://standardjs.com/
|
31 | [bd_standard_shield_url]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
|
32 |
|
33 |
|
34 |
|
35 |
|
36 |
|
37 | <a name="description"></a>
|
38 |
|
39 | Flexible generator, which makes your project clean and maintainable.
|
40 |
|
41 |
|
42 |
|
43 |
|
44 |
|
45 | <a name="overview"></a>
|
46 |
|
47 |
|
48 | <a href="http://coz-repo.github.io/coz/homepage"><img style="height:128px;" src="doc/images/coz-banner.png" height="128"/></a>
|
49 |
|
50 |
|
51 | ```javascript
|
52 | // Define rendering rule.
|
53 | module.exports = {
|
54 | path: 'have-a-nice-day.txt', // File path to write
|
55 | tmpl: '.have-a-nice-day.txt.hbs', // Template file
|
56 | force: true, // Overwrite each time
|
57 | mode: '444', // As readyonly file
|
58 | data: require('./my-datasource.json') // Data to render
|
59 | }
|
60 | ```
|
61 |
|
62 | Save this as ***.my-first-bud.bud*** , then running
|
63 |
|
64 | ```bash
|
65 | $ coz render ".my-first-bud.bud"
|
66 | ```
|
67 |
|
68 | will do the magic.
|
69 |
|
70 |
|
71 |
|
72 |
|
73 |
|
74 |
|
75 | <a name="sections"></a>
|
76 |
|
77 |
|
78 |
|
79 | <a name="section-doc-guides-01-about-md"></a>
|
80 |
|
81 | About coz
|
82 | ------
|
83 |
|
84 | ### What's This?
|
85 |
|
86 | The basic idea of coz is that creating files from files.
|
87 |
|
88 | 1. Writing a meta file called [.bud file](#spec-bud-spec).
|
89 | 2. Running `coz render` command.
|
90 | 3. Files will be generated!
|
91 |
|
92 | <img style="height:256px;" src="doc/images/coz-outline.jpg" height="256">
|
93 |
|
94 |
|
95 | ### What For?
|
96 |
|
97 | Automation. Generating files makes your project clean and maintainable.
|
98 |
|
99 | You can define a single datasource and distribute it in various forms.
|
100 |
|
101 | For example,
|
102 |
|
103 | + Generate Javascript and Python entity from database definition.
|
104 | + Generate Web API document and Swift client entity from json schema objects.
|
105 | + Generate skelton test case files from project files.
|
106 |
|
107 |
|
108 | ### Why This?
|
109 |
|
110 | + **Lightweight and fast**
|
111 | + coz does nothing bud file templating, it's very fast.
|
112 | + **Unopinionated and flexible**
|
113 | + coz could be used to any kind of strings files.
|
114 | + Bunch of options to manipulate files.
|
115 | + Could be used by CLI or programmatically.
|
116 | + **Simple and extensible**
|
117 | + coz provides ways to customize, like registering your own template engine.
|
118 |
|
119 |
|
120 |
|
121 |
|
122 |
|
123 |
|
124 |
|
125 |
|
126 | <a name="section-doc-guides-02-howto-md"></a>
|
127 |
|
128 | Getting started
|
129 | ------
|
130 |
|
131 | ### Requirements
|
132 |
|
133 | + [node.js][nodejs_url]
|
134 |
|
135 |
|
136 | ### Installation
|
137 |
|
138 | coz is available as an [npm][npm_url] package.
|
139 |
|
140 | ```bash
|
141 | # Install coz as a global module.
|
142 | $ npm install coz -g
|
143 | ```
|
144 |
|
145 | Or you can install it without `-g` option and use [Programmatic API](#programmatic-api).
|
146 | For more details, see tutorial section "[01 - Installing coz][01_installing_coz_url]".
|
147 |
|
148 |
|
149 | ### Quickstart
|
150 |
|
151 | **.who-likes-what.txt.bud** (bud file)
|
152 | ```javascript
|
153 | /**
|
154 | * .who-likes-what.txt.bud
|
155 | * This is a bud file for "examples/01-minimum-demo"
|
156 | */
|
157 |
|
158 | // Exports as a Node.js module.
|
159 | module.exports = {
|
160 |
|
161 | // Template string. By default, parsed by Handlebars engine.
|
162 | tmpl: '{{#each members}}Hi, my name is {{@key}}. I like {{this}}.\n{{/each}}',
|
163 |
|
164 | // Overwrite when already existing.
|
165 | force: true,
|
166 |
|
167 | // File path to write out.
|
168 | path: 'who-likes-what.txt',
|
169 |
|
170 | // File permission.
|
171 | mode: '444',
|
172 |
|
173 | // Data to render.
|
174 | data: {
|
175 | members: {
|
176 | "Mai": "apple",
|
177 | "Tom": "Orange",
|
178 | "Rita": "Banana"
|
179 | }
|
180 | }
|
181 | };
|
182 |
|
183 | ```
|
184 |
|
185 | As you see, `.bud` file is actuary a JavaScript file and could be exported a Node.js module.
|
186 |
|
187 | Save this file as `.who-likes-what.txt.bud` and then, run:
|
188 |
|
189 | ```bash
|
190 | # Render the bud file
|
191 | $ coz render ".who-likes-what.txt.bud"
|
192 | ```
|
193 |
|
194 | This will generate a file named `who-likes-what.txt`.
|
195 |
|
196 | For more details, see tutorial section "[02 - Rendering bud files][02_rendering_bud_files_url]".
|
197 |
|
198 |
|
199 | <a name="programmatic-api" />
|
200 | ### Programmatic API
|
201 |
|
202 | coz provides programmatic API which enables you to execute coz commands from Node.js program.
|
203 |
|
204 | ```javascript
|
205 | #!/usr/bin/env node
|
206 |
|
207 | /**
|
208 | * run_rendering.js
|
209 | * This is an executable file for "examples/04-from-programmatic-api/run_rendering.js"
|
210 | */
|
211 |
|
212 | var coz = require('coz');
|
213 |
|
214 | // Render .bud files.
|
215 | coz.render([
|
216 | '**/.*.bud'
|
217 | ], function (err) {
|
218 | console.log(err ? err : 'Done!');
|
219 | });
|
220 | ```
|
221 |
|
222 | For more details, see tutorial section "[04 - Using programmatic API][04_using_programmatic_a_p_i_url]".
|
223 |
|
224 |
|
225 | [nodejs_url]: https://nodejs.org/en/
|
226 | [npm_url]: https://www.npmjs.com/
|
227 |
|
228 |
|
229 |
|
230 |
|
231 |
|
232 |
|
233 | <a name="section-doc-guides-03-spec-md"></a>
|
234 |
|
235 | Specifications
|
236 | ---------
|
237 |
|
238 | <a name="spec-bud-spec"></a>
|
239 | ### Bud File Specification
|
240 |
|
241 | A bud contains file meta data like witch template to use, where to render it, what permission to give, and so on.
|
242 |
|
243 | You can specify bud data by writing `.bud` file, which is actually a javascript file and could be written in Node.js format.
|
244 |
|
245 | ```javascript
|
246 | module.exports = {
|
247 | path: 'my_file.txt',
|
248 | tmpl: '.my_file.txt.hbs',
|
249 | data: require('./.my_data')
|
250 | }
|
251 | ```
|
252 |
|
253 | And bud could be an array like:
|
254 |
|
255 | ```javascript
|
256 | module.exports = [
|
257 | {path: 'my_file.txt', /*...*/},
|
258 | {path: 'my_other_file.txt', /*...*/},
|
259 | ]
|
260 | ```
|
261 |
|
262 | Or an async function.
|
263 |
|
264 | ```javascript
|
265 | module.exports = function(callback){
|
266 | myAsync(function(data){
|
267 | var error = null;
|
268 | callback(err, data);
|
269 | });
|
270 | }
|
271 | ```
|
272 |
|
273 | For more details, see tutorial section "[03 - Mastering coz bud][03_mastering_coz_bud_url]".
|
274 |
|
275 | ##### Supported Properties
|
276 |
|
277 | List of properties configurable in bud files.
|
278 |
|
279 | | Name | Type | Default | Description |
|
280 | | ----- | ----- | ----- | ----- |
|
281 | | `engine` | string|object | 'handlebars' | Template engine name or engine itself |
|
282 | | `cwd` | string | process.cwd() | Working directory path |
|
283 | | `data` | object | | Data which template render with |
|
284 | | `mkdirp` | boolean | false | Make parent directories if needed |
|
285 | | `setup` | object | | Optional settings for template engine |
|
286 | | `force` | boolean | false | Should overwrite file when already exists, or not |
|
287 | | `mode` | string|number | '644' | Permission of generated files. (eg., '444' for readonly files) |
|
288 | | `path` | string | | Destination file path. If not provided, guess from bud file path |
|
289 | | `tmpl` | string|function | 'json' | Template file path or registered template name or template function |
|
290 |
|
291 |
|
292 |
|
293 |
|
294 |
|
295 |
|
296 |
|
297 |
|
298 | <a name="section-doc-guides-04-tutorials-md"></a>
|
299 |
|
300 | Tutorials
|
301 | ------
|
302 |
|
303 | + [01 Installing Coz][01_installing_coz_url]
|
304 | + [02 Rendering Bud Files][02_rendering_bud_files_url]
|
305 | + [03 Mastering Coz Bud][03_mastering_coz_bud_url]
|
306 | + [04 Using Programmatic a P I][04_using_programmatic_a_p_i_url]
|
307 | + [05 Customizing Coz][05_customizing_coz_url]
|
308 |
|
309 |
|
310 | [01_installing_coz_url]: https://github.com/coz-repo/coz/blob/master/doc/tutorial/01%20-%20Installing%20coz.md
|
311 | [02_rendering_bud_files_url]: https://github.com/coz-repo/coz/blob/master/doc/tutorial/02%20-%20Rendering%20bud%20files.md
|
312 | [03_mastering_coz_bud_url]: https://github.com/coz-repo/coz/blob/master/doc/tutorial/03%20-%20Mastering%20coz%20bud.md
|
313 | [04_using_programmatic_a_p_i_url]: https://github.com/coz-repo/coz/blob/master/doc/tutorial/04%20-%20Using%20programmatic%20API.md
|
314 | [05_customizing_coz_url]: https://github.com/coz-repo/coz/blob/master/doc/tutorial/05%20-%20Customizing%20coz.md
|
315 |
|
316 |
|
317 |
|
318 |
|
319 |
|
320 |
|
321 | <a name="section-doc-guides-05-project-md"></a>
|
322 |
|
323 | About this project
|
324 | --------
|
325 |
|
326 | ### Author
|
327 |
|
328 | + [Taka Okunishi](http://okunishitaka.com)
|
329 |
|
330 | ### Donation
|
331 |
|
332 | Support this project and [others by okunishinishi][my_gratipay_url] via [gratipay][my_gratipay_url].
|
333 |
|
334 | [<img src="https://cdn.rawgit.com/gratipay/gratipay-badge/2.3.0/dist/gratipay.svg" alt="Support via Gratipay"/>][my_gratipay_url]
|
335 |
|
336 | [my_gratipay_url]: https://gratipay.com/okunishinishi/
|
337 |
|
338 |
|
339 |
|
340 |
|
341 |
|
342 |
|
343 |
|
344 |
|
345 |
|
346 | <a name="license"></a>
|
347 |
|
348 | License
|
349 | -------
|
350 | This software is released under the [MIT License](https://github.com/coz-repo/coz/blob/master/LICENSE).
|
351 |
|
352 |
|
353 |
|
354 |
|
355 |
|
356 | <a name="links"></a>
|
357 |
|
358 | Links
|
359 | ------
|
360 |
|
361 | + [coz-examples][coz_examples_url]
|
362 |
|
363 | [coz_examples_url]: https://github.com/coz-repo/coz-examples#04-from-programmatic-api
|
364 |
|
365 |
|