Skip to content

Commit 1506c74

Browse files
dscdsc
committed
Updates documentation.
1 parent 05ff45d commit 1506c74

File tree

4 files changed

+96
-68
lines changed

4 files changed

+96
-68
lines changed

‎.gitignore

-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,2 @@
1-
settings.md
21
node_modules/
32
!node_modules/seq

‎README.md

+72-60
Original file line numberDiff line numberDiff line change
@@ -23,22 +23,29 @@ Usage is the same as all other `connect` middleware:
2323
server.listen(6969);
2424
````
2525

26+
Of note, earlier versions of `connect` actually came with a module like this, but they do not any longer.
27+
2628

2729
## Settings
2830

29-
The compiler middleware takes a settings object, minimally containing a list of compilers to enable (`enabled`). Most uses will also specify a source directory (`src`).
31+
The compiler middleware takes a settings object, minimally containing a list of compilers to
32+
enable (`enabled`). Most uses will also specify a source directory (`src`).
3033

3134
<table>
32-
<col>
33-
<col width="25%">
34-
<col>
35-
<col width="50%">
3635
<thead>
3736
<tr>
38-
<th>name</th>
39-
<th>type</th>
40-
<th>default</th>
41-
<th>description</th>
37+
<th>
38+
name
39+
</th>
40+
<th>
41+
type
42+
</th>
43+
<th>
44+
default
45+
</th>
46+
<th>
47+
description
48+
</th>
4249
</tr>
4350
</thead>
4451
<tbody>
@@ -49,9 +56,7 @@ The compiler middleware takes a settings object, minimally containing a list of
4956
<td>
5057
<code>String</code>, <code>String[]</code>
5158
</td>
52-
<td>
53-
54-
</td>
59+
<td></td>
5560
<td>
5661
<strong>Required</strong> Enabled compiler id(s). See below for included compilers.
5762
</td>
@@ -78,7 +83,7 @@ The compiler middleware takes a settings object, minimally containing a list of
7883
<code>String</code>
7984
</td>
8085
<td>
81-
<code>src</code><br>
86+
<code>src</code> or<br>
8287
<code>src[0]</code> if Array
8388
</td>
8489
<td>
@@ -90,11 +95,12 @@ The compiler middleware takes a settings object, minimally containing a list of
9095
<strong>roots</strong>
9196
</td>
9297
<td>
93-
<code>{src:dest, ...}</code>, <br> <code>[[src, dest], ...]</code>
98+
<code>{src:dest, ...}</code>,<br>
99+
<code>[[src, dest], ...]</code>
94100
</td>
95101
<td></td>
96102
<td>
97-
Allows you to specify multiple, ordered <code>src</code>-<code>dest</code> pairs. Only one of <code>roots</code> or <code>src</code> is required; <code>roots</code> takes precedence over <code>src</code> if present.
103+
Allows you to specify multiple, ordered <code>src</code>-<code>dest</code> pairs. One of <code>roots</code> or <code>src</code> is required; <code>roots</code> takes precedence over <code>src</code> if present.
98104
</td>
99105
</tr>
100106
<tr>
@@ -105,7 +111,7 @@ The compiler middleware takes a settings object, minimally containing a list of
105111
<code>String</code> , <code>Number</code>
106112
</td>
107113
<td>
108-
<code>warn</code>
114+
<code>WARN</code>
109115
</td>
110116
<td>
111117
Logging verbosity. Valid values (case-insensitive): <code>error</code>, <code>warn</code>, <code>info</code>, <code>debug</code>, <code>silent</code>, or a numeric constant (as found in <code>LOG</code>).
@@ -207,6 +213,20 @@ The compiler middleware takes a settings object, minimally containing a list of
207213
If <code>true</code>-y, directories are resolved with the supplied filename, where <code>true</code> maps to <code>'index.html'</code>.
208214
</td>
209215
</tr>
216+
<tr>
217+
<td>
218+
<strong>ignore</strong>
219+
</td>
220+
<td>
221+
<code>RegExp</code>
222+
</td>
223+
<td>
224+
<code>/\.(jpe?g!gif!png)$/i</code>
225+
</td>
226+
<td>
227+
Requests matching this pattern are short-circuit ignored, and no compiler matching occurs.
228+
</td>
229+
</tr>
210230
<tr>
211231
<td>
212232
<strong>allowed_methods</strong>
@@ -240,56 +260,48 @@ The compiler middleware takes a settings object, minimally containing a list of
240260

241261
## Compilers
242262

243-
- ### CoffeeScriptCompiler
244-
245-
246-
- ### CocoCompiler
247-
248-
249-
- ### CommonJSCompiler
250-
251-
252-
- ### UglifyCompiler
253-
254-
255-
- ### JadeCompiler
256-
257-
258-
- ### StylusCompiler
259-
260-
261-
- ### LessCompiler
262-
263-
264-
- ### SassJSCompiler
265-
266-
267-
- ### SassRubyCompiler
268-
269-
270-
- ### JisonCompiler
271-
272-
273-
- ### YamlCompiler
274-
275-
263+
To enable a compiler, you specify its `id`, which you can get from the handy list that follows. Some
264+
compilers take options, which you pass using the `options` setting using the compiler `id` as the
265+
key.
276266

277-
## API
267+
For example, to disable the `bare` option for the CoffeeScript compiler, you'd do something like:
278268

279-
- ### CompilerMiddleware(settings={}, ...custom)
280-
281-
282-
- ### Compiler
283-
284-
285-
- ### ExternalCompiler
286-
287-
269+
````js
270+
server = connect.createServer(
271+
compiler({
272+
src : 'src'
273+
dest : 'var'
274+
enabled : [ 'coffee' ],
275+
options : {
276+
'coffee' : {
277+
'bare' : false
278+
}
279+
}
280+
}),
281+
connect.static(__dirname + '/public'),
282+
connect.static(__dirname + '/var')
283+
)
284+
````
288285

286+
### Compiler IDs
289287

288+
- [CoffeeScript](http://coffeescript.org/) Compiler: `coffee`
289+
- [Coco](http://satyr.github.com/coco/) Compiler: `coco`
290+
- [Uglify](https://github.com/mishoo/UglifyJS) Compiler: `uglify`
291+
- [Jade](http://jade-lang.com/) Compiler: `jade`
292+
- [Stylus](http://learnboost.github.com/stylus/) Compiler: `stylus`
293+
- [Less](http://lesscss.org/) Compiler: `less`
294+
- [Sass](http://sass-lang.com/) Compiler: `sass` -- Using [sass.js](https://github.com/visionmedia/sass.js).
295+
- [SassRuby](http://sass-lang.com/) Compiler: `sass_ruby` -- External compiler using a shell command to
296+
the [Ruby version of Sass](http://sass-lang.com/download.html) (which you must install that part yourself).
297+
- [Jison](http://zaach.github.com/jison/) Compiler: `jison`
290298

291-
## Feedback
292299

300+
## Feedback
293301

302+
Find a bug or want to contribute? Open a ticket on [github](http://github.com/dsc/connect-compiler).
303+
You're also welcome to send me email at [[email protected]](mailto:[email protected]?subject=connect-compiler).
294304

305+
If you're interested in contributing, note that at the moment, a version of `node-seq` is checked in under
306+
`node_modules` while we wait for a pull request to be pulled into `master`.
295307

‎TODO.md

+3-7
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,15 @@
11
# todo
22

3+
## bugs
34

4-
## to ship
5+
## later
56

6-
- Validate compiler module exists on startup
7+
- Validate compiler module exists on startup in a way that still allows `@wraps` to work right
78
- Restructure middleware responder to use events to trigger compiler phases, remove `seq` due to need of `@die`. (State machine?)
89
- Allow nested `enabled` list for a more sane `cascade`
910
- Rename `enabled` to `compilers`
1011
- Allow entries in `compilers` to be an identifier or a options/config object
1112
- Add post-`write()` cleanup/finally event (which fires whether successful or not).
12-
13-
- Remove `yaml-python`, `CommonJS` compilers and create a `connect-compiler-extras` package for myself.
14-
15-
16-
## later
1713
- Compile `./src` (coco) -> `./lib` (js)
1814
- Move compilers to `lib/compilers.co`
1915

‎settings.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
2+
| name | type | default | description |
3+
| -------------------- | --------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
4+
| **enabled** | `String`, `String[]` | | **Required** Enabled compiler id(s). See below for included compilers. |
5+
| **src** | `String`, `String[]` | cwd | Directories to search for source files to compile. |
6+
| **dest** | `String` | `src` or <br/> `src[0]` if Array | Directory to write compiled result. |
7+
| **roots** | `{src:dest, ...}`, <br/> `[[src, dest], ...]` | | Allows you to specify multiple, ordered `src`-`dest` pairs. One of `roots` or `src` is required; `roots` takes precedence over `src` if present. |
8+
| **log_level** | `String` , `Number` | `WARN` | Logging verbosity. Valid values (case-insensitive): `error`, `warn`, `info`, `debug`, `silent`, or a numeric constant (as found in `LOG`). |
9+
| **create_dirs** | `Boolean` | `true` | Creates intermediate directories for destination files. |
10+
| **mount** | `String` | | Prefix trimmed off request path before matching/processing. |
11+
| **delta** | `Number` | `0` | Delta `mtime` (in seconds) required for a derived file to be considered stale, and therefore recompiled. By default, any change will cause a file to be recompiled on next request. |
12+
| **expires** | `Boolean` | `false` | Automatically treat files as stale if this old in secs. |
13+
| **external_timeout** | `Number` | `3000` | Milliseconds after which to kill subprocess commands. |
14+
| **cascade** | `Boolean` | `false` | Invoke all compilers that match? otherwise, only first. |
15+
| **resolve_index** | `Boolean` , `String` | `false` | If `true`-y, directories are resolved with the supplied filename, where `true` maps to `'index.html'`. |
16+
| **ignore** | `RegExp` | `/\.(jpe?g!gif!png)$/i` | Requests matching this pattern are short-circuit ignored, and no compiler matching occurs. |
17+
| **allowed_methods** | `String[]` | `['GET']` | HTTP methods compiler should process. This setting is global-only -- per-compiler overrides specified via `options` will have no effect. |
18+
| **options** | `{compilerId:settings, ...}` | | Hash of additional per-compiler options, mapped by compiler id. Each compiler is supplied a copy of the `settings` object; if additional options are supplied in this way for a given compiler, they will be merged into the settings (and override any colliding top-level keys). |
19+
20+
21+

0 commit comments

Comments
 (0)