<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>README</title>
<style>
html {
line-height: 1.5;
font-family: Georgia, serif;
font-size: 20px;
color: #1a1a1a;
background-color: #fdfdfd;
}
body {
margin: 0 auto;
max-width: 36em;
padding-left: 50px;
padding-right: 50px;
padding-top: 50px;
padding-bottom: 50px;
hyphens: auto;
overflow-wrap: break-word;
text-rendering: optimizeLegibility;
font-kerning: normal;
}
@media (max-width: 600px) {
body {
font-size: 0.9em;
padding: 1em;
}
h1 {
font-size: 1.8em;
}
}
@media print {
body {
background-color: transparent;
color: black;
font-size: 12pt;
}
p, h2, h3 {
orphans: 3;
widows: 3;
}
h2, h3, h4 {
page-break-after: avoid;
}
}
p {
margin: 1em 0;
}
a {
color: #1a1a1a;
}
a:visited {
color: #1a1a1a;
}
img {
max-width: 100%;
}
h1, h2, h3, h4, h5, h6 {
margin-top: 1.4em;
}
h5, h6 {
font-size: 1em;
font-style: italic;
}
h6 {
font-weight: normal;
}
ol, ul {
padding-left: 1.7em;
margin-top: 1em;
}
li > ol, li > ul {
margin-top: 0;
}
blockquote {
margin: 1em 0 1em 1.7em;
padding-left: 1em;
border-left: 2px solid #e6e6e6;
color: #606060;
}
code {
font-family: Menlo, Monaco, 'Lucida Console', Consolas, monospace;
font-size: 85%;
margin: 0;
}
pre {
margin: 1em 0;
overflow: auto;
}
pre code {
padding: 0;
overflow: visible;
overflow-wrap: normal;
}
.sourceCode {
background-color: transparent;
overflow: visible;
}
hr {
background-color: #1a1a1a;
border: none;
height: 1px;
margin: 1em 0;
}
table {
margin: 1em 0;
border-collapse: collapse;
width: 100%;
overflow-x: auto;
display: block;
font-variant-numeric: lining-nums tabular-nums;
}
table caption {
margin-bottom: 0.75em;
}
tbody {
margin-top: 0.5em;
border-top: 1px solid #1a1a1a;
border-bottom: 1px solid #1a1a1a;
}
th {
border-top: 1px solid #1a1a1a;
padding: 0.25em 0.5em 0.25em 0.5em;
}
td {
padding: 0.125em 0.5em 0.25em 0.5em;
}
header {
margin-bottom: 4em;
text-align: center;
}
#TOC li {
list-style: none;
}
#TOC ul {
padding-left: 1.3em;
}
#TOC > ul {
padding-left: 0;
}
#TOC a:not(:hover) {
text-decoration: none;
}
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { color: #008000; } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { color: #008000; font-weight: bold; } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
</head>
<body>
<h1 id="write">write</h1>
<blockquote>
<p>Write data to a file, replacing the file if it already exists and
creating any intermediate directories if they don't already exist. Thin
wrapper around node's native fs methods.</p>
</blockquote>
<p>Please consider following this project's author, <a
href="https://github.com/jonschlinkert">Jon Schlinkert</a>, and consider
starring the project to show your <span class="emoji"
data-emoji="heart">❤️</span> and support.</p>
<h2 id="install">Install</h2>
<p>Install with <a href="https://www.npmjs.com/">npm</a> (requires <a
href="https://nodejs.org/en/">Node.js</a> >=10):</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="ex">$</span> npm install <span class="at">--save</span> write</span></code></pre></div>
<h2 id="usage">Usage</h2>
<div class="sourceCode" id="cb2"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> write <span class="op">=</span> <span class="pp">require</span>(<span class="st">'write'</span>)<span class="op">;</span></span></code></pre></div>
<h2 id="options">Options</h2>
<p>The following options may be used with any method.</p>
<h3 id="optionsnewline">options.newline</h3>
<p><strong>Type</strong>: <code>boolean</code></p>
<p><strong>Default</strong>: <code>undefined</code></p>
<p>Ensure that contents has a trailing newline before writing it to the
file system.</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a>write<span class="op">.</span><span class="fu">sync</span>(<span class="st">'foo.txt'</span><span class="op">,</span> <span class="st">'some data...'</span><span class="op">,</span> { <span class="dt">newline</span><span class="op">:</span> <span class="kw">true</span> })<span class="op">;</span> </span></code></pre></div>
<h3 id="optionsoverwrite">options.overwrite</h3>
<p><strong>Type</strong>: <code>boolean</code></p>
<p><strong>Default</strong>: <code>undefined</code></p>
<p>Set to <code>false</code> to prevent existing files from being
overwritten. See <a href="#optionsincrement">increment</a> for a less
severe alternative.</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a>write<span class="op">.</span><span class="fu">sync</span>(<span class="st">'foo.txt'</span><span class="op">,</span> <span class="st">'some data...'</span><span class="op">,</span> { <span class="dt">overwrite</span><span class="op">:</span> <span class="kw">false</span> })<span class="op">;</span></span></code></pre></div>
<h3 id="optionsincrement">options.increment</h3>
<p><strong>Type</strong>: <code>boolean</code></p>
<p><strong>Default</strong>: <code>undefined</code></p>
<p>Set to <code>true</code> to automatically rename files by appending
an increment, like <code>foo (2).txt</code>, to prevent
<code>foo.txt</code> from being overwritten. This is useful when writing
log files, or other information where the file name is less important
than the contents being written.</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a>write<span class="op">.</span><span class="fu">sync</span>(<span class="st">'foo.txt'</span><span class="op">,</span> <span class="st">'some data...'</span><span class="op">,</span> { <span class="dt">increment</span><span class="op">:</span> <span class="kw">true</span> })<span class="op">;</span></span>
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="co">// if "foo.txt" exists, the file will be renamed to "foo (2).txt"</span></span></code></pre></div>
<h2 id="api">API</h2>
<h3 id="write-1"><a href="index.js#L41">write</a></h3>
<p>Asynchronously writes data to a file, replacing the file if it
already exists and creating any intermediate directories if they don't
already exist. Data can be a string or a buffer. Returns a promise if a
callback function is not passed.</p>
<p><strong>Params</strong></p>
<ul>
<li><code>filepath</code> <strong>{String}</strong>: file path.</li>
<li><code>data</code> <strong>{String|Buffer|Uint8Array}</strong>: Data
to write.</li>
<li><code>options</code> <strong>{Object}</strong>: Options to pass to
<a
href="https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback">fs.writeFile</a></li>
<li><code>callback</code> <strong>{Function}</strong>: (optional) If no
callback is provided, a promise is returned.</li>
<li><code>returns</code> <strong>{Object}</strong>: Returns an object
with the <code>path</code> and <code>contents</code> of the file that
was written to the file system. This is useful for debugging when
<code>options.increment</code> is used and the path might have been
modified.</li>
</ul>
<p><strong>Example</strong></p>
<div class="sourceCode" id="cb6"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> write <span class="op">=</span> <span class="pp">require</span>(<span class="st">'write'</span>)<span class="op">;</span></span>
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a><span class="co">// async/await</span></span>
<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a>(<span class="kw">async</span> () <span class="kw">=></span> {</span>
<span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a> <span class="cf">await</span> <span class="fu">write</span>(<span class="st">'foo.txt'</span><span class="op">,</span> <span class="st">'This is content...'</span>)<span class="op">;</span></span>
<span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a>})()<span class="op">;</span></span>
<span id="cb6-7"><a href="#cb6-7" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb6-8"><a href="#cb6-8" aria-hidden="true" tabindex="-1"></a><span class="co">// promise</span></span>
<span id="cb6-9"><a href="#cb6-9" aria-hidden="true" tabindex="-1"></a><span class="fu">write</span>(<span class="st">'foo.txt'</span><span class="op">,</span> <span class="st">'This is content...'</span>)</span>
<span id="cb6-10"><a href="#cb6-10" aria-hidden="true" tabindex="-1"></a> <span class="op">.</span><span class="fu">then</span>(() <span class="kw">=></span> {</span>
<span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a> <span class="co">// do stuff</span></span>
<span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a> })<span class="op">;</span></span>
<span id="cb6-13"><a href="#cb6-13" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb6-14"><a href="#cb6-14" aria-hidden="true" tabindex="-1"></a><span class="co">// callback</span></span>
<span id="cb6-15"><a href="#cb6-15" aria-hidden="true" tabindex="-1"></a><span class="fu">write</span>(<span class="st">'foo.txt'</span><span class="op">,</span> <span class="st">'This is content...'</span><span class="op">,</span> err <span class="kw">=></span> {</span>
<span id="cb6-16"><a href="#cb6-16" aria-hidden="true" tabindex="-1"></a> <span class="co">// do stuff with err</span></span>
<span id="cb6-17"><a href="#cb6-17" aria-hidden="true" tabindex="-1"></a>})<span class="op">;</span></span></code></pre></div>
<h3 id="sync"><a href="index.js#L88">.sync</a></h3>
<p>The synchronous version of <a href="#write">write</a>. Returns
undefined.</p>
<p><strong>Params</strong></p>
<ul>
<li><code>filepath</code> <strong>{String}</strong>: file path.</li>
<li><code>data</code> <strong>{String|Buffer|Uint8Array}</strong>: Data
to write.</li>
<li><code>options</code> <strong>{Object}</strong>: Options to pass to
<a
href="https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options">fs.writeFileSync</a></li>
<li><code>returns</code> <strong>{Object}</strong>: Returns an object
with the <code>path</code> and <code>contents</code> of the file that
was written to the file system. This is useful for debugging when
<code>options.increment</code> is used and the path might have been
modified.</li>
</ul>
<p><strong>Example</strong></p>
<div class="sourceCode" id="cb7"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> write <span class="op">=</span> <span class="pp">require</span>(<span class="st">'write'</span>)<span class="op">;</span></span>
<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a>write<span class="op">.</span><span class="fu">sync</span>(<span class="st">'foo.txt'</span><span class="op">,</span> <span class="st">'This is content...'</span>)<span class="op">;</span></span></code></pre></div>
<h3 id="stream"><a href="index.js#L127">.stream</a></h3>
<p>Returns a new <a
href="https://nodejs.org/api/fs.html#fs_class_fs_writestream">WriteStream</a>
object. Uses <code>fs.createWriteStream</code> to write data to a file,
replacing the file if it already exists and creating any intermediate
directories if they don't already exist. Data can be a string or a
buffer.</p>
<p><strong>Params</strong></p>
<ul>
<li><code>filepath</code> <strong>{String}</strong>: file path.</li>
<li><code>options</code> <strong>{Object}</strong>: Options to pass to
<a
href="https://nodejs.org/api/fs.html#fs_fs_createwritestream_path_options">fs.createWriteStream</a></li>
<li><code>returns</code> <strong>{Stream}</strong>: Returns a new <a
href="https://nodejs.org/api/fs.html#fs_class_fs_writestream">WriteStream</a>
object. (See <a
href="https://nodejs.org/api/stream.html#stream_class_stream_writable">Writable
Stream</a>).</li>
</ul>
<p><strong>Example</strong></p>
<div class="sourceCode" id="cb8"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> fs <span class="op">=</span> <span class="pp">require</span>(<span class="st">'fs'</span>)<span class="op">;</span></span>
<span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a><span class="kw">const</span> write <span class="op">=</span> <span class="pp">require</span>(<span class="st">'write'</span>)<span class="op">;</span></span>
<span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a>fs<span class="op">.</span><span class="fu">createReadStream</span>(<span class="st">'README.md'</span>)</span>
<span id="cb8-4"><a href="#cb8-4" aria-hidden="true" tabindex="-1"></a> <span class="op">.</span><span class="fu">pipe</span>(write<span class="op">.</span><span class="fu">stream</span>(<span class="st">'a/b/c/other-file.md'</span>))</span>
<span id="cb8-5"><a href="#cb8-5" aria-hidden="true" tabindex="-1"></a> <span class="op">.</span><span class="fu">on</span>(<span class="st">'close'</span><span class="op">,</span> () <span class="kw">=></span> {</span>
<span id="cb8-6"><a href="#cb8-6" aria-hidden="true" tabindex="-1"></a> <span class="co">// do stuff</span></span>
<span id="cb8-7"><a href="#cb8-7" aria-hidden="true" tabindex="-1"></a> })<span class="op">;</span></span></code></pre></div>
<h2 id="release-history">Release history</h2>
<p>See [CHANGELOG.md].</p>
<h2 id="about">About</h2>
<details>
<summary><strong>Contributing</strong></summary>
<p>Pull requests and stars are always welcome. For bugs and feature
requests, <a href="../../issues/new">please create an issue</a>.</p>
</details>
<details>
<summary><strong>Running Tests</strong></summary>
<p>Running and reviewing unit tests is a great way to get familiarized
with a library and its API. You can install dependencies and run tests
with the following command:</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="ex">$</span> npm install <span class="kw">&&</span> <span class="ex">npm</span> test</span></code></pre></div>
</details>
<details>
<summary><strong>Building docs</strong></summary>
<p><em>(This project's readme.md is generated by <a
href="https://github.com/verbose/verb-generate-readme">verb</a>, please
don't edit the readme directly. Any changes to the readme must be made
in the <a href=".verb.md">.verb.md</a> readme template.)</em></p>
<p>To generate the readme, run the following command:</p>
<div class="sourceCode" id="cb10"><pre
class="sourceCode sh"><code class="sourceCode bash"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="ex">$</span> npm install <span class="at">-g</span> verbose/verb#dev verb-generate-readme <span class="kw">&&</span> <span class="ex">verb</span></span></code></pre></div>
</details>
<h3 id="related-projects">Related projects</h3>
<p>You might also be interested in these projects:</p>
<ul>
<li><a
href="https://www.npmjs.com/package/add-filename-increment">add-filename-increment</a>:
When copying or moving files, it's common for operating systems to
automatically add an increment… <a
href="https://github.com/jonschlinkert/add-filename-increment">more</a>
| <a href="https://github.com/jonschlinkert/add-filename-increment"
title="When copying or moving files, it's common for operating systems to automatically add an increment or 'copy' to duplicate file names. This does that for Node.js applications, with automatic platform detection and support for Linux, MacOs, and Windows conve">homepage</a></li>
<li><a href="https://www.npmjs.com/package/delete">delete</a>: Delete
files and folders and any intermediate directories if they exist (sync
and async). | <a href="https://github.com/jonschlinkert/delete"
title="Delete files and folders and any intermediate directories if they exist (sync and async).">homepage</a></li>
<li><a href="https://www.npmjs.com/package/read-data">read-data</a>:
Read JSON or YAML files. | <a
href="https://github.com/jonschlinkert/read-data"
title="Read JSON or YAML files.">homepage</a></li>
<li><a href="https://www.npmjs.com/package/read-yaml">read-yaml</a>:
Very thin wrapper around js-yaml for directly reading in YAML files. |
<a href="https://github.com/jonschlinkert/read-yaml"
title="Very thin wrapper around js-yaml for directly reading in YAML files.">homepage</a></li>
<li><a
href="https://www.npmjs.com/package/strip-filename-increment">strip-filename-increment</a>:
Operating systems commonly add a trailing increment, or the word 'copy',
or something similar to… <a
href="https://github.com/jonschlinkert/strip-filename-increment">more</a>
| <a href="https://github.com/jonschlinkert/strip-filename-increment"
title="Operating systems commonly add a trailing increment, or the word 'copy', or something similar to duplicate files. This strips those increments. Tested on Windows, MacOS, and Linux.">homepage</a></li>
<li><a href="https://www.npmjs.com/package/write-data">write-data</a>:
Write a YAML or JSON file to disk. Automatically detects the format to
write based… <a
href="https://github.com/jonschlinkert/write-data">more</a> | <a
href="https://github.com/jonschlinkert/write-data"
title="Write a YAML or JSON file to disk. Automatically detects the format to write based on extension. Or pass `ext` on the options.">homepage</a></li>
<li><a href="https://www.npmjs.com/package/write-json">write-json</a>:
Write a JSON file to disk, also creates intermediate directories in the
destination path if… <a
href="https://github.com/jonschlinkert/write-json">more</a> | <a
href="https://github.com/jonschlinkert/write-json"
title="Write a JSON file to disk, also creates intermediate directories in the destination path if they don't already exist.">homepage</a></li>
<li><a href="https://www.npmjs.com/package/write-yaml">write-yaml</a>:
Write YAML. Converts JSON to YAML writes it to the specified file. | <a
href="https://github.com/jonschlinkert/write-yaml"
title="Write YAML. Converts JSON to YAML writes it to the specified file.">homepage</a></li>
</ul>
<h3 id="contributors">Contributors</h3>
<table>
<thead>
<tr class="header">
<th><strong>Commits</strong></th>
<th><strong>Contributor</strong></th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>42</td>
<td><a href="https://github.com/jonschlinkert">jonschlinkert</a></td>
</tr>
<tr class="even">
<td>2</td>
<td><a href="https://github.com/jpetitcolas">jpetitcolas</a></td>
</tr>
<tr class="odd">
<td>1</td>
<td><a href="https://github.com/tunnckoCore">tunnckoCore</a></td>
</tr>
</tbody>
</table>
<h3 id="author">Author</h3>
<p><strong>Jon Schlinkert</strong></p>
<ul>
<li><a href="https://github.com/jonschlinkert">GitHub Profile</a></li>
<li><a href="https://twitter.com/jonschlinkert">Twitter Profile</a></li>
<li><a href="https://linkedin.com/in/jonschlinkert">LinkedIn
Profile</a></li>
</ul>
<h3 id="license">License</h3>
<p>Copyright © 2019, <a href="https://github.com/jonschlinkert">Jon
Schlinkert</a>. Released under the <a href="LICENSE">MIT
License</a>.</p>
<hr />
<p><em>This file was generated by <a
href="https://github.com/verbose/verb-generate-readme">verb-generate-readme</a>,
v0.8.0, on September 04, 2019.</em></p>
</body>
</html>
|