Documentation for Multipart parser

Also added multipart.parse as a convenience function
15 years ago · eeaa267cbe
5 changed files with 444 additions and 6 deletions
--- a/doc/api.html
+++ b/doc/api.html
@ -1516,6 +1516,116 @@ After emitted no other events will be emitted on the response.</p></td>
 </p>
 </dd>
 </dl></div>
 <h3 id="_multipart_parsing">Multipart Parsing</h3><div style="clear:left"></div>
 <div class="paragraph"><p>A library to parse HTTP requests with <tt>multipart/form-data</tt> is included with
 Node.  To use it, <tt>require("/multipart.js")</tt>.</p></div>
 <div class="dlist"><dl>
 <dt class="hdlist1">
 <tt>multipart.parse(options)</tt> 
 </dt>
 <dd>
 <div class="ulist"><ul>
 <li>
 <p>
 on success: Returns an object where each key holds the value of one part of
                the stream. <tt>options</tt> can either be an instance of
                <tt>http.ServerRequest</tt> or an object containing a <em>boundary</em> and a
                <em>data</em> key.
 </p>
 </li>
 <li>
 <p>
 on error: no parameters.
 </p>
 </li>
 </ul></div>
 </dd>
 </dl></div>
 <h4 id="_tt_multipart_stream_tt"><tt>multipart.Stream</tt></h4>
 <div class="paragraph"><p>Here is an example for parsing a <tt>multipart/form-data</tt> request:</p></div>
 <div class="listingblock">
 <div class="content">
 <pre><tt>var multipart = require('/multipart.js');
 var stream = new multipart.Stream(options);
 var parts = {};
 stream.addListener('part', function (part) {
  var name = part.headers['Content-Disposition'].name;
  var buffer = '';
  part.addListener('body', function(chunk) {
    buffer = buffer + chunk;
  });
  part.addListener('complete', function() {
    parts[name] = buffer;
  });
 });
 stream.addListener('complete', function() {
  // The parts object now contains all parts and data
 });</tt></pre>
 </div></div>
 <div class="tableblock">
 <table rules="all"
 width="100%"
 frame="border"
 cellspacing="0" cellpadding="4">
 <col width="7%" />
 <col width="15%" />
 <col width="76%" />
 <thead>
 <tr>
 <th align="left" valign="top">Event           </th>
 <th align="left" valign="top"> Parameters   </th>
 <th align="left" valign="top"> Notes</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td align="left" valign="top"><p class="table"><tt>"part"</tt></p></td>
 <td align="left" valign="top"><p class="table"><tt>part</tt></p></td>
 <td align="left" valign="top"><p class="table">Emitted when a new part is found in the stream.
                                  <tt>part</tt> is an instance of <tt>multipart.Part</tt>.</p></td>
 </tr>
 <tr>
 <td align="left" valign="top"><p class="table"><tt>"complete"</tt></p></td>
 <td align="left" valign="top"><p class="table"></p></td>
 <td align="left" valign="top"><p class="table">Emitted when the end of the stream is reached.</p></td>
 </tr>
 </tbody>
 </table>
 </div>
 <h4 id="_tt_multipart_part_tt"><tt>multipart.Part</tt></h4>
 <div class="tableblock">
 <table rules="all"
 width="100%"
 frame="border"
 cellspacing="0" cellpadding="4">
 <col width="7%" />
 <col width="15%" />
 <col width="76%" />
 <thead>
 <tr>
 <th align="left" valign="top">Event           </th>
 <th align="left" valign="top"> Parameters   </th>
 <th align="left" valign="top"> Notes</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td align="left" valign="top"><p class="table"><tt>"body"</tt></p></td>
 <td align="left" valign="top"><p class="table"><tt>chunk</tt></p></td>
 <td align="left" valign="top"><p class="table">Emitted when a chunk of body is read.</p></td>
 </tr>
 <tr>
 <td align="left" valign="top"><p class="table"><tt>"complete"</tt></p></td>
 <td align="left" valign="top"><p class="table"></p></td>
 <td align="left" valign="top"><p class="table">Emitted when the end of the part is reached.</p></td>
 </tr>
 </tbody>
 </table>
 </div>
 <h3 id="_tcp">TCP</h3><div style="clear:left"></div>
 <div class="paragraph"><p>To use the TCP server and client one must <tt>require("/tcp.js")</tt> or
 <tt>include("/tcp.js")</tt>.</p></div>
@ -2029,7 +2139,7 @@ init (Handle&lt;Object&gt; target)
 <div id="footer">
 <div id="footer-text">
 Version 0.1.13<br />
-Last updated 2009-09-30 23:15:59 CEST
+Last updated 2009-10-03 18:02:36 CEST
 </div>
 </div>
 </body>
--- a/doc/api.txt
+++ b/doc/api.txt
@ -565,8 +565,6 @@ Objects returned from +node.fs.stat()+ are of this type.
 +stats.isSocket()+:: ...
 === HTTP
 To use the HTTP server and client one must +require("/http.js")+ or
@ -942,6 +940,62 @@ After emitted no other events will be emitted on the response.
 +response.client+ ::
  A reference to the +http.Client+ that this response belongs to.
 === Multipart Parsing
 A library to parse HTTP requests with +multipart/form-data+ is included with
 Node.  To use it, +require("/multipart.js")+.
 +multipart.parse(options)+ ::
  - on success: Returns an object where each key holds the value of one part of
                the stream. +options+ can either be an instance of
                +http.ServerRequest+ or an object containing a 'boundary' and a
                'data' key.
  - on error: no parameters.
 ==== +multipart.Stream+
 Here is an example for parsing a +multipart/form-data+ request:
 ----------------------------------------
 var multipart = require('/multipart.js');
 var stream = new multipart.Stream(options);
 var parts = {};
 stream.addListener('part', function (part) {
  var name = part.headers['Content-Disposition'].name;
  var buffer = '';
  part.addListener('body', function(chunk) {
    buffer = buffer + chunk;
  });
  part.addListener('complete', function() {
    parts[name] = buffer;
  });
 });
 stream.addListener('complete', function() {
  // The parts object now contains all parts and data
 });
 ----------------------------------------
 [cols="1,2,10",options="header"]
 |=========================================================
 |Event           | Parameters   | Notes
 |+"part"+        | +part+       | Emitted when a new part is found in the stream.
                                  +part+ is an instance of +multipart.Part+.
 |+"complete"+    |              | Emitted when the end of the stream is reached.
 |=========================================================
 ==== +multipart.Part+
 [cols="1,2,10",options="header"]
 |=========================================================
 |Event           | Parameters   | Notes
 |+"body"+        | +chunk+      | Emitted when a chunk of body is read.
 |+"complete"+    |              | Emitted when the end of the part is reached.
 |=========================================================
 === TCP
--- a/doc/api.xml
+++ b/doc/api.xml
@ -1609,6 +1609,121 @@ After emitted no other events will be emitted on the response.</simpara></entry>
 </variablelist>
 </refsect3>
 </refsect2>
 <refsect2 id="_multipart_parsing">
 <title>Multipart Parsing</title>
 <simpara>A library to parse HTTP requests with <literal>multipart/form-data</literal> is included with
 Node.  To use it, <literal>require("/multipart.js")</literal>.</simpara>
 <variablelist>
 <varlistentry>
 <term>
 <literal>multipart.parse(options)</literal> 
 </term>
 <listitem>
 <itemizedlist>
 <listitem>
 <simpara>
 on success: Returns an object where each key holds the value of one part of
                the stream. <literal>options</literal> can either be an instance of
                <literal>http.ServerRequest</literal> or an object containing a <emphasis>boundary</emphasis> and a
                <emphasis>data</emphasis> key.
 </simpara>
 </listitem>
 <listitem>
 <simpara>
 on error: no parameters.
 </simpara>
 </listitem>
 </itemizedlist>
 </listitem>
 </varlistentry>
 </variablelist>
 <refsect3 id="_literal_multipart_stream_literal">
 <title><literal>multipart.Stream</literal></title>
 <simpara>Here is an example for parsing a <literal>multipart/form-data</literal> request:</simpara>
 <screen>var multipart = require('/multipart.js');
 var stream = new multipart.Stream(options);
 var parts = {};
 stream.addListener('part', function (part) {
  var name = part.headers['Content-Disposition'].name;
  var buffer = '';
  part.addListener('body', function(chunk) {
    buffer = buffer + chunk;
  });
  part.addListener('complete', function() {
    parts[name] = buffer;
  });
 });
 stream.addListener('complete', function() {
  // The parts object now contains all parts and data
 });</screen>
 <informaltable
 frame="all"
 rowsep="1" colsep="1"
 >
 <tgroup cols="3">
 <colspec colname="col_1" colwidth="7*"/>
 <colspec colname="col_2" colwidth="15*"/>
 <colspec colname="col_3" colwidth="76*"/>
 <thead>
 <row>
 <entry align="left" valign="top">Event           </entry>
 <entry align="left" valign="top"> Parameters   </entry>
 <entry align="left" valign="top"> Notes</entry>
 </row>
 </thead>
 <tbody>
 <row>
 <entry align="left" valign="top"><simpara><literal>"part"</literal></simpara></entry>
 <entry align="left" valign="top"><simpara><literal>part</literal></simpara></entry>
 <entry align="left" valign="top"><simpara>Emitted when a new part is found in the stream.
                                  <literal>part</literal> is an instance of <literal>multipart.Part</literal>.</simpara></entry>
 </row>
 <row>
 <entry align="left" valign="top"><simpara><literal>"complete"</literal></simpara></entry>
 <entry align="left" valign="top"><simpara></simpara></entry>
 <entry align="left" valign="top"><simpara>Emitted when the end of the stream is reached.</simpara></entry>
 </row>
 </tbody>
 </tgroup>
 </informaltable>
 </refsect3>
 <refsect3 id="_literal_multipart_part_literal">
 <title><literal>multipart.Part</literal></title>
 <informaltable
 frame="all"
 rowsep="1" colsep="1"
 >
 <tgroup cols="3">
 <colspec colname="col_1" colwidth="7*"/>
 <colspec colname="col_2" colwidth="15*"/>
 <colspec colname="col_3" colwidth="76*"/>
 <thead>
 <row>
 <entry align="left" valign="top">Event           </entry>
 <entry align="left" valign="top"> Parameters   </entry>
 <entry align="left" valign="top"> Notes</entry>
 </row>
 </thead>
 <tbody>
 <row>
 <entry align="left" valign="top"><simpara><literal>"body"</literal></simpara></entry>
 <entry align="left" valign="top"><simpara><literal>chunk</literal></simpara></entry>
 <entry align="left" valign="top"><simpara>Emitted when a chunk of body is read.</simpara></entry>
 </row>
 <row>
 <entry align="left" valign="top"><simpara><literal>"complete"</literal></simpara></entry>
 <entry align="left" valign="top"><simpara></simpara></entry>
 <entry align="left" valign="top"><simpara>Emitted when the end of the part is reached.</simpara></entry>
 </row>
 </tbody>
 </tgroup>
 </informaltable>
 </refsect3>
 </refsect2>
 <refsect2 id="_tcp">
 <title>TCP</title>
 <simpara>To use the TCP server and client one must <literal>require("/tcp.js")</literal> or
--- a/doc/node.1
+++ b/doc/node.1
@ -1,11 +1,11 @@
 .\"     Title: node
 .\"    Author: 
 .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
-.\"      Date: 09/30/2009
+.\"      Date: 10/03/2009
 .\"    Manual: 
 .\"    Source: 
 .\"
-.TH "NODE" "1" "09/30/2009" "" ""
+.TH "NODE" "1" "10/03/2009" "" ""
 .\" disable hyphenation
 .nh
 .\" disable justification (adjust text to left margin only)
@ -1374,6 +1374,139 @@ http\.Client
 that this response belongs to\.
 .RE
 .RE
 .SS "Multipart Parsing"
 A library to parse HTTP requests with multipart/form\-data is included with Node\. To use it, require("/multipart\.js")\.
 .PP
 multipart\.parse(options)
 .RS 4
 .sp
 .RS 4
 \h'-04'\(bu\h'+03'on success: Returns an object where each key holds the value of one part of the stream\.
 options
 can either be an instance of
 http\.ServerRequest
 or an object containing a
 \fIboundary\fR
 and a
 \fIdata\fR
 key\.
 .RE
 .sp
 .RS 4
 \h'-04'\(bu\h'+03'on error: no parameters\.
 .RE
 .RE
 .sp
 .it 1 an-trap
 .nr an-no-space-flag 1
 .nr an-break-flag 1
 .br
 multipart.Stream
 .RS
 Here is an example for parsing a multipart/form\-data request:
 .sp
 .sp
 .RS 4
 .nf
 var multipart = require(\'/multipart\.js\');
 var stream = new multipart\.Stream(options);
 var parts = {};
 stream\.addListener(\'part\', function (part) {
  var name = part\.headers[\'Content\-Disposition\']\.name;
  var buffer = \'\';
  part\.addListener(\'body\', function(chunk) {
    buffer = buffer + chunk;
  });
  part\.addListener(\'complete\', function() {
    parts[name] = buffer;
  });
 });
 stream\.addListener(\'complete\', function() {
  // The parts object now contains all parts and data
 });
 .fi
 .RE
 .TS
 allbox tab(:);
 ltB ltB ltB.
 T{
 Event
 T}:T{
 Parameters
 T}:T{
 Notes
 T}
 .T&
 lt lt lt
 lt lt lt.
 T{
 "part"
 .sp
 T}:T{
 part
 .sp
 T}:T{
 Emitted when a new part is found in the stream\. part is an instance of multipart\.Part\.
 .sp
 T}
 T{
 "complete"
 .sp
 T}:T{
 .sp
 T}:T{
 Emitted when the end of the stream is reached\.
 .sp
 T}
 .TE
 .sp
 .RE
 .sp
 .it 1 an-trap
 .nr an-no-space-flag 1
 .nr an-break-flag 1
 .br
 multipart.Part
 .RS
 .TS
 allbox tab(:);
 ltB ltB ltB.
 T{
 Event
 T}:T{
 Parameters
 T}:T{
 Notes
 T}
 .T&
 lt lt lt
 lt lt lt.
 T{
 "body"
 .sp
 T}:T{
 chunk
 .sp
 T}:T{
 Emitted when a chunk of body is read\.
 .sp
 T}
 T{
 "complete"
 .sp
 T}:T{
 .sp
 T}:T{
 Emitted when the end of the part is reached\.
 .sp
 T}
 .TE
 .sp
 .RE
 .SS "TCP"
 To use the TCP server and client one must require("/tcp\.js") or include("/tcp\.js")\.
 .sp
--- a/lib/multipart.js
+++ b/lib/multipart.js
@ -1,3 +1,28 @@
 exports.parse = function(options) {
  var stream = new exports.Stream(options);
  var promise = new node.Promise();
  var parts = {};
  stream.addListener('part', function(part) {
    var name = part.headers['Content-Disposition'].name;
    var buffer = '';
    part.addListener('body', function(chunk) {
      buffer = buffer + chunk;
    });
    part.addListener('complete', function() {
      parts[name] = buffer;
    });
  });
  stream.addListener('complete', function() {
    promise.emitSuccess(parts);
  });
  return promise;
 };
 exports.Stream = function(options) {
  node.EventEmitter.call(this);
@ -37,6 +62,7 @@ proto.init = function(options) {
      });
  } else {
    this.boundary = options.boundary;
    this.write(options.data || '');
  }
 };