<p>Delimited data can be parsed out of strings or files. Files that are parsed can be local or remote. Local files are opened with FileReader, and remote files are downloaded with XMLHttpRequest.</p>
to alter the flow of parsing. Actions can be <code>"abort"</code> to skip this and all other files in the queue, <code>"skip"</code> to skip just this file, or <code>"continue"</code> to carry on (equivalent to returning nothing). <code>reason</code> can be a reason for aborting. <code>config</code> can be a modified <ahref="#config">configuration</a> for parsing just this file.
</li>
<li>The <code>complete</code> callback shown here is executed after <i>all</i> files are finished and does not receive any data. Use the complete callback in <ahref="#config">config</a> for per-file results.
Set <code>quotes</code> to <code>true</code> to force enclosing each datum around quotes. The <code>delimiter</code> can be any valid delimiting character. And the <code>newline</code> character(s) may also be customized.
<p>Every call to <code>parse</code> receives a configuration object. Its properties define settings, behavior, and callbacks used during parsing.</p>
</div>
<divclass="grid-50">
<h4id="unparse">Default config</h4>
<codeclass="block">{
delimiter: "",
header: false,
dynamicTyping: false,
preview: 0,
step: undefined,
encoding: "",
worker: false,
comments: false,
complete: undefined,
download: false
}</code>
<ul>
<li><code>delimiter</code> The delimiting character. Leave blank to auto-detect. If specified, it must be a string of length 1, and cannot be found in <ahref="#extras">Papa.BAD_DELIMITERS</a>.</li>
<li><code>header</code> If true, the first row of parsed data will be interpreted as field names. Fields will be returned in the <ahref="#meta">meta</a>, and each row will be an object of data keyed by field name. If false, the parser simply returns an array of arrays, including the first row.</li>
<li><code>dynamicTyping</code> If true, numeric and boolean data will be converted to their type instead of remaining strings.</li>
<li><code>preview</code> If > 0, only that many rows will be parsed.</li>
</ul>
</div>
<divclass="grid-50">
<ul>
<li>
<code>step</code> To <ahref="faq.html#streaming">stream</a> the input, define a callback function to receive <ahref="#results">results</a> row-by-row rather than together at the end:
You can call <code>parser.abort()</code> to halt parsing that input (not available if using a worker).
</li>
<li><code>encoding</code> The encoding to use when opening files locally.</li>
<li><code>worker</code> Whether or not to use a <ahref="faq.html#workers">worker thread</a>. Using a worker will keep your page reactive, but may be slightly slower.</li>
<li><code>comments</code> Specify a comment character (like <code>"#"</code>) if your CSV file has commented lines, and Papa will skip them. This feature is disabled by default.</li>
<li>
<code>complete</code> A callback to execute when parsing is complete. Results are passed in, and if parsing a file, the file is, too:
If streaming, results will <i>not</i> be available in this function.
</li>
<li><code>download</code> If <code>true</code>, this indicates that the string you passed in is actually a URL from which to download a file and parse it.
<p>Parse results are always (even when streaming) provided in a roughly consistent format: an object with data, errors, and meta. When streaming, <code>results.data</code> contains only one row.</p>
</div>
<divclass="grid-50">
<h4id="results-structure">Results structure</h4>
<codeclass="block">{
data: <spanclass="comment">// array of parse results</span>
errors: <spanclass="comment">// array of errors</span>
meta: <spanclass="comment">// object with extra info</span>
<li><code>data</code> is an array of rows. Rows are either arrays (if <code>header: false</code>) or objects (if <code>header: true</code>). Inside a <ahref="#config">step</a> function, data will only contain one row.</li>
<li><code>errors</code> is an array of errors.</li>
<li><code>meta</code> contains extra information about the parse, such as delimiter used, number of lines, whether the process was aborted, etc.
</ul>
</div>
<divclass="clear"></div>
<divclass="grid-50">
<h4id="data">results.data</h4>
<codeclass="block"><spanclass="comment">// Example (without header)</span>
[
["Column 1", "Column 2"],
["foo", "bar"],
["abc", "def"]
]
<spanclass="comment">// Example (with header)</span>
[
{
"Column 1": "foo",
"Column 2": "bar"
},
{
"Column 1": "abc",
"Column 2": "def"
}
]</code>
</div>
<divclass="grid-50">
<ul>
<li>If header row is enabled, and more fields are found on a row of data than in the header row, an extra field will appear in the results called <code>__parsed_extra</code>. It contains an array of all data parsed from that row that was wider than the header row.</li>
<li>Using <code>dynamicTyping: true</code> will turn numeric and boolean data into number and boolean types, respectively. Otherwise, all parsed data is string.</li>
<li>The error <code>type</code> will be one of "Abort", "Quotes", "Delimiter", or "FieldMismatch".</li>
<li>The <code>code</code> may be "ParseAbort", "MissingQuotes", "UnexpectedQuotes", "UndetectableDelimiter", "TooFewFields", or "TooManyFields" (depending on the error type).</li>
<li><code>line</code> and <code>index</code> may not be available on all error messages because some errors are only generated after parsing is already complete.</li>
<li>Just because errors are generated does not necessarily mean that parsing failed! Papa is strong, and usually parsing only bombs hard if the input has sloppy quotes.</li>
</ul>
</div>
<divclass="clear"></div>
<divclass="grid-50">
<h4id="meta">results.meta</h4>
<codeclass="block">{
lines: <spanclass="comment">// Number of lines parsed</span>
<p>There's a few other things that Papa exposes for you that weren't explained above.</p>
</div>
<divclass="grid-50">
<p>
These are provided as a convenience and should remain read-only, but <b>feel free to use them</b>:
</p>
<ul>
<li>
<code>Papa.BAD_DELIMITERS</code>
An array of characters that are not allowed as delimiters (or comment characters).
</li>
<li>
<code>Papa.RECORD_SEP</code>
The true delimiter. Invisible. ASCII code 30. Should be doing the job we strangely rely upon commas and tabs for.
</li>
<li>
<code>Papa.UNIT_SEP</code>
Also sometimes used as a delimiting character. ASCII code 31.
</li>
<li>
<code>Papa.WORKERS_SUPPORTED</code>
Whether or not the browser supports HTML5 Web Workers. If false, <code>worker: true</code> will have no effect.
</li>
</ul>
</div>
<divclass="grid-50">
<p>
The following items are for internal use and testing only. <b>It is not recommended that you use them unless you're familiar with the underlying code base:</b>
</p>
<ul>
<li>
<code>Papa.Parser</code>
The core parsing component.
</li>
<li>
<code>Papa.ParserHandle</code>
A wrapper over the Parser which provides dynamic typing and header row support.
</li>
<li>
<code>Papa.NetworkStreamer</code>
Facilitates downloading and parsing files in chunks over the network with XMLHttpRequest.
</li>
<li>
<code>Papa.FileStreamer</code>
Similar to NetworkStreamer, but for local files, and using the HTML5 FileReader.
