Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 214 lines (143 sloc) 5.896 kB
6042bf0 @dandean Update documentation
authored
1 fspkg: File System Packager
c587d3e @dandean Initial commit
authored
2 =============================
3
6042bf0 @dandean 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 @dandean Missing quotes around key in documentation.
authored
15 var template = require('views')['layouts/index.mustache'];
6042bf0 @dandean Update documentation
authored
16 var html = Mustache.to_html(template, this.model);
17 this.el.html(html);
18 },
19 ...
20 });
21 ```
22
a11cb9f @dandean Add new filter API info
authored
23 Command-line API
24 ----------------
6042bf0 @dandean Update documentation
authored
25
a11cb9f @dandean 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 @dandean Update documentation
authored
40
d7d93e4 @dandean docs
authored
41 `fspkg` exposes both async and sync API's.
43c446e @dandean 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 @dandean docs
authored
75 ### Builder (async) ###
43c446e @dandean 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 @dandean 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 @dandean Updated docs
authored
91
92 * format (String): The format to return from the `build` method:
a11cb9f @dandean Add new filter API info
authored
93 "module", "json" or "object". Defaults to "module";
43c446e @dandean 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 @dandean 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 @dandean 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 @dandean Update documentation
authored
134
135 * format (String): The format to return from the `build` method:
a11cb9f @dandean Add new filter API info
authored
136 "module", "json" or "object". Defaults to "module";
6042bf0 @dandean Update documentation
authored
137
138
139
140 SyncBuilder#build(path) -> ?
141 - path (String): The root path of the package.
142
43c446e @dandean Updated docs
authored
143 Builds the directory or file `path`, returning a package in the configured format.
6042bf0 @dandean 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 @dandean 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 @dandean Update documentation
authored
202 Install
203 -------
204
205 `npm install fspkg`
206
a11cb9f @dandean Add new filter API info
authored
207 To install the command-line utility, add the `-g` flag during installation.
208
6042bf0 @dandean Update documentation
authored
209
210
211 License
212 -------
213
214 MIT
Something went wrong with that request. Please try again.