/usr/share/mozart/doc/op/node6.html is in mozart-doc 1.4.0-8ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD><TITLE>3.1 Basic Patterns of Use</TITLE><LINK href="ozdoc.css" rel="stylesheet" type="text/css"></HEAD><BODY><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node5.html">- Up -</A></TD><TD><A href="node7.html#section.files.expand-a">Next >></A></TD></TR></TABLE><DIV id="section.files.basic"><H2><A name="section.files.basic">3.1 Basic Patterns of Use</A></H2><P> The basic idea of how to use files in Mozart is as follows. We provide a class <CODE>Open<SPAN class="keyword">.</SPAN>file</CODE>. To an object created from this class we refer to as <A name="label39"></A><EM>file object</EM><A name="label40"></A>. Conceptually, its state consists of a string together with the current position in this string called <A name="label41"></A><EM>seek pointer</EM>. </P><P> In the following, we will refer to this particular string as <A name="label42"></A><EM>file</EM>. It is visible to other operating system processes via the operating system's filesystem. </P><P> The atoms used for labels and fields of methods of the class <CODE>Open<SPAN class="keyword">.</SPAN>file</CODE> are chosen to coincide with the common operating system terminology (i. e., POSIX terminology). </P><H3><A name="label43">3.1.1 Reading a File</A></H3><P> Suppose we want to read data from a file named <CODE>a.txt</CODE>. The contents of this file is as follows<A href="node6.html#label70"><SUP>1</SUP></A>: </P><TABLE align="center" bgcolor="#f0f0e0"><TR valign="top"><TH><P></P></TH><TH><P>0</P></TH><TH><P>1</P></TH><TH><P>2</P></TH><TH><P>3</P></TH><TH><P>4</P></TH><TH><P>5</P></TH><TH><P>6</P></TH><TH><P>7</P></TH><TH><P>8</P></TH><TH><P>9</P></TH></TR><TR valign="top"><TH><P>0</P></TH><TD><P>H</P></TD><TD><P>e</P></TD><TD><P>l</P></TD><TD><P>l</P></TD><TD><P>o</P></TD><TD><P>H</P></TD><TD><P>e</P></TD><TD><P>l</P></TD><TD><P>l</P></TD><TD><P>o</P></TD></TR><TR valign="top"><TH><P>10</P></TH><TD><P>O</P></TD><TD><P>z</P></TD><TD><P>_</P></TD><TD><P>I</P></TD><TD><P>s</P></TD><TD><P>_</P></TD><TD><P>b</P></TD><TD><P>e</P></TD><TD><P>a</P></TD><TD><P>u</P></TD></TR><TR valign="top"><TH><P>20</P></TH><TD><P>t</P></TD><TD><P>i</P></TD><TD><P>f</P></TD><TD><P>u</P></TD><TD><P>l</P></TD><TD><P></P></TD><TD><P></P></TD><TD><P></P></TD><TD><P></P></TD><TD><P></P></TD></TR></TABLE><P> </P><P> The first step is to create a file object and associate it to the file <CODE>a.txt</CODE>. This is done by feeding </P><DL class="anonymous"><DD class="code"><CODE>F={New Open<SPAN class="keyword">.</SPAN>file init(name:<SPAN class="string">'a.txt'</SPAN> flags:[read])}</CODE></DD></DL><P> <A name="label45"></A> The list <CODE>[read]</CODE> used as value of the field <CODE>flags</CODE> means that we want to have read access to the file. </P><P> After the file has been opened and associated to the file object <CODE>F</CODE>, we can read from it. To read the next five characters from the file we feed </P><DL class="anonymous"><DD class="code"><CODE>{F read(list:{Browse} size:5)}</CODE></DD></DL><P> <A name="label47"></A> The character string <CODE>Hello</CODE> appears in the browser window (the value <CODE>5</CODE> at the field <CODE>size</CODE> signals that we want to read five characters from the file). </P><P> Note that if we had not switched the browser to the mode for displaying virtual strings (see <A href="node2.html#chapter.data">Chapter 2</A>), we would have seen the output <CODE>[72 101 108 108 111]</CODE> in the browser window. </P><P> A common pattern of use is to read the entire file into an Oz string. This is especially supported. Feed: </P><DL class="anonymous"><DD class="code"><CODE>{F read(list:{Browse} size:all)}</CODE></DD></DL><P> <A name="label49"></A> The rest of the file <CODE>HelloOz is beautiful</CODE> appears in the browser window. </P><P> Up to now we have read the data in strict left to right fashion. Suppose we want to start reading at the eighth character of the file. Navigating to this character and reading the following five characters is done by: </P><DL class="anonymous"><DD class="code"><CODE>{F seek(whence:set offset:7)}<BR>{F read(list:{Browse} size:5)}</CODE></DD></DL><P> <A name="label51"></A> <A name="label53"></A> You will see <CODE>lloOz</CODE> in the browser window. Internally, as already mentioned, each file object has a <A name="label54"></A><EM>seek pointer</EM>. Each operation refers to its position: for instance, instead of ``reading five characters'' one should think of ``reading the next five characters after the seek pointer''. Note that in order to read the first character of a file, the seek pointer must be set to the offset zero. </P><P> Furthermore, you can get the current position of the seek pointer by: </P><DL class="anonymous"><DD class="code"><CODE>{F tell(offset:{Browse})}</CODE></DD></DL><P> <A name="label56"></A> The number <CODE>12</CODE> appears in the browser window. </P><H3><A name="label57">3.1.2 Closing a File</A></H3><P> After use, the file object <CODE>F</CODE> must be closed. By applying <CODE>F</CODE> to the message <CODE>close</CODE>: </P><DL class="anonymous"><DD class="code"><CODE>{F close}</CODE></DD></DL><P> <A name="label59"></A> the file as well as the file object are closed. Note that invoking a method other than <CODE>close</CODE> of the class <CODE>Open<SPAN class="keyword">.</SPAN>file</CODE> after the object has been closed raises an exception. Exceptions are discussed later. </P><H3><A name="label60">3.1.3 Writing a File</A></H3><P> Suppose we want to create an object for a file which does not yet exist and that should be named <CODE>ours.txt</CODE>. Furthermore, this file should have read and write access rights for yourself and for each member of your group. We feed </P><DL class="anonymous"><DD class="code"><CODE>F={New Open<SPAN class="keyword">.</SPAN>file <BR> init(name: <SPAN class="string">'ours.txt'</SPAN> <BR> flags: [write create]<BR> mode: mode(owner: [read write] <BR> group: [read write]))}</CODE></DD></DL><P> <A name="label62"></A> Data to be written to the file must be virtual strings. For example, the character sequence <CODE><SPAN class="string">"Go ahead"</SPAN></CODE> can be written to the file <CODE>F</CODE> by </P><DL class="anonymous"><DD class="code"><CODE>{F write(vs:<SPAN class="string">'Go ahead!'</SPAN>)}</CODE></DD></DL><P> <A name="label64"></A> The same character sequence we also can write by </P><DL class="anonymous"><DD class="code"><CODE>{F write(vs:<SPAN class="string">"Go ahead!"</SPAN>)}</CODE></DD></DL><P> <A name="label66"></A> </P><P> Also more complex virtual strings are handled this way. For example </P><DL class="anonymous"><DD class="code"><CODE>{F write(vs:<SPAN class="string">"This is "</SPAN><SPAN class="keyword">#</SPAN>1<SPAN class="keyword">#</SPAN><SPAN class="string">' And '</SPAN><SPAN class="keyword">#</SPAN> <BR> (<SPAN class="string">"now a float: "</SPAN><SPAN class="keyword">#</SPAN>2<SPAN class="keyword">.</SPAN>0)<SPAN class="keyword">#</SPAN><SPAN class="string">"\n"</SPAN>)}</CODE></DD></DL><P> <A name="label68"></A> writes a nested virtual string containing integers, atoms, strings and floats to the file. Even the filename argument of the <CODE>init</CODE> method of class <CODE>Open<SPAN class="keyword">.</SPAN>file</CODE> is allowed to be a virtual string. For more information on virtual strings see <A href="node4.html#section.data.virtualstrings">Section 2.2</A>. </P><P> If you type the Unix command </P><BLOCKQUOTE class="code"><SPAN class="index"><CODE>cat</CODE></SPAN><CODE> ours.txt</CODE></BLOCKQUOTE><P> or the Windows command </P><BLOCKQUOTE class="code"><CODE><SPAN class="builtin">type</SPAN> ours.txt</CODE></BLOCKQUOTE><P> to a shell, you see the content of <CODE>ours.txt</CODE> printed to standard output. </P><H3><A name="label69">3.1.4 Exceptions</A></H3><P> Functionality provided by the class <CODE>Open<SPAN class="keyword">.</SPAN>file</CODE> relies on operating system services. These services might report exceptions, these exceptions are then raised as Oz exceptions. </P><P> For example, trying to open a non existing file raises an exception. Operating system dependent exceptions can be caught as follows: </P><DL class="anonymous"><DD class="code"><CODE><SPAN class="keyword">try</SPAN> <BR> _={New Open<SPAN class="keyword">.</SPAN>file init(name:<SPAN class="string">'not-existing'</SPAN>)}<BR><SPAN class="keyword">catch</SPAN> system(os(A W I S) <SPAN class="keyword">...</SPAN>) <SPAN class="keyword">then</SPAN> <BR> {Browse os(category: A<BR> what: W<BR> number: I<BR> description: S)}<BR><SPAN class="keyword">end</SPAN></CODE></DD></DL><P> where <CODE>A</CODE> is an atom describing the category of the error (e. g., <CODE>os</CODE> or <CODE>host</CODE>), <CODE>W</CODE> the system call that raised the exception (as string), <CODE>I</CODE> is the operating system dependent error number, and <CODE>S</CODE> is a string describing the error. </P><P> Besides of operating system exceptions, the methods of the class <CODE>Open<SPAN class="keyword">.</SPAN>file</CODE> can raise two different exceptions themselves: </P><OL type="1"><LI><P>An exception is raised when an object is initialized twice. This exception can be caught as follows: </P><BLOCKQUOTE class="code"><CODE><SPAN class="keyword">try</SPAN> <BR> </CODE>...<CODE> % <SPAN class="comment">Initialize twice<BR></SPAN><SPAN class="keyword">catch</SPAN> system(open(alreadyInitialized O M) <SPAN class="keyword">...</SPAN>) <SPAN class="keyword">then</SPAN> <BR> </CODE>...<CODE> <BR><SPAN class="keyword">end</SPAN></CODE></BLOCKQUOTE><P> Here <CODE>O</CODE> is the object that has been tried to be initialized twice by applying it to the method <CODE>M</CODE>. </P></LI><LI><P>An exception is raised when a message other than <CODE>close</CODE> is executed by an already closed file object. This exception can be caught as follows: </P><BLOCKQUOTE class="code"><CODE><SPAN class="keyword">try</SPAN> <BR> </CODE>...<CODE> % <SPAN class="comment">Apply closed object<BR></SPAN><SPAN class="keyword">catch</SPAN> system(open(alreadyClosed O M) <SPAN class="keyword">...</SPAN>) <SPAN class="keyword">then</SPAN> <BR> </CODE>...<CODE> <BR><SPAN class="keyword">end</SPAN></CODE></BLOCKQUOTE><P> Here <CODE>O</CODE> is the object that has been closed already and <CODE>M</CODE> the message <CODE>O</CODE> has been applied to. </P></LI></OL><P> </P></DIV><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node5.html">- Up -</A></TD><TD><A href="node7.html#section.files.expand-a">Next >></A></TD></TR></TABLE><HR align="left" width="30%"><DIV class="footnote"><A name="label70">1. </A>The <A href="OpenProgramming.oz">demo file</A> for this document contains the Oz code to create this file.</DIV><HR><ADDRESS><A href="http://www.ps.uni-sb.de/~schulte/">Christian Schulte</A><BR><SPAN class="version">Version 1.4.0 (20110908185330)</SPAN></ADDRESS></BODY></HTML>
|