Mirror/wren
1
0
Fork 1
mirror of https://github.com/wren-lang/wren.git synced 2026-01-12 22:58:40 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
99bc2be625fee97cd1ccc13d19966d56ae2edacc
wren/modules/io/file.html
Bob Nystrom 5cac3af2f2 Fresh docs!
2017-10-19 07:05:45 -07:00

181 lines
11 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-type" content="text/html;charset=UTF-8" />
<title>File Class &ndash; Wren</title>
<link rel="stylesheet" type="text/css" href="../../style.css" />
<link href='//fonts.googleapis.com/css?family=Source+Sans+Pro:400,700,400italic,700italic|Source+Code+Pro:400|Lato:400|Sanchez:400italic,400' rel='stylesheet' type='text/css'>
<!-- Tell mobile browsers we're optimized for them and they don't need to crop
the viewport. -->
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1"/>
</head>
<body id="top" class="module">
<header>
<div class="page">
<div class="main-column">
<h1><a href="../../">wren</a></h1>
<h2>a classy little scripting language</h2>
</div>
</div>
</header>
<div class="page">
<nav class="big">
<ul>
<li><a href="../">Modules</a></li>
<li><a href="./">io</a></li>
</ul>
<section>
<h2>io classes</h2>
<ul>
<li><a href="directory.html">Directory</a></li>
<li><a href="file.html">File</a></li>
<li><a href="file-flags.html">FileFlags</a></li>
<li><a href="stat.html">Stat</a></li>
<li><a href="stdin.html">Stdin</a></li>
<li><a href="stdout.html">Stdout</a></li>
</ul>
</section>
</nav>
<nav class="small">
<table>
<tr>
<td><a href="../">Modules</a></td>
<td><a href="./">io</a></td>
</tr>
<tr>
<td colspan="2"><h2>io classes</h2></td>
</tr>
<tr>
<td>
<ul>
<li><a href="directory.html">Directory</a></li>
<li><a href="file.html">File</a></li>
<li><a href="file-flags.html">FileFlags</a></li>
</ul>
</td>
<td>
<ul>
<li><a href="stat.html">Stat</a></li>
<li><a href="stdin.html">Stdin</a></li>
<li><a href="stdout.html">Stdout</a></li>
</ul>
</td>
</tr>
</table>
</nav>
<main>
<h1>File Class</h1>
<p>Lets you work with files on the file system. An instance of this class
represents an open file with a file descriptor. </p>
<p>When you are done with a file object, it&rsquo;s a good idea to explicitly close it.
If you don&rsquo;t, the GC will close it when the file is no longer used and gets
finalized, but that may take a while. In the meantime, leaving it open wastes
a file descriptor. </p>
<h2>Static Methods <a href="#static-methods" name="static-methods" class="header-anchor">#</a></h2>
<h3>File.<strong>create</strong>(path, fn) <a href="#file.create(path,-fn)" name="file.create(path,-fn)" class="header-anchor">#</a></h3>
<p>Opens the file at <code>path</code> for writing and passes it to <code>fn</code>. If there is already
a file at that path, it is truncated. After the function returns, the file is
automatically closed. </p>
<div class="codehilite"><pre><span></span><span class="vg">File</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="s">&quot;numbers.txt&quot;</span><span class="p">)</span> <span class="p">{</span><span class="o">|</span><span class="n">file</span><span class="o">|</span>
<span class="n">file</span><span class="o">.</span><span class="n">writeBytes</span><span class="p">(</span><span class="s">&quot;one two three&quot;</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
<h3>File.<strong>delete</strong>(path) <a href="#file.delete(path)" name="file.delete(path)" class="header-anchor">#</a></h3>
<p>Deletes the file at <code>path</code>. </p>
<h3>File.<strong>exists</strong>(path) <a href="#file.exists(path)" name="file.exists(path)" class="header-anchor">#</a></h3>
<p>Whether a regular file exists at <code>path</code>. This returns <code>false</code> for directories
or other special file system entities. </p>
<h3>File.<strong>open</strong>(path, fn) <a href="#file.open(path,-fn)" name="file.open(path,-fn)" class="header-anchor">#</a></h3>
<p>Opens the file at <code>path</code> for reading and passes it to <code>fn</code>. After the function
returns, the file is automatically closed. </p>
<div class="codehilite"><pre><span></span><span class="vg">File</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s">&quot;words.txt&quot;</span><span class="p">)</span> <span class="p">{</span><span class="o">|</span><span class="n">file</span><span class="o">|</span>
<span class="n">file</span><span class="o">.</span><span class="n">readBytes</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
<h3>File.<strong>read</strong>(path) <a href="#file.read(path)" name="file.read(path)" class="header-anchor">#</a></h3>
<p>Reads the entire contents of the file at <code>path</code> and returns it as a string. </p>
<div class="codehilite"><pre><span></span><span class="vg">File</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="s">&quot;words.txt&quot;</span><span class="p">)</span>
</pre></div>
<p>No encoding or decoding is done. If the file is UTF-8, then the resulting
string will be a UTF-8 string. Otherwise, it will be a string of bytes in
whatever encoding the file uses. </p>
<h3>File.<strong>realPath</strong>(path) <a href="#file.realpath(path)" name="file.realpath(path)" class="header-anchor">#</a></h3>
<p>Resolves <code>path</code>, traversing symlinks and removining any unneeded <code>./</code> and <code>../</code>
components. Returns the canonical absolute path to the file. </p>
<div class="codehilite"><pre><span></span><span class="k">var</span> <span class="n">path</span> <span class="o">=</span> <span class="s">&quot;/some/./symlink/a/../b/file.txt&quot;</span>
<span class="vg">System</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="vg">File</span><span class="o">.</span><span class="n">realPath</span><span class="p">(</span><span class="n">path</span><span class="p">))</span> <span class="output">/real/path/a/file.txt</span>
</pre></div>
<h3>File.<strong>size</strong>(path) <a href="#file.size(path)" name="file.size(path)" class="header-anchor">#</a></h3>
<p>Returns the size in bytes of the contents of the file at <code>path</code>. </p>
<h2>Constructors <a href="#constructors" name="constructors" class="header-anchor">#</a></h2>
<h3>File.<strong>create</strong>(path) <a href="#file.create(path)" name="file.create(path)" class="header-anchor">#</a></h3>
<p>Opens the file at <code>path</code> for writing. If there is already a file at that path,
it is truncated. </p>
<div class="codehilite"><pre><span></span><span class="k">var</span> <span class="n">file</span> <span class="o">=</span> <span class="vg">File</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="s">&quot;colors.txt&quot;</span><span class="p">)</span>
<span class="n">file</span><span class="o">.</span><span class="n">writeBytes</span><span class="p">(</span><span class="s">&quot;chartreuse lime teal&quot;</span><span class="p">)</span>
<span class="n">file</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
<h3>File.<strong>open</strong>(path) <a href="#file.open(path)" name="file.open(path)" class="header-anchor">#</a></h3>
<p>Opens the file at <code>path</code> for reading. You are responsible for closing it when
done with it. </p>
<h2>Methods <a href="#methods" name="methods" class="header-anchor">#</a></h2>
<h3><strong>descriptor</strong> <a href="#descriptor" name="descriptor" class="header-anchor">#</a></h3>
<p>The numeric file descriptor used to access the file. </p>
<h3><strong>isOpen</strong> <a href="#isopen" name="isopen" class="header-anchor">#</a></h3>
<p>Whether the file is still open or has been closed. </p>
<h3><strong>size</strong> <a href="#size" name="size" class="header-anchor">#</a></h3>
<p>The size of the contents of the file in bytes. </p>
<h3><strong>close</strong>() <a href="#close()" name="close()" class="header-anchor">#</a></h3>
<p>Closes the file. After calling this, you can read or write from it. </p>
<h3><strong>readBytes</strong>(count) <a href="#readbytes(count)" name="readbytes(count)" class="header-anchor">#</a></h3>
<p>Reads up to <code>count</code> bytes starting from the beginning of the file. </p>
<div class="codehilite"><pre><span></span><span class="c1">// Assume this file contains &quot;I am a file!&quot;.</span>
<span class="vg">File</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s">&quot;example.txt&quot;</span><span class="p">)</span> <span class="p">{</span><span class="o">|</span><span class="n">file</span><span class="o">|</span>
<span class="vg">System</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="n">file</span><span class="o">.</span><span class="n">readBytes</span><span class="p">(</span><span class="mi">6</span><span class="p">))</span> <span class="output">I am a</span>
<span class="p">}</span>
</pre></div>
<h3><strong>readBytes</strong>(count, offset) <a href="#readbytes(count,-offset)" name="readbytes(count,-offset)" class="header-anchor">#</a></h3>
<p>Reads up to <code>count</code> bytes starting at <code>offset</code> bytes from the beginning of
the file. </p>
<div class="codehilite"><pre><span></span><span class="c1">// Assume this file contains &quot;I am a file!&quot;.</span>
<span class="vg">File</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s">&quot;example.txt&quot;</span><span class="p">)</span> <span class="p">{</span><span class="o">|</span><span class="n">file</span><span class="o">|</span>
<span class="vg">System</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="n">file</span><span class="o">.</span><span class="n">readBytes</span><span class="p">(</span><span class="mi">6</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span> <span class="output">am a f</span>
<span class="p">}</span>
</pre></div>
<h3><strong>writeBytes</strong>(bytes) <a href="#writebytes(bytes)" name="writebytes(bytes)" class="header-anchor">#</a></h3>
<p>Writes the raw bytes of the string <code>bytes</code> to the end of the file. </p>
<h3><strong>writeBytes</strong>(bytes, offset) <a href="#writebytes(bytes,-offset)" name="writebytes(bytes,-offset)" class="header-anchor">#</a></h3>
<p>Writes the raw bytes of the string <code>bytes</code> to the to the file, starting at
<code>offset</code>. Any overlapping bytes already in the file at the offset are
overwritten. </p>
</main>
</div>
<footer>
<div class="page">
<div class="main-column">
<p>Wren lives
<a href="https://github.com/munificent/wren">on GitHub</a>
&mdash; Made with &#x2764; by
<a href="http://journal.stuffwithstuff.com/">Bob Nystrom</a> and
<a href="https://github.com/munificent/wren/blob/master/AUTHORS">friends</a>.
</p>
<div class="main-column">
</div>
</footer>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink