/usr/share/mozart/doc/apptut/node2.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>1 Getting Started</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="node1.html">- Up -</A></TD><TD><A href="node3.html#chapter.development">Next >></A></TD></TR></TABLE><DIV id="chapter.hello"><H1><A name="chapter.hello">1 Getting Started</A></H1><P> The purpose of programming languages is of course the construction of applications. In this chapter we will use Oz for our first small application. </P><DIV id="section.hello.webget"><H2><A name="section.hello.webget">1.1 Our First Application: <CODE>Webget.oza</CODE></A></H2><P> Our first application is a program that copies a file from a url to a local file. The program is called <CODE>Webget.oza</CODE>. </P><DIV id="figure.hello.invoke"><HR><P><A name="figure.hello.invoke"></A></P><BLOCKQUOTE class="code"><CODE>ozengine Webget.oza --in http://www.mozart-oz.org/LICENSE --out LICENSE</CODE></BLOCKQUOTE><P class="caption"><STRONG>Figure 1.1:</STRONG> Get yourself a Mozart license.</P><HR></DIV><P> </P><P> Our goal is to have an application that can be started like any other application from the operating system shell. For example, executing the command shown in <A href="node2.html#figure.hello.invoke">Figure 1.1</A> gets us a local copy of the Mozart license file. </P><P> In addition to taking arguments from the command line, <CODE>Webget.oza</CODE> should report problems by returning an error status to the operating system shell. The error status is an integer, where the value <CODE>0</CODE> means okay. Any other values signals an error. </P></DIV><DIV id="section.hello.structure"><H2><A name="section.hello.structure">1.2 What to do?</A></H2><P> In the following we consider the three main steps in constructing our application. We give a brief outline of what to do, the following sections are going to detail the steps. </P><P> </P><DL><DT>Definition </DT><DD><P>The first step, of course, is to program our application. For this purpose, we will create a file <CODE>Webget.oz</CODE> that contains the Oz program implementing <KBD>webget</KBD>. More specifically, the file <CODE>Webget.oz</CODE> contains a <EM>functor definition</EM>. </P></DD><DT>Compilation </DT><DD><P>Next, we compile the functor definition contained in <CODE>Webget.oz</CODE>. The compiler takes the functor definition and executes it. By this it creates a <EM>functor</EM>. Then the functor is written to a file <CODE>Webget.oza</CODE>. This persistent representation of a functor value is called a <EM>pickled functor</EM>. </P></DD><DT>Execution </DT><DD><P>The pickled functor <CODE>Webget.oza</CODE> is executed by the Oz virtual machine <CODE>ozengine</CODE>. The engine takes a pickled functor (<CODE>Webget.oza</CODE> in our case), unpickles the functor, runs the functor, and supplies it with application arguments. After execution terminates, it reports the application's execution status back to the operating system shell. </P></DD></DL><P> </P></DIV><DIV id="section.hello.definition"><H2><A name="section.hello.definition">1.3 Functor Definition: <CODE>Webget.oza</CODE></A></H2><P> The toplevel structure of the file <CODE>Webget.oz</CODE> is as follows. </P><P></P><DL><DT><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A name="label2">Webget.oz</A><SPAN class="chunkborder">>=</SPAN></SPAN></DT><DD class="code"><CODE><SPAN class="keyword">functor</SPAN> <BR> </CODE><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A href="node2.html#label3">Module import</A><SPAN class="chunkborder">></SPAN></SPAN><CODE> <BR> </CODE><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A href="node2.html#label5">Functor body</A><SPAN class="chunkborder">></SPAN></SPAN><CODE> <BR><SPAN class="keyword">end</SPAN></CODE></DD></DL><P> </P><DIV class="apropos"><P class="margin">Importing modules</P><P> Our application requires the system module <CODE>Application</CODE> to both process the command line arguments as well as for terminating the application. In addition, the module <CODE>Open</CODE> provides the class <CODE>Open<SPAN class="keyword">.</SPAN>file</CODE> required for reading and writing files. </P></DIV><P> The functor needs to <EM>import</EM> these two modules. The functor definition thus contains the following import specification: </P><P></P><DL><DT><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A name="label3">Module import</A><SPAN class="chunkborder">>=</SPAN></SPAN></DT><DD class="code"><CODE><SPAN class="keyword">import</SPAN> <BR> Application <BR> Open</CODE></DD></DL><P> </P><P> The import specification serves two purposes: the variable identifiers <CODE>Application</CODE> and <CODE>Open</CODE> are introduced with a lexical scope that extends over the entire body of the functor. Secondly, the identifiers also serve as <EM>module names</EM>. When the functor corresponding to this definition is executed, the variables are given as values the system modules with the same names. </P><P> More precisely, the import specification above is a convenient abbreviation for the more verbose specification below: </P><DL><DT><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A name="label4">Module import (no convenience)</A><SPAN class="chunkborder">>=</SPAN></SPAN></DT><DD class="code"><CODE><SPAN class="keyword">import</SPAN> <BR> Application <SPAN class="keyword">at</SPAN> <SPAN class="string">'x-oz://system/Application'</SPAN> <BR> Open <SPAN class="keyword">at</SPAN> <SPAN class="string">'x-oz://system/Open'</SPAN></CODE></DD></DL><P> In <A href="node4.html#section.modman.import">Section 3.3</A> we will discuss system modules in more detail. In particular, <A href="node4.html#table.modman.system">Table 3.1</A> lists available system modules. </P><DIV class="apropos"><P class="margin">Functor body</P><P> The <EM>body of a functor</EM> is a statement that is executed when the application is run. </P></DIV><P></P><DL><DT><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A name="label5">Functor body</A><SPAN class="chunkborder">>=</SPAN></SPAN></DT><DD class="code"><CODE><SPAN class="keyword">define</SPAN> <BR> </CODE><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A href="node2.html#label6">Argument processing</A><SPAN class="chunkborder">></SPAN></SPAN><CODE> <BR> Status = <SPAN class="keyword">try</SPAN> <BR> </CODE><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A href="node2.html#label7">Opening input and output files</A><SPAN class="chunkborder">></SPAN></SPAN><CODE> <BR> <SPAN class="keyword">in</SPAN> <BR> </CODE><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A href="node2.html#label8">Copying input file to output file</A><SPAN class="chunkborder">></SPAN></SPAN><CODE> <BR> 0<BR> <SPAN class="keyword">catch</SPAN> _ <SPAN class="keyword">then</SPAN> 1<BR> <SPAN class="keyword">end</SPAN> <BR> </CODE><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A href="node2.html#label9">Terminating the application</A><SPAN class="chunkborder">></SPAN></SPAN></DD></DL><P> </P><P> The structure for our application is straightforward: after processing the command line arguments, file objects for source and destination are created and the content is copied from the source file to the destination file. </P><P> If a runtime error occurs either during opening the files or while copying the file content, the raised exception is caught and the <CODE>Status</CODE> is bound to <CODE>1</CODE>. Otherwise, <CODE>Status</CODE> gets bound to zero. </P><P> Note that the body of a functor is like the part of a <CODE><SPAN class="keyword">local</SPAN> <SPAN class="keyword">...</SPAN> <SPAN class="keyword">in</SPAN> <SPAN class="keyword">...</SPAN> <SPAN class="keyword">end</SPAN></CODE> statement before the <CODE><SPAN class="keyword">in</SPAN></CODE>: definitions and statements are allowed, where the left hand side of definitions can introduce variables. </P><DIV class="apropos"><P class="margin">Processing arguments</P><P> The application needs two input parameters: the URL to get the file from, and the file name under which the downloaded content should be stored. </P></DIV><P> The following application of <CODE>Application<SPAN class="keyword">.</SPAN>getCmdArgs</CODE></P><P></P><DL><DT><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A name="label6">Argument processing</A><SPAN class="chunkborder">>=</SPAN></SPAN></DT><DD class="code"><CODE>Args = {Application<SPAN class="keyword">.</SPAN>getArgs record(<SPAN class="string">'in'</SPAN>(single type:string)<BR> <SPAN class="string">'out'</SPAN>(single type:string))}</CODE></DD></DL><P> computes <CODE>Args</CODE> to be a record (as signalled by the label <CODE>record</CODE> of the single argument to <A href="../system/node2.html#section.application.module"><CODE>Application<SPAN class="keyword">.</SPAN>getArgs</CODE></A>. The features of the record are <CODE><SPAN class="string">'in'</SPAN></CODE> and <CODE><SPAN class="string">'out'</SPAN></CODE> where both fields are of type string and both are allowed to be given only once on the command line (that is specified by <CODE>single</CODE>). </P><P> For a complete reference of how application arguments are processed see <A href="../system/node1.html#chapter.application">Chapter 1 of ``System Modules''</A>. </P><DIV class="apropos"><P class="margin">Opening input & output</P><P> The two files are opened as follows:</P></DIV><P></P><DL><DT><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A name="label7">Opening input and output files</A><SPAN class="chunkborder">>=</SPAN></SPAN></DT><DD class="code"><CODE>I={New Open<SPAN class="keyword">.</SPAN>file init(url: Args<SPAN class="keyword">.</SPAN><SPAN class="string">'in'</SPAN>)}<BR>O={New Open<SPAN class="keyword">.</SPAN>file init(name: Args<SPAN class="keyword">.</SPAN><SPAN class="string">'out'</SPAN> <BR> flags:[write create truncate])}</CODE></DD></DL><P> Note how the strings <CODE>Args<SPAN class="keyword">.</SPAN><SPAN class="string">'in'</SPAN></CODE> and <CODE>Args<SPAN class="keyword">.</SPAN><SPAN class="string">'out'</SPAN></CODE> computed by argument processing are used for the source URL and the destination filename. </P><DIV class="apropos"><P class="margin">Copying input to output</P><P> Copying the file from source to destination is straightforward: As long as we can read a non-empty string <CODE>S</CODE> from the source file, we write it to the destination file and repeat the procedure.</P></DIV><P></P><DL><DT><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A name="label8">Copying input file to output file</A><SPAN class="chunkborder">>=</SPAN></SPAN></DT><DD class="code"><CODE><SPAN class="keyword">local</SPAN> <BR> <SPAN class="keyword">proc</SPAN><SPAN class="variablename"> </SPAN>{<SPAN class="functionname">Copy</SPAN>}<BR> S={I read(list:$)}<BR> <SPAN class="keyword">in</SPAN> <BR> <SPAN class="keyword">if</SPAN> S<SPAN class="keyword">\=</SPAN><SPAN class="string">""</SPAN> <SPAN class="keyword">then</SPAN> <BR> {O write(vs:S)} {Copy} <BR> <SPAN class="keyword">end</SPAN> <BR> <SPAN class="keyword">end</SPAN> <BR><SPAN class="keyword">in</SPAN> <BR> {Copy}<BR><SPAN class="keyword">end</SPAN></CODE></DD></DL><P> </P><DIV class="apropos"><P class="margin">Terminating the application</P><P> Termination of the application is effected by invocation of <CODE>Application<SPAN class="keyword">.</SPAN>exit</CODE> which takes the application status as single integer argument. In our case an exit value of <CODE>1</CODE> indicates an error, otherwise <CODE>0</CODE> is returned to the operating system shell.</P></DIV><P></P><DL><DT><SPAN class="chunktitle"><SPAN class="chunkborder"><</SPAN><A name="label9">Terminating the application</A><SPAN class="chunkborder">>=</SPAN></SPAN></DT><DD class="code"><CODE>{Application<SPAN class="keyword">.</SPAN>exit Status}</CODE></DD></DL><P> </P><P> </P></DIV><DIV id="section.hello.compile"><H2><A name="section.hello.compile">1.4 Compilation</A></H2><P> As is the case for many programming languages, the functor definition must be compiled before it can be executed. This is achieved by invoking the Oz compiler <CODE>ozc</CODE> as follows: </P><BLOCKQUOTE class="code"><CODE>ozc -c Webget.oz -o Webget.oza</CODE></BLOCKQUOTE><P> </P><P> Note the intentional similarity between the options illustrated above and those accepted by a C compiler. The compiler <CODE>ozc</CODE> offers a variety of other options that control compilation, an overview of which can be found in <A href="../tools/node2.html#chapter.compiler">Chapter 2 of ``Oz Shell Utilities''</A>. </P></DIV><DIV id="section.hello.exec"><H2><A name="section.hello.exec">1.5 Execution</A></H2><P> The functor pickled into <CODE>Webget.oza</CODE> can be executed by applying the program <CODE>ozengine</CODE> to the functor and the application arguments. For example, to copy the Mozart license file at url <CODE>http://www.mozart-oz.org/LICENSE</CODE> to the local file <CODE>LICENSE</CODE>, simply enter the command line shown in <A href="node2.html#figure.hello.invoke">Figure 1.1</A> at your shell promt. </P><P> Execution of an application proceeds as follows: </P><OL type="1"><LI><P><CODE>ozengine</CODE>, the Oz virtual machine, is started by the operating system. </P></LI><LI><P><CODE>ozengine</CODE> starts to execute a <EM>module manager</EM>. </P></LI><LI><P>The module manager loads the pickled functor <CODE>Webget.oza</CODE>. This initial application functor is called the <EM>root functor</EM>. </P></LI><LI><P>The module manager <EM>links</EM> the functor by applying the functor body to <EM>argument modules</EM>. The argument modules in our example are the system modules <CODE>Application</CODE> and <CODE>Open</CODE>. </P></LI><LI><P>Then it executes the functor body. </P></LI></OL><P> </P><P> The different steps in application are detailed in the following sections. </P></DIV></DIV><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node1.html">- Up -</A></TD><TD><A href="node3.html#chapter.development">Next >></A></TD></TR></TABLE><HR><ADDRESS><A href="http://www.ps.uni-sb.de/~duchier/">Denys Duchier</A>, <A href="http://www.ps.uni-sb.de/~kornstae/">Leif Kornstaedt</A> and <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>
|