@ -26,7 +26,7 @@ can be installed with the following command:
npm install papaparse
npm install papaparse
If you don't want to use npm, [papaparse.min.js](https://github.com/mholt/PapaParse/blob/master/papaparse.min.js) can be downloaded to your project source.
If you don't want to use npm, [papaparse.min.js](https://unpkg.com/papaparse@latest/papaparse.min.js) can be downloaded to your project source.
Homepage & Demo
Homepage & Demo
@ -39,9 +39,7 @@ To learn how to use Papa Parse:
- [Documentation](http://papaparse.com/docs)
- [Documentation](http://papaparse.com/docs)
The website is hosted on on [Github Pages](https://pages.github.com/). If
The website is hosted on [Github Pages](https://pages.github.com/). It's content is also include in the docs folder of this repository. If you want to contribute on it just clone the master of this repository and open a pull request.
you want to contribute just clone the gh-branch of this repository and
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>
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>
<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.</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.</li>
<h5id="unparse-config-default">Default Unparse Config with all options</h5>
</div>
<divclass="prefix-25 grid-50 suffix-25">
<pre><codeclass="language-javascript">
{
{
quotes: false,
quotes: false, //or array of booleans
quoteChar: '"',
quoteChar: '"',
escapeChar: '"',
escapeChar: '"',
delimiter: ",",
delimiter: ",",
header: true,
header: true,
newline: "\r\n"
newline: "\r\n",
}</code></pre>
skipEmptyLines: false, //or 'greedy',
Set <code>quotes</code> to <code>true</code> to always enclose each field in quotes, or an array of true/false values correlating to specific to columns to force-quote. The character used to quote can be customized using <code>quoteChar</code>. The character used to escape the <code>quoteChar</code> within a field can be customized using <code>escapeChar</code>. The <code>delimiter</code> can be any valid delimiting character. The <code>newline</code> character(s) may also be customized. Setting <code>header</code> to <code>false</code> will omit the header row.
columns: null //or array of strings
</li>
}
</ul>
</code></pre>
</div>
<divclass="clear"></div>
<divclass="grid-100">
<h5>Unparse Config Options</h5>
</div>
<divclass="grid-100"style="overflow-x: auto;">
<table>
<tr>
<thstyle="width: 20%;">Option</th>
<thstyle="width: 80%;">Explanation</th>
</tr>
<tr>
<td>
<code>quotes</code>
</td>
<td>
If <code>true</code>, forces all fields to be enclosed in quotes. If an array of <code>true/false</code> values, specifies which fields should be force-quoted (first boolean is for the first column, second boolean for the second column, ...). If a function (accepting cell value & column index as parameters), returning <code>true</code> will force quotes for that value and <code>false</code> will not.
</td>
</tr>
<tr>
<td><code>quoteChar</code></td>
<td>
The character used to quote fields.
</td>
</tr>
<tr>
<td><code>escapeChar</code></td>
<td>
The character used to escape <code>quoteChar</code> inside field values.
</td>
</tr>
<tr>
<td>
<code>delimiter</code>
</td>
<td>
The delimiting character. It must not be found in <ahref="#readonly">Papa.BAD_DELIMITERS</a>.
</td>
</tr>
<tr>
<td>
<code>header</code>
</td>
<td>
If <code>false</code>, will omit the header row. If <code>data</code> is an array of arrays this option is ignored. If <code>data</code> is an array of objects the keys of the first object are the header row. If <code>data</code> is an object with the keys <code>fields</code> and <code>data</code> the <code>fields</code> are the header row.
</td>
</tr>
<tr>
<td>
<code>newline</code>
</td>
<td>
The newline sequence. Must be one of <code>"\r"</code>, <code>"\n"</code>, or <code>"\r\n"</code>.
</td>
</tr>
<tr>
<td>
<code>skipEmptyLines</code>
</td>
<td>
If <code>true</code>, lines that are completely empty (those which evaluate to an empty string) will be skipped. If set to <code>'greedy'</code>, lines that don't have any content (those which have only whitespace after parsing) will also be skipped.
</td>
</tr>
<tr>
<td>
<code>columns</code>
</td>
<td>
If <code>data</code> is an array of objects this option can be used to manually specify the keys (columns) you expect in the objects. If not set the keys of the first objects are used as column.
</td>
</tr>
</table>
</div>
</div>
<divclass="clear"></div>
<divclass="clear"></div>
@ -289,8 +371,8 @@ var csv = Papa.unparse([
<divclass="grid-33">
<divclass="grid-33">
<pre><codeclass="language-javascript">// Specifying fields and data explicitly
<pre><codeclass="language-javascript">// Specifying fields and data explicitly
The delimiting character. Leave blank to auto-detect from a list of most common delimiters. It can be a string or a function. If string, it must be one of length 1. If a function, it must accept the input as first parameter and it must return a string which will be used as delimiter. In both cases it cannot be found in <ahref="#readonly">Papa.BAD_DELIMITERS</a>.
The delimiting character. Leave blank to auto-detect from a list of most common delimiters, or any values passed in through <code>delimitersToGuess</code>. It can be a string or a function. If string, it must be one of length 1. If a function, it must accept the input as first parameter and it must return a string which will be used as delimiter. In both cases it cannot be found in <ahref="#readonly">Papa.BAD_DELIMITERS</a>.
</td>
</td>
</tr>
</tr>
<tr>
<tr>
@ -412,10 +496,11 @@ var csv = Papa.unparse({
</tr>
</tr>
<tr>
<tr>
<td>
<td>
<code>trimHeaders</code>
<code>transformHeader</code>
</td>
</td>
<td>
<td>
If true leading/trailing spaces will be trimed from headers.
A function to apply on each header. Requires <code>header</code> to be <code>true</code>. The function receives the header as its first argument.<br>
Only available starting with version 5.0.
</td>
</td>
</tr>
</tr>
<tr>
<tr>
@ -423,7 +508,7 @@ var csv = Papa.unparse({
<code>dynamicTyping</code>
<code>dynamicTyping</code>
</td>
</td>
<td>
<td>
If true, numeric and boolean data will be converted to their type instead of remaining strings. Numeric data must conform to the definition of a decimal literal. European-formatted numbers must have commas and dots swapped. If also accepts an object or a function. If object it's values should be a boolean to indicate if dynamic typing should be applied for each column number (or header name if using headers). If it's a function, it should return a boolean value for each field number (or name if using headers) which will be passed as first argument.
If true, numeric and boolean data will be converted to their type instead of remaining strings. Numeric data must conform to the definition of a decimal literal. Numerical values greater than <code>2^53</code> or less than <code>-2^53</code> will not be converted to numbers to preserve precision. European-formatted numbers must have commas and dots swapped. If also accepts an object or a function. If object it's values should be a boolean to indicate if dynamic typing should be applied for each column number (or header name if using headers). If it's a function, it should return a boolean value for each field number (or name if using headers) which will be passed as first argument.
</td>
</td>
</tr>
</tr>
<tr>
<tr>
@ -431,7 +516,7 @@ var csv = Papa.unparse({
<code>preview</code>
<code>preview</code>
</td>
</td>
<td>
<td>
If > 0, only that many rows will be parsed.
If > 0, only that many rows will be parsed.
</td>
</td>
</tr>
</tr>
<tr>
<tr>
@ -447,7 +532,7 @@ var csv = Papa.unparse({
<code>worker</code>
<code>worker</code>
</td>
</td>
<td>
<td>
Whether or not to use a <ahref="/faq#workers">worker thread</a>. Using a worker will keep your page reactive, but may be slightly slower. Web Workers also load the entire Javascript file, so be careful when <ahref="/faq#combine">combining other libraries</a> in the same file as Papa Parse. Note that worker option is only available when parsing files and not when converting from JSON to CSV.
Whether or not to use a <ahref="/faq#workers">worker thread</a>. Using a worker will keep your page reactive, but may be slightly slower.
</td>
</td>
</tr>
</tr>
<tr>
<tr>
@ -500,12 +585,25 @@ var csv = Papa.unparse({
If true, this indicates that the string you passed as the first argument to <code>parse()</code> is actually a URL from which to download a file and parse its contents.
If true, this indicates that the string you passed as the first argument to <code>parse()</code> is actually a URL from which to download a file and parse its contents.
</td>
</td>
</tr>
</tr>
<tr>
<td>
<code>downloadRequestHeaders</code>
</td>
<td>
If defined, should be an object that describes the headers, example:
If true, lines that are completely empty will be skipped. An empty line is defined to be one which evaluates to empty string.
If true, lines that are completely empty (those which evaluate to an empty string) will be skipped. If set to <code>'greedy'</code>, lines that don't have any content (those which have only whitespace after parsing) will also be skipped.
</td>
</td>
</tr>
</tr>
<tr>
<tr>
@ -545,7 +643,15 @@ var csv = Papa.unparse({
<code>transform</code>
<code>transform</code>
</td>
</td>
<td>
<td>
A function to apply on each value. The function receives the value as its first argument and the column number as its second argument. The return value of the function will replace the value it received. The transform function is applied before dynamicTyping.
A function to apply on each value. The function receives the value as its first argument and the column number or header name when enabled as its second argument. The return value of the function will replace the value it received. The transform function is applied before dynamicTyping.
</td>
</tr>
<tr>
<td>
<code>delimitersToGuess</code>
</td>
<td>
An array of delimiters to guess from if the <code>delimiter</code> option is not set.
</td>
</td>
</tr>
</tr>
</table>
</table>
@ -749,12 +855,6 @@ var csv = Papa.unparse({
Whether or not the browser supports HTML5 Web Workers. If false, <code>worker: true</code> will have no effect.
Whether or not the browser supports HTML5 Web Workers. If false, <code>worker: true</code> will have no effect.
</td>
</td>
</tr>
</tr>
<tr>
<td><code>Papa.SCRIPT_PATH</code></td>
<td>
The relative path to Papa Parse. This is automatically detected when Papa Parse is loaded synchronously. However, if you load Papa Parse asynchronously (e.g. with RequireJS), you need to set this variable manually in order to use Web Workers. (In those cases, this variable is <i>not</i> read-only and you should set it!)
</td>
</tr>
</table>
</table>
</div>
</div>
@ -812,7 +912,7 @@ var csv = Papa.unparse({
<br><br>
<br><br>
Papa Parse by <ahref="https://twitter.com/mholt6">Matt Holt</a>
Papa Parse by <ahref="https://twitter.com/mholt6">Matt Holt</a>
<h6id="combine">Can I put other libraries in the same file as Papa Parse?</h6>
<h6id="combine">Can I put other libraries in the same file as Papa Parse?</h6>
<p>
<p>
Yes, but then don't use the Web Worker feature unless your other dependencies are battle-hardened for worker threads. A worker thread loads an entire file, not just a function, so all those dependencies would be executed in an environment without a DOM and other <code>window</code> features. If any of those dependencies crash (<code>Cannot read property "defaultView" of undefined</code><ahref="https://github.com/mholt/PapaParse/issues/114">is</a><ahref="https://github.com/mholt/PapaParse/issues/163">common</a>), the whole worker thread will crash and parsing will not succeed.
Yes.
</p>
</p>
@ -96,7 +93,7 @@
<h6id="async">Can Papa Parse be loaded asynchronously (after the page loads)?</h6>
<h6id="async">Can Papa Parse be loaded asynchronously (after the page loads)?</h6>
<p>
<p>
Yes. But if you want to use Web Workers, you'll need to specify the relative path to Papa Parse. To do this, set <ahref="/docs#readonly">Papa.SCRIPT_PATH</a> to the relative path of the Papa Parse file. In synchronous loading, this is automatically detected.
Yes.
</p>
</p>
@ -209,7 +206,7 @@
<h6>Can I use a worker if I combine/concatenate my Javascript files?</h6>
<h6>Can I use a worker if I combine/concatenate my Javascript files?</h6>
<p>
<p>
Probably not. It's safest to concatenate the rest of your dependencies and include Papa Parse in a seperate file. Any library that expects to have access to the <code>window</code> or DOM will crash when executed in a worker thread. Only put <ahref="/faq#combine">other libraries in the same file</a> if they are ready to be used in worker threads.
Yes.
</p>
</p>
<h6>When should I use a worker?</h6>
<h6>When should I use a worker?</h6>
@ -241,6 +238,11 @@
<p>
<p>
No. This would drastically slow down parsing, as it would require the worker to wait after every chunk for a "continue" signal from the main thread. But you <i>can</i> abort workers by calling <code>.abort()</code> on the parser that gets passed to your callback function.
No. This would drastically slow down parsing, as it would require the worker to wait after every chunk for a "continue" signal from the main thread. But you <i>can</i> abort workers by calling <code>.abort()</code> on the parser that gets passed to your callback function.
</p>
</p>
<h6>I set worker:true and now I'm getting an error: "window is not defined." How do I fix it?</h6>
<p>
This is a fairly common issue with configuration and it appears to be related to the use of React or other third party tools. Since this is a configuration issue, the exact steps needed to solve it may vary. See <ahref="https://github.com/mholt/PapaParse/issues/655">Issue #655</a> on GitHub for a solution that worked for one person, and for links to other related issues.
</p>
</div>
</div>
</div>
</div>
</main>
</main>
@ -257,7 +259,7 @@
<br><br>
<br><br>
Papa Parse by <ahref="https://twitter.com/mholt6">Matt Holt</a>
Papa Parse by <ahref="https://twitter.com/mholt6">Matt Holt</a>
<b><ahref="https://github.com/mholt/PapaParse/blob/gh-pages/resources/js/lovers.js"class="add-lover-link subheader"><iclass="fa fa-plus-square"></i> Add your link (it's free)</a></b>
<b><ahref="https://github.com/mholt/PapaParse/blob/master/docs/resources/js/lovers.js"class="add-lover-link subheader"><iclass="fa fa-plus-square"></i> Add your link (it's free)</a></b>
</div>
</div>
</div>
</div>
</section>
</section>
@ -506,6 +503,7 @@ var csv = Papa.unparse(yourData);</code></pre>
<iclass="fa fa-book"></i> Documentation
<iclass="fa fa-book"></i> Documentation
</a>
</a>
</div>
</div>
</div>
</section>
</section>
@ -524,7 +522,7 @@ var csv = Papa.unparse(yourData);</code></pre>
<br><br>
<br><br>
Papa Parse by <ahref="https://twitter.com/mholt6">Matt Holt</a>
Papa Parse by <ahref="https://twitter.com/mholt6">Matt Holt</a>
description:"is a text adventure framework that uses Papa Parse to enable user-friendly translations.",
description:"is a text adventure framework that uses Papa Parse to enable user-friendly translations.",
quote:"Papa saves countless hours of work and makes reading large CSV files so easy!"
quote:"Papa saves countless hours of work and makes reading large CSV files so easy!"
},
{
link:"https://mailcheck.co",
name:"Mailcheck.co",
description:"Mailcheck is email validation service. All emails usually stored in CSV's. We use Papa Parse to process data from our customers in browser",
quote:"Papa Parser allowed our customers to preview and process csv's in browser, without uploading them to server. It saves lots of time and space :)"
},
{
link:"https://flatfile.io",
name:"Flatfile.io",
description:"is an add-in data importer for web-apps, providing the full UX to upload a spreadsheet, field match, and repair issues found during import.",
quote:"Papa is a core part of our importer, so much so that we're committed to helping maintain it!"
},
{
link:"https://familiohq.com",
name:"Familio",
description:"is a brand-new messaging app made specifically for busy families. Automatically align all family members when sending text messages to parents in the kindergarten or school or when planning your kids birthday parties.",
quote:"With Papa it was a joy to implement our tool for importing messages and places from external systems."
"description":"Fast and powerful CSV parser for the browser that supports web workers and streaming large files. Converts CSV to JSON and JSON to CSV.",
"description":"Fast and powerful CSV parser for the browser that supports web workers and streaming large files. Converts CSV to JSON and JSON to CSV.",
description:"Date objects are exported in its ISO representation",
description:"Date objects are exported in its ISO representation",
input:[{date:newDate("2018-05-04T21:08:03.269Z"),"not a date":16},{date:newDate("Tue May 08 2018 08:20:22 GMT-0700 (PDT)"),"not a date":32}],
input:[{date:newDate("2018-05-04T21:08:03.269Z"),"not a date":16},{date:newDate("Tue May 08 2018 08:20:22 GMT-0700 (PDT)"),"not a date":32}],
expected:'date,not a date\r\n2018-05-04T21:08:03.269Z,16\r\n2018-05-08T15:20:22.000Z,32'
expected:'date,not a date\r\n2018-05-04T21:08:03.269Z,16\r\n2018-05-08T15:20:22.000Z,32'
},
{
description:"Returns empty rows when empty rows are passed and skipEmptyLines is false",
input:[[null,' '],[],['1','2']],
config:{skipEmptyLines:false},
expected:'," "\r\n\r\n1,2'
},
{
description:"Returns without empty rows when skipEmptyLines is true",
input:[[null,' '],[],['1','2']],
config:{skipEmptyLines:true},
expected:'," "\r\n1,2'
},
{
description:"Returns without rows with no content when skipEmptyLines is 'greedy'",
input:[[null,' '],[],['1','2']],
config:{skipEmptyLines:'greedy'},
expected:'1,2'
},
{
description:"Returns empty rows when empty rows are passed and skipEmptyLines is false with headers",
input:[{a:null,b:' '},{},{a:'1',b:'2'}],
config:{skipEmptyLines:false,header:true},
expected:'a,b\r\n," "\r\n\r\n1,2'
},
{
description:"Returns without empty rows when skipEmptyLines is true with headers",
input:[{a:null,b:' '},{},{a:'1',b:'2'}],
config:{skipEmptyLines:true,header:true},
expected:'a,b\r\n," "\r\n1,2'
},
{
description:"Returns without rows with no content when skipEmptyLines is 'greedy' with headers",
input:[{a:null,b:' '},{},{a:'1',b:'2'}],
config:{skipEmptyLines:'greedy',header:true},
expected:'a,b\r\n1,2'
},
{
description:"Column option used to manually specify keys",
notes:"Should not throw any error when attempting to serialize key not present in object. Columns are different than keys of the first object. When an object is missing a key then the serialized value should be an empty string.",
Puzzleton
6 years ago