Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 288 lines (193 sloc) 9.709 kB
0267575 @Meettya * add gitter bage
authored
1 [![Join the chat at https://gitter.im/Meettya/clinch](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/Meettya/clinch?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
a1e07fd @Meettya * before cached loader add
authored
2 [![Dependency Status](https://gemnasium.com/Meettya/clinch.png)](https://gemnasium.com/Meettya/clinch)
b6d1018 @Meettya * add travis bage
authored
3 [![Build Status](https://travis-ci.org/Meettya/clinch.png?branch=master)](https://travis-ci.org/Meettya/clinch)
d85a3ba @Meettya * fist beta out
authored
4
5 # clinch
6
a0c737e @Meettya * fix dependencies, Readme, bump vers
authored
7 YA ComonJS to browser packer tool, well-suited for tiny widgets by small overhead and big app by module replacement, node-environment emulations and multi-exports.
c8a43d6 @Meettya * fix error support
authored
8
ea79766 @Meettya * update readme
authored
9 In addition it rapidly compiles the first pass of packaging and has an elegant solution to caching data.
10
11 ## BRAKING CHANGES
12
13 ### 1.0.1
14
15 A lot of processors moved to separate modules.
16
17 It may brake you old bundler and require some changes - add used processor to dependencies, install it and declare via `.addPlugin()` - see example section.
18
ffde88a @Meettya * recompile to js and link package to it
authored
19 ## what in a box?
c97596a @Meettya * add jade settings and docs about it
authored
20
21 - `.js` - just put it to bundle as is
22 - `.json` - wrap in `module.exports` as node do it on `require('file.json')`
23
ea79766 @Meettya * update readme
authored
24 Yes, with version 1.0.1 box fairly empty and the default itself ** clinch ** can only work with these two types of files.
d502d87 @Meettya * add registerProcessor() method
authored
25
ea79766 @Meettya * update readme
authored
26 ## where another processors?
d502d87 @Meettya * add registerProcessor() method
authored
27
ea79766 @Meettya * update readme
authored
28 All other processors moved into separate modules. At the moment, the list is as follows:
84a827e @Meettya * add Handlebars as addon example, update docs, add test
authored
29
ea79766 @Meettya * update readme
authored
30 - [clinch.coffee](https://github.com/Meettya/clinch.coffee) - `.coffee` - compile to JavaScript
31 - [clinch.eco](https://github.com/Meettya/clinch.eco) - `.eco` - precompile to JavaScript function
32 - [clinch.jade](https://github.com/Meettya/clinch.jade) - `.jade` - precompile it in [client-mode](https://github.com/visionmedia/jade#a4) way
33 - [clinch.jsx](https://github.com/Meettya/clinch.jsx) - `.jsx` - compile [React '.jsx'](http://facebook.github.io/react/index.html) to JavaScript
34 - [clinch.csbx](https://github.com/Meettya/clinch.csbx) - `.csbx` - compile '.jsx' on Coffee with backticks to JavaScript (yes, we do it)
977a979 @Meettya * fix filters & add .jade support
authored
35
ea79766 @Meettya * update readme
authored
36 Separation of code done in order to provide flexibility in target versions required you to processors. Ie for example, you can continue to use the processor with a version of `.csbx` ** React ** 0.11.1 for the old project and to take for the new 0.14.1, simply prescribe the right version you react-processor ** clinch ** in your package.json project.
977a979 @Meettya * fix filters & add .jade support
authored
37
ea79766 @Meettya * update readme
authored
38 ## what about my custom template engine?
19c9f9c @Meettya * update docs
authored
39
ea79766 @Meettya * update readme
authored
40 This possibility almost exists - **clinch** from 0.2.5 have API for third party processors, but template engine must support template-to-function precompilation.
19c9f9c @Meettya * update docs
authored
41
ea79766 @Meettya * update readme
authored
42 More info and example - below at description of methods `addPlugin()` and `registerProcessor()`
19c9f9c @Meettya * update docs
authored
43
ea79766 @Meettya * update readme
authored
44 For additional example - see [using Handelbars](https://github.com/Meettya/clinch/wiki/Handlebars-template-engine-support) - yap, now [Hadlebars](http://handlebarsjs.com/) supported as add-on.
19c9f9c @Meettya * update docs
authored
45
8a0a02d @Meettya * all ready to beta
authored
46 ## installation
47
ea79766 @Meettya * update readme
authored
48 npm install clinch clinch.coffee
8a0a02d @Meettya * all ready to beta
authored
49
50 ## example
51
52 #!/usr/bin/env coffee
ea79766 @Meettya * update readme
authored
53 Clinch = require 'clinch'
54 clinch_coffee = require 'clinch.coffee'
55
e01de39 @Meettya * update docs & example
authored
56 packer = new Clinch runtime : on
ea79766 @Meettya * update readme
authored
57 # register '.coffee' processor
58 packer.addPlugin clinch_coffee
59
8a0a02d @Meettya * all ready to beta
authored
60 pack_config =
be127bb @Meettya * fix Readme
authored
61 package_name : 'my_package'
8a0a02d @Meettya * all ready to beta
authored
62 bundle :
63 main : "#{__dirname}/hello_world"
307a033 @Meettya * replace 'buld' -> 'build'
authored
64 packer.buildPackage pack_config, (err, data) ->
8a0a02d @Meettya * all ready to beta
authored
65 if err
66 console.log 'Builder, err: ', err
67 else
68 console.log 'Builder, data: \n', data
69
a0c737e @Meettya * fix dependencies, Readme, bump vers
authored
70 Content of `./hellow_world`
71
72 ###
73 This is 'Hello World!' example
74 ###
75 module.exports =
76 hello_world : -> 'Hello World!'
77
78 Now `data` contain something like this
79
80 (function() {
e01de39 @Meettya * update docs & example
authored
81 'use strict';
82
83 var dependencies, sources, require, modules_cache = {};
84 dependencies = {};
a0c737e @Meettya * fix dependencies, Readme, bump vers
authored
85
e01de39 @Meettya * update docs & example
authored
86 sources = {
87 "JPGt0": function(exports, module, require) {
a0c737e @Meettya * fix dependencies, Readme, bump vers
authored
88 // /Users/meettya/github/clinch/example/hello_world/hello_world.coffee
ea79766 @Meettya * update readme
authored
89
a0c737e @Meettya * fix dependencies, Readme, bump vers
authored
90 /*
91 This is 'Hello World!' example
ea79766 @Meettya * update readme
authored
92 */
a0c737e @Meettya * fix dependencies, Readme, bump vers
authored
93 module.exports = {
94 hello_world: function() {
95 return 'Hello World!';
96 }
97 };
e01de39 @Meettya * update docs & example
authored
98
a0c737e @Meettya * fix dependencies, Readme, bump vers
authored
99 }};
ea79766 @Meettya * update readme
authored
100
e01de39 @Meettya * update docs & example
authored
101 if(this.clinch_runtime_v2 == null) {
102 throw Error("Resolve clinch runtime library version |2| first!");
103 }
104
105 require = this.clinch_runtime_v2.require_builder.call(this, dependencies, sources, modules_cache);
106
107 /* bundle export */
a0c737e @Meettya * fix dependencies, Readme, bump vers
authored
108 this.my_package = {
e01de39 @Meettya * update docs & example
authored
109 main : require("JPGt0")
110 };
a0c737e @Meettya * fix dependencies, Readme, bump vers
authored
111 }).call(this);
112
113 And in browser function may be accessed in this way
114
115 hello_world = my_package.main.hello_world
116
c97596a @Meettya * add jade settings and docs about it
authored
117 ## API
8a0a02d @Meettya * all ready to beta
authored
118
119 **clinch** have minimalistic API
120
c97596a @Meettya * add jade settings and docs about it
authored
121 ### constructor
122
123 packer = new Clinch clinch_options
124
125 `clinch_options` - Clinch settings
126
127
307a033 @Meettya * replace 'buld' -> 'build'
authored
128 ### buildPackage()
a5533bf @Meettya * add flushCache()
authored
129
307a033 @Meettya * replace 'buld' -> 'build'
authored
130 packer.buildPackage package_config, cb
3365ece @Meettya * add all for package_name
authored
131 # or old form, will be deprecated in new version
307a033 @Meettya * replace 'buld' -> 'build'
authored
132 packer.buildPackage package_name, package_config, cb
8a0a02d @Meettya * all ready to beta
authored
133
be127bb @Meettya * fix Readme
authored
134 `package_name` - root bundle package name (like `$` for jQuery), remember about name collisions, may be omitted. Will be deprecated in new versions, use `package_config.package_name`
8a0a02d @Meettya * all ready to beta
authored
135
136 `package_config` - package settings
137
138 `cb` - standard callback, all in **clinch** are async
139
ea79766 @Meettya * update readme
authored
140 ### addPlugin()
141
142 packer.addPlugin clinch_plugin
143
144 This method allows you to connect plug-ins, in fact being a syntactic sugar to `registerProcessor ()`
145
146 `clinch_plugin` - plugin-processor for selected files
147
148 Example:
149
150 # declare plugin in place
151 econ_plugin =
152 extension : '.econ'
153 processor : (file_content, filename, cb) ->
154 content = Eco.precompile file_content
155 cb null, "module.exports = #{content}"
156
157 # add .econ processor
158 packer.addPlugin econ_plugin
159
d502d87 @Meettya * add registerProcessor() method
authored
160 ### registerProcessor()
161
162 packer.registerProcessor file_extention, fn
163
164 This method allow to register any file content processor, which will be used to process files with `file_extention`.
165
166 `file_extention` - file extension to proceed
8157796 @Meettya * fix mistype in docs
authored
167
d502d87 @Meettya * add registerProcessor() method
authored
168 `fn` - processor function
169
170 Example:
171
172 # add .econ processor
173 packer.registerProcessor '.econ', (file_content, filename, cb) ->
174 content = Eco.precompile file_content
175 cb null, "module.exports = #{content}"
176
177 At now **clinch** will be compile all required `.econ` files with this function.
178
179 And in module code:
180
181 template = require './template' # ./template.econ, extension may be omitted
182 res = template data # res now is some html-contented string
183
ea79766 @Meettya * update readme
authored
184 In fact, similar to the method `addPlugin ()`.
185
a5533bf @Meettya * add flushCache()
authored
186 ### flushCache()
187
188 packer.flushCache()
189
190 This method will force flush packer cache. As usually **clinch** flush cache if files changed, but for some rare cases its available to force it.
191
48236e8 @Meettya * add getPackageFilesList(), refactor
authored
192 ### getPackageFilesList()
193
194 packer.getPackageFilesList package_config, cb
195
196 This method will return an Array of all files, used in package building process.
197 May be used for custom `watch` implementation or in other cases
198
c97596a @Meettya * add jade settings and docs about it
authored
199 ## Settings
200
201 ### clinch_options
f7fcf86 @Meettya * Add runtime & cache docs, improve tests
authored
202 log : off # will add verbose output, but now not realized yet
203 strict : on # knob for 'use strict;' in bundle header
204 inject : on # if changed to 'off' - bundle will not to inject 'package_name' to global
205 runtime : off # use internal boilerplate code, or as external file
206 cache_modules : on # by default all resolved by 'require' file will be cached, if you have some problem - turn cache off and notice me
c97596a @Meettya * add jade settings and docs about it
authored
207
8a0a02d @Meettya * all ready to beta
authored
208 ### package_config
3365ece @Meettya * add all for package_name
authored
209 ###
210 May be omitted. If omitted - inject all bundle members to global OR, if `inject : off` in package settings - make all bundle members local for bundle (it may be usefully in case of widgets with self-detection)
211 ###
212 package_name : 'bundle_pack_name'
213
214 # bundle settings
215 strict : on # bundle knob for 'use strict;' in bundle header
216 inject : on # if changed to 'off' - bundle will not to inject 'package_name' to global
f7fcf86 @Meettya * Add runtime & cache docs, improve tests
authored
217 runtime : off # use internal boilerplate code, or as external file
218 cache_modules : on # by default all resolved by 'require' file will be cached, if you have some problem - turn cache off and notice me
219
8a0a02d @Meettya * all ready to beta
authored
220
221 ###
222 At least one key must be exists
223 name -> code place
224 this keys was be exported when script loaded
225 bundle =
226 main : function(){...}
227 helper : function(){...}
228
229 later in code
230
231 main = bundle.main
232 ###
233
234 bundle :
235 main : './src'
236 helper : './src/lib/helper'
237
238 ###
239 This is local for code variables, to imitate node.js environment,
240 or replace somthing
241 Important - keys will be used as variable name, so any strange things may happened
242 if it not old plain string, remember it!!!
243 ###
244 environment :
245 process : './node/js-process'
246 console : './node_modules/console-shim'
247
248 ###
249 This part replace modules with browser-spec one
250 ###
251 replacement :
252 util : './node_modules/js-util'
e01de39 @Meettya * update docs & example
authored
253 lodash : -> @_ # yes, its allowed to use function instead of file (`this` will be pointed to global scoop)
8a0a02d @Meettya * all ready to beta
authored
254
255 ###
256 this is list of modules, which is not be placed in bungle
257 ###
258 exclude : [
259 'underscore'
260 ]
261
262 ###
263 This is list of modules, which we are not check for require in it
264 save time with huge pre-bulded libraries, like `lodash` or `jquery`
265 if we are decide to place it in bundle
266 ###
267 requireless : [
268 'lodash'
269 ]
270
271 ## Examples
272
273 See `example` or `test` dirs.
274
a0c737e @Meettya * fix dependencies, Readme, bump vers
authored
275 Also some examples will be available online at [clinch_demo](http://meettya.github.com/clinch_demo/index.html).
276
277 Also **clinch** will be used to browser-pack [TinyData](http://meettya.github.com/TinyData/demo.html), see sources and [packed lib](https://github.com/Meettya/TinyData/blob/master/lib_browser/tinydata.js)
278
8a0a02d @Meettya * all ready to beta
authored
279 ## See also
280
281 Its exists README_ru version of documentation, with more information.
f7fcf86 @Meettya * Add runtime & cache docs, improve tests
authored
282
283 ## Acknowledgement
284
285 [Shuvalov Anton](https://github.com/shuvalov-anton)
9dd5618 @Meettya * Fix Acknowledgement
authored
286
0267575 @Meettya * add gitter bage
authored
287 [Simakov Konstantin](https://github.com/GigabyteTheOne)
Something went wrong with that request. Please try again.