Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 214 lines (143 sloc) 5.896 kb
6042bf0 Dan Dean Update documentation
authored
1 fspkg: File System Packager
c587d3e Dan Dean Initial commit
authored
2 =============================
3
6042bf0 Dan Dean Update documentation
authored
4 `fspkg` takes a directory or file as input and transforms it into a CommonJS module, JSON string or JavaScript object. `fspkg` is great for:
5
6 * bundling mustache templates for inclusion in a client-side application.
7 * encoding images and other assets as Data URIs.
8
9 For example, I use `fspkg` with <code>[modulr-node](https://github.com/tobie/modulr-node)</code> to compile my mustache templates for use in a [backbone.js](http://documentcloud.github.com/backbone/) application. This lets me do this within my backbone views (assuming I've packaged up my "views" directory:
10
11 ```js
12 var MyView = Backbone.View.extend({
13 ...
14 render: function() {
dba8f44 Dan Dean Missing quotes around key in documentation.
authored
15 var template = require('views')['layouts/index.mustache'];
6042bf0 Dan Dean Update documentation
authored
16 var html = Mustache.to_html(template, this.model);
17 this.el.html(html);
18 },
19 ...
20 });
21 ```
22
a11cb9f Dan Dean Add new filter API info
authored
23 Command-line API
24 ----------------
6042bf0 Dan Dean Update documentation
authored
25
a11cb9f Dan Dean Add new filter API info
authored
26 ```sh
27 Usage: fspkg [options] <source>
28
29 Options:
30
31 -h, --help output usage information
32 -V, --version output the version number
33 -s, --save-path [savePath] save path: prints to stdout if not given
34 -e, --extensions [extensions] file extensions to include in the package; default is "mustache,html,htm,txt"
35 ```
36
37
38 Node.js API
39 -----------
6042bf0 Dan Dean Update documentation
authored
40
d7d93e4 Dan Dean docs
authored
41 `fspkg` exposes both async and sync API's.
43c446e Dan Dean Updated docs
authored
42
43 ### Main Function ###
44
45 The module export is a shortcut to instantiating a new `Builder` and immediately
46 its `build` method, packaging the file-system at `path`.
47
48 ```text
49 fspkg(path, [options,] cb)
50 - path (String): Path to the file to package.
51 - options (Object): Options to configure the builder.
52 - cb (Function(e, content)): Callback function which is given the file content.
53 ```
54
55 #### Example ####
56
57 ```js
58 require('fspkg')('./views', function(e, pkg) {
59 console.log(pkg);
60 });
61 ```
62
63 The above example would print a CommonJS module similar to this:
64
65 ```js
66 module.exports = {
67 "index.mustache": "<div>\n Welcome {{username}}!\n</div> ...",
68 "about/index.mustache": "<h1>This {{expletive}} is awesome</h1> ...",
69 "about/contact.mustache": "<h1>Contact Us</h1>\n Phone: {{phone}}..."
70 // etc...
71 }
72 ```
73
74
d7d93e4 Dan Dean docs
authored
75 ### Builder (async) ###
43c446e Dan Dean Updated docs
authored
76
77 ```text
78 new Builder([options])
79 - options (Object): Options to configure the builder.
80
81 Creates a new Builder instance. Available Options:
82
a11cb9f Dan Dean Add new filter API info
authored
83 * filter (Function|String): A function or string which filters file paths
84 found in the directory to be packaged.
85
86 If a `String`, it should be a comma-separated list of file extensions,
87 such as "foo,bar,baz". If a `Function`, should return `true` to include
88 the file, `false` to exclude it.
89
90 Defaults to "mustache,html,htm,txt".
43c446e Dan Dean Updated docs
authored
91
92 * format (String): The format to return from the `build` method:
a11cb9f Dan Dean Add new filter API info
authored
93 "module", "json" or "object". Defaults to "module";
43c446e Dan Dean Updated docs
authored
94
95
96
97 Builder#build(path, cb)
98 - path (String): The root path of the package.
99 - cb (Function(e, result)): Callback function which is given the result.
100
101 Builds the directory or file `path`. `result` is a package in the configured format.
102
103
104
105 Builder.Processor.*(path, cb) -> String
106 - path (String): Path to the file to package.
107 - cb (Function(e, content)): Callback function which is given the file content.
108
109 All processors have the same signature: they take a file path and callback function.
110 The file content is encoded file as a String and passed to `cb` as the 2nd argument.
111
112 Builder.Processor.Default(path, cb)
113 Builder.Processor.Base64(path, cb)
114 Builder.Processor.DataURI(path, cb)
115 ```
116
6042bf0 Dan Dean Update documentation
authored
117
118 ### SyncBuilder ###
119
120 ```text
121 new SyncBuilder([options])
122 - options (Object): Options to configure the builder.
123
124 Creates a new SyncBuilder instance. Available Options:
125
a11cb9f Dan Dean Add new filter API info
authored
126 * filter (Function|String): A function or string which filters file paths
127 found in the directory to be packaged.
128
129 If a `String`, it should be a comma-separated list of file extensions,
130 such as "foo,bar,baz". If a `Function`, should return `true` to include
131 the file, `false` to exclude it.
132
133 Defaults to "mustache,html,htm,txt".
6042bf0 Dan Dean Update documentation
authored
134
135 * format (String): The format to return from the `build` method:
a11cb9f Dan Dean Add new filter API info
authored
136 "module", "json" or "object". Defaults to "module";
6042bf0 Dan Dean Update documentation
authored
137
138
139
140 SyncBuilder#build(path) -> ?
141 - path (String): The root path of the package.
142
43c446e Dan Dean Updated docs
authored
143 Builds the directory or file `path`, returning a package in the configured format.
6042bf0 Dan Dean Update documentation
authored
144
145
146
147 SyncBuilder.Processor.*(path) -> String
148 - path (String): Path to the file to package.
149
150 All processors have the same signature: they take a file path and return the
151 encoded file as a String.
152
153 SyncBuilder.Processor.Default(path) -> UTF-8 encoded string.
154 SyncBuilder.Processor.Base64(path) -> Base64 encoded string.
155 SyncBuilder.Processor.DataURI(path) -> Base64 encoded Data URI.
156 ```
157
158 ### Filter ###
159
160 ```text
161 Filter.Default(path) -> Boolean
162 - path (String): The path to the file.
163
164 Returns `true` if the file should be included in the package, otherwise: `false`.
165 Only .mustache, .html, .htm and .txt files pass this filter, and all files within
166 ".git" and "node_modules" direcotories are excluded.
167 ```
168
169
91b735f Dan Dean Updated docs
authored
170 Example
171 -------
172
173 ```js
174 var fs = require('fs');
175 var fspkg = require('fspkg');
176
177 var builder = new fspkg.SyncBuilder({
178 filter: function(path) {
179 // Include .png files...
180 if (path && path.match(/\.png$/)) return true;
181 return fspkg.Filter.Default(path);
182 },
183
184 // Use the Data URI processor for .png files
185 '.png': function(path) {
186 return fspkg.SyncBuilder.Processor.DataURI(path);
187 }
188 });
189
190 // Assuming you have a "stuff" directory with PNGs and other
191 // files that you want to package up:
192 var result = builder.build('./stuff');
193
194 // Write the module to the current directory as "assets.js".
195 fs.writeFileSync('./assets.js', result);
196
197 // Now you can require() the file and use it for whatever.
198 console.log(require('./assets.js'));
199 ```
200
201
6042bf0 Dan Dean Update documentation
authored
202 Install
203 -------
204
205 `npm install fspkg`
206
a11cb9f Dan Dean Add new filter API info
authored
207 To install the command-line utility, add the `-g` flag during installation.
208
6042bf0 Dan Dean Update documentation
authored
209
210
211 License
212 -------
213
214 MIT
Something went wrong with that request. Please try again.