mthl
/
texinfo


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194
							<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Reading and writing whole files</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Overall-Index.xhtml" title="Index"/>
    <link rel="next" href="Ports.xhtml" title="Ports"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Reading and writing whole files" epub:type="subchapter" id="Reading-and-writing-whole-files">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Reading and writing whole files</h2>
          </div>
        </div>
      </div>
      <p>The following procedures and syntax allow you to read and write
the entire contents of a file, without iterating using a port.
</p>
      <section class="sect2" title="Reading a file" epub:type="division" id="idm139667872829760">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Reading a file</h3>
            </div>
          </div>
        </div>
        <p>For reading the contents of a file in a single operation,
you can use the following syntax:
</p>
        <div class="literallayout">
          <p><code class="literal"><span class="bold"><strong>&amp;&lt;{</strong></span></code><a class="link" href="Named-quasi-literals.xhtml#meta-named-literal-part"><em class="replaceable"><code>named-literal-part</code></em></a>+<code class="literal"><span class="bold"><strong>}</strong></span></code><br/>
</p>
        </div>
        <p>This is equivalent to using the <code class="literal">path-data</code> function (defined below):
</p>
        <div class="literallayout">
          <p><code class="literal"><span class="bold"><strong>(path-data</strong></span></code> <code class="literal"><span class="bold"><strong>&amp;{</strong></span></code><a class="link" href="Named-quasi-literals.xhtml#meta-named-literal-part"><em class="replaceable"><code>named-literal-part</code></em></a>+<code class="literal"><span class="bold"><strong>})</strong></span></code><br/>
</p>
        </div>
        <p>For example:
</p>
        <pre class="screen">(define dir "/home/me/")
(define help-message &amp;&lt;{&amp;[dir]HELP})
</pre>
        <p>This binds <code class="literal">help-message</code> to the contents of the file
named <code class="literal">HELP</code> in the <code class="literal">dir</code> directory.
</p>
        <span id="Blobs"/>
      </section>
      <section class="sect2" title="Blobs" epub:type="division" id="idm139667872818656">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Blobs</h3>
            </div>
          </div>
        </div>
        <p>The content of a file is, in general, a sequence of uninterpreted bytes.
Often these bytes represent text in a locale-dependent encoding,
but we don’t always know this. Sometimes they’re images, or videos,
or word-processor documents.  A filename extension or a “magic number”
in the file can give you hints, but not certainty as to the type of the data.
</p>
        <p>A <em class="firstterm"><a class="ulink" href="http://en.wikipedia.org/wiki/Binary_large_object" target="_top">blob</a></em>
is a raw uninterpreted sequence of bytes. It is a <code class="literal">bytevector</code>
that can be automatically converted to other types as needed,
specifically to a string or a bytevector.
</p>
        <p>The <code class="literal">&amp;&lt;{..}</code> returns a blob.  For example,
assume the file <code class="literal">README</code> contains (bytes representing)
the text <code class="literal">"Check doc directory.\n"</code>.  Then:
</p>
        <pre class="screen">#|kawa:1|# (define readme &amp;&lt;{README}))
|kawa:2|# readme:class
class gnu.lists.Blob
#|kawa:3|# (write (-&gt;string readme))
"Check doc directory.\n"
#|kawa:4|# (write (-&gt;bytevector readme))
#u8(67 104 101 99 107 32 100 111 99 32 100 105 114 101 99 116 111 114 121 46 10)
#|kawa:5|# (-&gt;bytevector readme):class
class gnu.lists.U8Vector
</pre>
      </section>
      <section class="sect2" title="Writing to a file" epub:type="division" id="idm139667872811728">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Writing to a file</h3>
            </div>
          </div>
        </div>
        <p>The <code class="literal">&amp;&lt;{..}</code> syntax can be used with <code class="literal">set!</code>
to replace the contents of a file:
</p>
        <pre class="screen">(set! &amp;&lt;{README} "Check example.com\n")
</pre>
        <p>The new contents must be blob-compatible - i.e. a bytevector or a string.
</p>
        <p>If you dislike using <code class="literal">&lt;</code> as an output operator, you can instead using the <code class="literal">&amp;&gt;{..}</code> operation, which evaluates to a function whose single argument is the new value:
</p>
        <pre class="screen">(&amp;&gt;{README} "Check example.com\n")
</pre>
        <p>In general:
</p>
        <pre class="screen"><code class="literal"><span class="bold"><strong>&amp;&gt;{</strong></span></code><a class="link" href="Named-quasi-literals.xhtml#meta-named-literal-part"><em class="replaceable"><code>named-literal-part</code></em></a>+<code class="literal"><span class="bold"><strong>}</strong></span></code>
</pre>
        <p>is equivalent to:
</p>
        <pre class="screen">(lambda (new-contents)
  (set! <code class="literal"><span class="bold"><strong>&amp;&lt;{</strong></span></code><a class="link" href="Named-quasi-literals.xhtml#meta-named-literal-part"><em class="replaceable"><code>named-literal-part</code></em></a>+<code class="literal"><span class="bold"><strong>}</strong></span></code> new-contents))
</pre>
        <p>You can use <code class="literal">&amp;&gt;&gt;</code> to append more data to a file:
</p>
        <pre class="screen">(&amp;&gt;&gt;{README} "or check example2.com\n")
</pre>
      </section>
      <section class="sect2" title="Functions" epub:type="division" id="idm139667872799632">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Functions</h3>
            </div>
          </div>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667872798560" class="indexterm"/> <code class="function">path-data</code> <em class="replaceable"><code>path</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Reads the contents of the file specified by <em class="replaceable"><code>path</code></em>,
where <em class="replaceable"><code>path</code></em> can be a <a class="link" href="Paths.xhtml" title="Paths - file name, URLs, and URIs">path</a> object, or anything that can
be converted to a <code class="literal">Path</code>, including a filename string or a URL. 
returning the result as a blob.
The result is a <span class="emphasis"><em>blob</em></span>, which is a kind of bytevector than can be
auto-converted to a string or bytevecor as required.
</p>
            <p>The function <code class="literal">path-data</code> has a setter, which replaces the contents
with new contents:
</p>
            <pre class="screen">(set! &amp;&lt;{file-name} new-contents)
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667872791216" class="indexterm"/> <code class="function">path-bytes</code> <em class="replaceable"><code>path</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Reads the contents of the file specified by <em class="replaceable"><code>path</code></em>, as
with the <code class="literal">path-data</code> function, but the result is a plain bytevector,
rather than a blob.  This functtion also has a setter, which you
can use to replace the file-contents by new bytevector-valued data.
</p>
          </blockquote>
        </div>
      </section>
    </section>
    <footer>
      <div class="navfooter">
        <ul>
          <li>
            <b class="toc">
              <a href="Reading-and-writing-whole-files.xhtml#idm139667872829760">Reading a file</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Reading-and-writing-whole-files.xhtml#idm139667872818656">Blobs</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Reading-and-writing-whole-files.xhtml#idm139667872811728">Writing to a file</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Reading-and-writing-whole-files.xhtml#idm139667872799632">Functions</a>
            </b>
          </li>
        </ul>
        <p>
          Up: <a accesskey="u" href="Input-Output.xhtml">Input, output, and file handling</a></p>
        <p>
        Previous: <a accesskey="p" href="Files.xhtml">File System Interface</a></p>
        <p>
        Next: <a accesskey="n" href="Ports.xhtml">Ports</a></p>
      </div>
    </footer>
  </body>
</html>