root/branches/maintenance/2.2.1/Modelica/Utilities/Streams.mo

Revision 463, 9.0 kB (checked in by hubertus, 22 months ago)

Created maintenance version from Dynasims version with minimal changes (no checksum, 1 graphics, a few improved documentation places, structurallyIncomplete annotations in Visualizers)
Line 
1package Streams "Read from files and write to files" 
2  extends Modelica.Icons.Library;
3 
4  annotation (
5  preferedView="info",
6    Documentation(info="<HTML>
7<h3><font color=\"#008000\">Library content</font></h3>
8<p>
9Package <b>Streams</b> contains functions to input and output strings
10to a message window or on files. Note that a string is interpreted
11and displayed as html text (e.g., with print(..) or error(..))
12if it is enclosed with the Modelica html quotation, e.g.,
13</p>
14<center>
15string = \"&lt;html&gt; first line &lt;br&gt; second line &lt;/html&gt;\".
16</center>
17<p>
18It is a quality of implementation, whether (a) all tags of html are supported
19or only a subset, (b) how html tags are interpreted if the output device
20does not allow to display formatted text.
21</p>
22<p>
23In the table below an example call to every function is given:
24</p>
25<table border=1 cellspacing=0 cellpadding=2>
26  <tr><th><b><i>Function/type</i></b></th><th><b><i>Description</i></b></th></tr>
27  <tr><td><a href=\"Modelica:Modelica.Utilities.Streams.print\">print</a>(string)<br>
28          <a href=\"Modelica:Modelica.Utilities.Streams.print\">print</a>(string,fileName)</td>
29      <td> Print string \"string\" or vector of strings to message window or on
30           file \"fileName\".</td>
31  </tr>
32  <tr><td>stringVector =
33         <a href=\"Modelica:Modelica.Utilities.Streams.readFile\">readFile</a>(fileName)</td>
34      <td> Read complete text file and return it as a vector of strings.</td>
35  </tr>
36  <tr><td>(string, endOfFile) =
37         <a href=\"Modelica:Modelica.Utilities.Streams.readLine\">readLine</a>(fileName, lineNumber)</td>
38      <td>Returns from the file the content of line lineNumber.</td>
39  </tr>
40  <tr><td>lines =
41         <a href=\"Modelica:Modelica.Utilities.Streams.countLines\">countLines</a>(fileName)</td>
42      <td>Returns the number of lines in a file.</td>
43  </tr>
44  <tr><td><a href=\"Modelica:Modelica.Utilities.Streams.error\">error</a>(string)</td>
45      <td> Print error message \"string\" to message window
46           and cancel all actions</td>
47  </tr>
48  <tr><td><a href=\"Modelica:Modelica.Utilities.Streams.close\">close</a>(fileName)</td>
49      <td> Close file if it is still open. Ignore call if
50           file is already closed or does not exist. </td>
51  </tr>
52</table>
53<p>
54Use functions <b>scanXXX</b> from package
55<a href=\"Modelica:Modelica.Utilities.Strings\">Strings</a>
56to parse a string.
57</p>
58<p>
59If Real, Integer or Boolean values shall be printed
60or used in an error message, they have to be first converted
61to strings with the builtin operator
62<a href=\"Modelica:ModelicaReference.Operators.string\">String</a>(...).
63Example:
64</p>
65<pre>
66  <b>if</b> x &lt; 0 <b>or</b> x &gt; 1 <b>then</b>
67     Streams.error(\"x (= \" + String(x) + \") has to be in the range 0 .. 1\");
68  <b>end if</b>;
69</pre>
70</HTML>
71"));
72 
73  function print "Print string to terminal or file" 
74    extends Modelica.Icons.Function;
75    input String string="" "String to be printed";
76    input String fileName="" 
77      "File where to print (empty string is the terminal)";
78  external "C" ModelicaInternal_print(string, fileName);
79    annotation (  preferedView="info",
80  Documentation(info="<HTML>
81<h3><font color=\"#008000\">Syntax</font></h3>
82<blockquote><pre>
83Streams.<b>print</b>(string);
84Streams.<b>print</b>(string,fileName);
85</pre></blockquote>
86<h3><font color=\"#008000\">Description</font></h3>
87<p>
88Function <b>print</b>(..) opens automatically the given file, if
89it is not yet open. If the file does not exist, it is created.
90If the file does exist, the given string is appended to the file.
91If this is not desired, call \"Files.remove(fileName)\" before calling print
92(\"remove(..)\" is silent, if the file does not exist).
93The Modelica environment may close the file whenever appropriate.
94This can be enforced by calling <b>Streams.close</b>(fileName).
95After every call of \"print(..)\" a \"new line\" is printed automatically.
96</p>
97<h3><font color=\"#008000\">Example</font></h3>
98<blockquote><pre>
99  Streams.print(\"x = \" + String(x));
100  Streams.print(\"y = \" + String(y));
101  Streams.print(\"x = \" + String(y), \"mytestfile.txt\");
102</pre></blockquote>
103<p>
104<h3><font color=\"#008000\">See also</font></h3>
105<p>
106<a href=\"Modelica:Modelica.Utilities.Streams\">Streams</a>,
107<a href=\"Modelica:Modelica.Utilities.Streams.error\">Streams.error</a>,
108<a href=\"Modelica:ModelicaReference.Operators.string\">String</a>
109</p>
110</HTML>"));
111  end print;
112 
113  function readFile
114    "Read content of a file and return it in a vector of strings" 
115    extends Modelica.Icons.Function;
116    input String fileName "Name of the file that shall be read";
117    output String stringVector[countLines(fileName)] "Content of file";
118   
119    annotation (preferedView="info", Documentation(info="<html>
120<h3><font color=\"#008000\">Syntax</font></h3>
121<blockquote><pre>
122stringVector = Streams.<b>readFile</b>(fileName)
123</pre></blockquote>
124<h3><font color=\"#008000\">Description</font></h3>
125<p>
126Function <b>readFile</b>(..) opens the given file, reads the complete
127content, closes the file and returns the content as a vector of strings. Lines are separated by LF or CR-LF; the returned strings do not contain the line separators.
128</p>
129</html>"));
130   
131  algorithm 
132    for i in 1:size(stringVector, 1) loop
133      stringVector[i] := readLine(fileName, i);
134    end for;
135    Streams.close(fileName);
136  end readFile;
137 
138  function readLine
139    "Reads a line of text from a file and returns it in a string" 
140    extends Modelica.Icons.Function;
141    input String fileName "Name of the file that shall be read";
142    input Integer lineNumber(min=1) "Number of line to read";
143    output String string "Line of text";
144    output Boolean endOfFile
145      "If true, end-of-file was reached when trying to read line";
146   external "C" string=  ModelicaInternal_readLine(fileName,lineNumber,endOfFile);
147    annotation (preferedView="info",Documentation(info="<html>
148<h3><font color=\"#008000\">Syntax</font></h3>
149<blockquote><pre>
150(string, endOfFile) = Streams.<b>readLine</b>(fileName, lineNumber)
151</pre></blockquote>
152<h3><font color=\"#008000\">Description</font></h3>
153<p>
154Function <b>readLine</b>(..) opens the given file, reads enough of the
155content to get the requested line, and returns the line as a string.
156Lines are separated by LF or CR-LF; the returned string does not
157contain the line separator. The file might remain open after
158the call.
159</p>
160<p>
161If lineNumber > countLines(fileName), an empty string is returned
162and endOfFile=true. Otherwise endOfFile=false.
163</p>
164</html>"));
165  end readLine;
166 
167  function countLines "Returns the number of lines in a file" 
168    extends Modelica.Icons.Function;
169    input String fileName "Name of the file that shall be read";
170    output Integer numberOfLines "Number of lines in file";
171  external "C" numberOfLines=  ModelicaInternal_countLines(fileName);
172    annotation (preferedView="info",Documentation(info="<html>
173<h3><font color=\"#008000\">Syntax</font></h3>
174<blockquote><pre>
175numberOfLines = Streams.<b>countLines</b>(fileName)
176</pre></blockquote>
177<h3><font color=\"#008000\">Description</font></h3>
178<p>
179Function <b>countLines</b>(..) opens the given file, reads the complete
180content, closes the file and returns the number of lines. Lines are
181separated by LF or CR-LF.
182</p>
183</html>"));
184  end countLines;
185 
186  function error "Print error message and cancel all actions" 
187    extends Modelica.Icons.Function;
188    input String string "String to be printed to error message window";
189    external "C" ModelicaError(string);
190    annotation (  preferedView="info",
191  Documentation(info="<html>
192<h3><font color=\"#008000\">Syntax</font></h3>
193<blockquote><pre>
194Streams.<b>error</b>(string);
195</pre></blockquote>
196<h3><font color=\"#008000\">Description</font></h3>
197<p>
198Print the string \"string\" as error message and
199cancel all actions. Line breaks are characterized
200by \"\\n\" in the string.
201</p>
202<h3><font color=\"#008000\">Example</font></h3>
203<blockquote><pre>
204  Streams.error(\"x (= \" + String(x) + \")\\nhas to be in the range 0 .. 1\");
205</pre></blockquote>
206<h3><font color=\"#008000\">See also</font></h3>
207<p>
208<a href=\"Modelica:Modelica.Utilities.Streams\">Streams</a>,
209<a href=\"Modelica:Modelica.Utilities.Streams.print\">Streams.print</a>,
210<a href=\"Modelica:ModelicaReference.Operators.string\">String</a>
211</p>
212</html>"));
213  end error;
214 
215  function close "Close file" 
216    extends Modelica.Icons.Function;
217    input String fileName "Name of the file that shall be closed";
218    external "C" ModelicaStreams_closeFile(fileName);
219    annotation (preferedView="info",Documentation(info="<html>
220<h3><font color=\"#008000\">Syntax</font></h3>
221<blockquote><pre>
222Streams.<b>close</b>(fileName)
223</pre></blockquote>
224<h3><font color=\"#008000\">Description</font></h3>
225<p>
226Close file if it is open. Ignore call if
227file is already closed or does not exist.
228</p>
229</html>"));
230  end close;
231 
232end Streams;
Note: See TracBrowser for help on using the browser.