raspberryGPIOhtmlserver/node_modules/formidable/Readme.md
node_modules/formidable/Readme.mdRaw
1# Formidable
2
3[](http://travis-ci.org/felixge/node-formidable)
4
5## Purpose
6
7A node.js module for parsing form data, especially file uploads.
8
9## Current status
10
11This module was developed for [Transloadit](http://transloadit.com/), a service focused on uploading
12and encoding images and videos. It has been battle-tested against hundreds of GB of file uploads from
13a large variety of clients and is considered production-ready.
14
15## Features
16
17* Fast (~500mb/sec), non-buffering multipart parser
18* Automatically writing file uploads to disk
19* Low memory footprint
20* Graceful error handling
21* Very high test coverage
22
23## Installation
24
25Via [npm](http://github.com/isaacs/npm):
26```
27npm install formidable@latest
28```
29Manually:
30```
31git clone git://github.com/felixge/node-formidable.git formidable
32vim my.js
33# var formidable = require('./formidable');
34```
35
36Note: Formidable requires [gently](http://github.com/felixge/node-gently) to run the unit tests, but you won't need it for just using the library.
37
38## Example
39
40Parse an incoming file upload.
41```javascript
42var formidable = require('formidable'),
43 http = require('http'),
44 util = require('util');
45
46http.createServer(function(req, res) {
47 if (req.url == '/upload' && req.method.toLowerCase() == 'post') {
48 // parse a file upload
49 var form = new formidable.IncomingForm();
50
51 form.parse(req, function(err, fields, files) {
52 res.writeHead(200, {'content-type': 'text/plain'});
53 res.write('received upload:\n\n');
54 res.end(util.inspect({fields: fields, files: files}));
55 });
56
57 return;
58 }
59
60 // show a file upload form
61 res.writeHead(200, {'content-type': 'text/html'});
62 res.end(
63 '<form action="/upload" enctype="multipart/form-data" method="post">'+
64 '<input type="text" name="title"><br>'+
65 '<input type="file" name="upload" multiple="multiple"><br>'+
66 '<input type="submit" value="Upload">'+
67 '</form>'
68 );
69}).listen(8080);
70```
71## API
72
73### Formidable.IncomingForm
74```javascript
75var form = new formidable.IncomingForm()
76```
77Creates a new incoming form.
78
79```javascript
80form.encoding = 'utf-8';
81```
82Sets encoding for incoming form fields.
83
84```javascript
85form.uploadDir = process.env.TMP || process.env.TMPDIR || process.env.TEMP || '/tmp' || process.cwd();
86```
87The directory for placing file uploads in. You can move them later on using
88`fs.rename()`. The default directory is picked at module load time depending on
89the first existing directory from those listed above.
90
91```javascript
92form.keepExtensions = false;
93```
94If you want the files written to `form.uploadDir` to include the extensions of the original files, set this property to `true`.
95
96```javascript
97form.type
98```
99Either 'multipart' or 'urlencoded' depending on the incoming request.
100
101```javascript
102form.maxFieldsSize = 2 * 1024 * 1024;
103```
104Limits the amount of memory a field (not file) can allocate in bytes.
105If this value is exceeded, an `'error'` event is emitted. The default
106size is 2MB.
107
108```javascript
109form.maxFields = 0;
110```
111Limits the number of fields that the querystring parser will decode. Defaults
112to 0 (unlimited).
113
114```javascript
115form.hash = false;
116```
117If you want checksums calculated for incoming files, set this to either `'sha1'` or `'md5'`.
118
119```javascript
120form.bytesReceived
121```
122The amount of bytes received for this form so far.
123
124```javascript
125form.bytesExpected
126```
127The expected number of bytes in this form.
128
129```javascript
130form.parse(request, [cb]);
131```
132Parses an incoming node.js `request` containing form data. If `cb` is provided, all fields an files are collected and passed to the callback:
133
134
135```javascript
136form.parse(req, function(err, fields, files) {
137 // ...
138});
139
140form.onPart(part);
141```
142You may overwrite this method if you are interested in directly accessing the multipart stream. Doing so will disable any `'field'` / `'file'` events processing which would occur otherwise, making you fully responsible for handling the processing.
143
144```javascript
145form.onPart = function(part) {
146 part.addListener('data', function() {
147 // ...
148 });
149}
150```
151If you want to use formidable to only handle certain parts for you, you can do so:
152```javascript
153form.onPart = function(part) {
154 if (!part.filename) {
155 // let formidable handle all non-file parts
156 form.handlePart(part);
157 }
158}
159```
160Check the code in this method for further inspiration.
161
162
163### Formidable.File
164```javascript
165file.size = 0
166```
167The size of the uploaded file in bytes. If the file is still being uploaded (see `'fileBegin'` event), this property says how many bytes of the file have been written to disk yet.
168```javascript
169file.path = null
170```
171The path this file is being written to. You can modify this in the `'fileBegin'` event in
172case you are unhappy with the way formidable generates a temporary path for your files.
173```javascript
174file.name = null
175```
176The name this file had according to the uploading client.
177```javascript
178file.type = null
179```
180The mime type of this file, according to the uploading client.
181```javascript
182file.lastModifiedDate = null
183```
184A date object (or `null`) containing the time this file was last written to. Mostly
185here for compatibility with the [W3C File API Draft](http://dev.w3.org/2006/webapi/FileAPI/).
186```javascript
187file.hash = null
188```
189If hash calculation was set, you can read the hex digest out of this var.
190
191#### Formidable.File#toJSON()
192
193 This method returns a JSON-representation of the file, allowing you to
194 `JSON.stringify()` the file which is useful for logging and responding
195 to requests.
196
197### Events
198
199
200#### 'progress'
201```javascript
202form.on('progress', function(bytesReceived, bytesExpected) {
203});
204```
205Emitted after each incoming chunk of data that has been parsed. Can be used to roll your own progress bar.
206
207
208
209#### 'field'
210```javascript
211form.on('field', function(name, value) {
212});
213```
214
215#### 'fileBegin'
216
217Emitted whenever a field / value pair has been received.
218```javascript
219form.on('fileBegin', function(name, file) {
220});
221```
222
223#### 'file'
224
225Emitted whenever a new file is detected in the upload stream. Use this even if
226you want to stream the file to somewhere else while buffering the upload on
227the file system.
228
229Emitted whenever a field / file pair has been received. `file` is an instance of `File`.
230```javascript
231form.on('file', function(name, file) {
232});
233```
234
235#### 'error'
236
237Emitted when there is an error processing the incoming form. A request that experiences an error is automatically paused, you will have to manually call `request.resume()` if you want the request to continue firing `'data'` events.
238```javascript
239form.on('error', function(err) {
240});
241```
242
243#### 'aborted'
244
245
246Emitted when the request was aborted by the user. Right now this can be due to a 'timeout' or 'close' event on the socket. In the future there will be a separate 'timeout' event (needs a change in the node core).
247```javascript
248form.on('aborted', function() {
249});
250```
251
252##### 'end'
253```javascript
254form.on('end', function() {
255});
256```
257Emitted when the entire request has been received, and all contained files have finished flushing to disk. This is a great place for you to send your response.
258
259
260
261## Changelog
262
263### v1.0.14
264
265* Add failing hash tests. (Ben Trask)
266* Enable hash calculation again (Eugene Girshov)
267* Test for immediate data events (Tim Smart)
268* Re-arrange IncomingForm#parse (Tim Smart)
269
270### v1.0.13
271
272* Only update hash if update method exists (Sven Lito)
273* According to travis v0.10 needs to go quoted (Sven Lito)
274* Bumping build node versions (Sven Lito)
275* Additional fix for empty requests (Eugene Girshov)
276* Change the default to 1000, to match the new Node behaviour. (OrangeDog)
277* Add ability to control maxKeys in the querystring parser. (OrangeDog)
278* Adjust test case to work with node 0.9.x (Eugene Girshov)
279* Update package.json (Sven Lito)
280* Path adjustment according to eb4468b (Markus Ast)
281
282### v1.0.12
283
284* Emit error on aborted connections (Eugene Girshov)
285* Add support for empty requests (Eugene Girshov)
286* Fix name/filename handling in Content-Disposition (jesperp)
287* Tolerate malformed closing boundary in multipart (Eugene Girshov)
288* Ignore preamble in multipart messages (Eugene Girshov)
289* Add support for application/json (Mike Frey, Carlos Rodriguez)
290* Add support for Base64 encoding (Elmer Bulthuis)
291* Add File#toJSON (TJ Holowaychuk)
292* Remove support for Node.js 0.4 & 0.6 (Andrew Kelley)
293* Documentation improvements (Sven Lito, Andre Azevedo)
294* Add support for application/octet-stream (Ion Lupascu, Chris Scribner)
295* Use os.tmpDir() to get tmp directory (Andrew Kelley)
296* Improve package.json (Andrew Kelley, Sven Lito)
297* Fix benchmark script (Andrew Kelley)
298* Fix scope issue in incoming_forms (Sven Lito)
299* Fix file handle leak on error (OrangeDog)
300
301### v1.0.11
302
303* Calculate checksums for incoming files (sreuter)
304* Add definition parameters to "IncomingForm" as an argument (Math-)
305
306### v1.0.10
307
308* Make parts to be proper Streams (Matt Robenolt)
309
310### v1.0.9
311
312* Emit progress when content length header parsed (Tim Koschützki)
313* Fix Readme syntax due to GitHub changes (goob)
314* Replace references to old 'sys' module in Readme with 'util' (Peter Sugihara)
315
316### v1.0.8
317
318* Strip potentially unsafe characters when using `keepExtensions: true`.
319* Switch to utest / urun for testing
320* Add travis build
321
322### v1.0.7
323
324* Remove file from package that was causing problems when installing on windows. (#102)
325* Fix typos in Readme (Jason Davies).
326
327### v1.0.6
328
329* Do not default to the default to the field name for file uploads where
330 filename="".
331
332### v1.0.5
333
334* Support filename="" in multipart parts
335* Explain unexpected end() errors in parser better
336
337**Note:** Starting with this version, formidable emits 'file' events for empty
338file input fields. Previously those were incorrectly emitted as regular file
339input fields with value = "".
340
341### v1.0.4
342
343* Detect a good default tmp directory regardless of platform. (#88)
344
345### v1.0.3
346
347* Fix problems with utf8 characters (#84) / semicolons in filenames (#58)
348* Small performance improvements
349* New test suite and fixture system
350
351### v1.0.2
352
353* Exclude node\_modules folder from git
354* Implement new `'aborted'` event
355* Fix files in example folder to work with recent node versions
356* Make gently a devDependency
357
358[See Commits](https://github.com/felixge/node-formidable/compare/v1.0.1...v1.0.2)
359
360### v1.0.1
361
362* Fix package.json to refer to proper main directory. (#68, Dean Landolt)
363
364[See Commits](https://github.com/felixge/node-formidable/compare/v1.0.0...v1.0.1)
365
366### v1.0.0
367
368* Add support for multipart boundaries that are quoted strings. (Jeff Craig)
369
370This marks the beginning of development on version 2.0 which will include
371several architectural improvements.
372
373[See Commits](https://github.com/felixge/node-formidable/compare/v0.9.11...v1.0.0)
374
375### v0.9.11
376
377* Emit `'progress'` event when receiving data, regardless of parsing it. (Tim Koschützki)
378* Use [W3C FileAPI Draft](http://dev.w3.org/2006/webapi/FileAPI/) properties for File class
379
380**Important:** The old property names of the File class will be removed in a
381future release.
382
383[See Commits](https://github.com/felixge/node-formidable/compare/v0.9.10...v0.9.11)
384
385### Older releases
386
387These releases were done before starting to maintain the above Changelog:
388
389* [v0.9.10](https://github.com/felixge/node-formidable/compare/v0.9.9...v0.9.10)
390* [v0.9.9](https://github.com/felixge/node-formidable/compare/v0.9.8...v0.9.9)
391* [v0.9.8](https://github.com/felixge/node-formidable/compare/v0.9.7...v0.9.8)
392* [v0.9.7](https://github.com/felixge/node-formidable/compare/v0.9.6...v0.9.7)
393* [v0.9.6](https://github.com/felixge/node-formidable/compare/v0.9.5...v0.9.6)
394* [v0.9.5](https://github.com/felixge/node-formidable/compare/v0.9.4...v0.9.5)
395* [v0.9.4](https://github.com/felixge/node-formidable/compare/v0.9.3...v0.9.4)
396* [v0.9.3](https://github.com/felixge/node-formidable/compare/v0.9.2...v0.9.3)
397* [v0.9.2](https://github.com/felixge/node-formidable/compare/v0.9.1...v0.9.2)
398* [v0.9.1](https://github.com/felixge/node-formidable/compare/v0.9.0...v0.9.1)
399* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
400* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
401* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
402* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
403* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
404* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
405* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
406* [v0.9.0](https://github.com/felixge/node-formidable/compare/v0.8.0...v0.9.0)
407* [v0.1.0](https://github.com/felixge/node-formidable/commits/v0.1.0)
408
409## License
410
411Formidable is licensed under the MIT license.
412
413## Ports
414
415* [multipart-parser](http://github.com/FooBarWidget/multipart-parser): a C++ parser based on formidable
416
417## Credits
418
419* [Ryan Dahl](http://twitter.com/ryah) for his work on [http-parser](http://github.com/ry/http-parser) which heavily inspired multipart_parser.js