root/trunk/Modelica/Utilities/Streams.mo

Revision 1041, 9.2 kB (checked in by otter, 10 months ago)

Added 'annotation(Library="ModelicaExternalC")' to all 'external "C"' functions, as decided at the last design meeting.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1within Modelica.Utilities;
2package Streams "Read from files and write to files"
3  extends Modelica.Icons.Library;
4
5  annotation (
6    Documentation(info="<HTML>
7<h4>Library content</h4>
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 valign=\"top\"><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 valign=\"top\"> Print string \"string\" or vector of strings to message window or on
30           file \"fileName\".</td>
31  </tr>
32  <tr><td valign=\"top\">stringVector =
33         <a href=\"Modelica://Modelica.Utilities.Streams.readFile\">readFile</a>(fileName)</td>
34      <td valign=\"top\"> Read complete text file and return it as a vector of strings.</td>
35  </tr>
36  <tr><td valign=\"top\">(string, endOfFile) =
37         <a href=\"Modelica://Modelica.Utilities.Streams.readLine\">readLine</a>(fileName, lineNumber)</td>
38      <td valign=\"top\">Returns from the file the content of line lineNumber.</td>
39  </tr>
40  <tr><td valign=\"top\">lines =
41         <a href=\"Modelica://Modelica.Utilities.Streams.countLines\">countLines</a>(fileName)</td>
42      <td valign=\"top\">Returns the number of lines in a file.</td>
43  </tr>
44  <tr><td valign=\"top\"><a href=\"Modelica://Modelica.Utilities.Streams.error\">error</a>(string)</td>
45      <td valign=\"top\"> Print error message \"string\" to message window
46           and cancel all actions</td>
47  </tr>
48  <tr><td valign=\"top\"><a href=\"Modelica://Modelica.Utilities.Streams.close\">close</a>(fileName)</td>
49      <td valign=\"top\"> 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                 annotation(Dialog(__Dymola_saveSelector(filter="Text files (*.txt)",
79                        caption="Text file to store the output of print(..)")));
80  external "C" ModelicaInternal_print(string, fileName);
81    annotation (Library="ModelicaExternalC",
82  Documentation(info="<HTML>
83<h4>Syntax</h4>
84<blockquote><pre>
85Streams.<b>print</b>(string);
86Streams.<b>print</b>(string,fileName);
87</pre></blockquote>
88<h4>Description</h4>
89<p>
90Function <b>print</b>(..) opens automatically the given file, if
91it is not yet open. If the file does not exist, it is created.
92If the file does exist, the given string is appended to the file.
93If this is not desired, call \"Files.remove(fileName)\" before calling print
94(\"remove(..)\" is silent, if the file does not exist).
95The Modelica environment may close the file whenever appropriate.
96This can be enforced by calling <b>Streams.close</b>(fileName).
97After every call of \"print(..)\" a \"new line\" is printed automatically.
98</p>
99<h4>Example</h4>
100<blockquote><pre>
101  Streams.print(\"x = \" + String(x));
102  Streams.print(\"y = \" + String(y));
103  Streams.print(\"x = \" + String(y), \"mytestfile.txt\");
104</pre></blockquote>
105<p>
106<h4>See also</h4>
107<p>
108<a href=\"Modelica://Modelica.Utilities.Streams\">Streams</a>,
109<a href=\"Modelica://Modelica.Utilities.Streams.error\">Streams.error</a>,
110<a href=\"Modelica://ModelicaReference.Operators.string\">String</a>
111</p>
112</HTML>"));
113  end print;
114
115  function readFile
116    "Read content of a file and return it in a vector of strings"
117    extends Modelica.Icons.Function;
118    input String fileName "Name of the file that shall be read" 
119                 annotation(Dialog(__Dymola_loadSelector(filter="Text files (*.txt)",
120                        caption="Open text file for reading")));
121    output String stringVector[countLines(fileName)] "Content of file";
122
123    annotation ( Documentation(info="<html>
124<h4>Syntax</h4>
125<blockquote><pre>
126stringVector = Streams.<b>readFile</b>(fileName)
127</pre></blockquote>
128<h4>Description</h4>
129<p>
130Function <b>readFile</b>(..) opens the given file, reads the complete
131content, 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.
132</p>
133</html>"));
134
135  algorithm
136    for i in 1:size(stringVector, 1) loop
137      stringVector[i] := readLine(fileName, i);
138    end for;
139    Streams.close(fileName);
140  end readFile;
141
142  function readLine
143    "Reads a line of text from a file and returns it in a string"
144    extends Modelica.Icons.Function;
145    input String fileName "Name of the file that shall be read" 
146                        annotation(Dialog(__Dymola_loadSelector(filter="Text files (*.txt)",
147                        caption="Open text file for reading")));
148    input Integer lineNumber(min=1) "Number of line to read";
149    output String string "Line of text";
150    output Boolean endOfFile
151      "If true, end-of-file was reached when trying to read line";
152   external "C" string=  ModelicaInternal_readLine(fileName,lineNumber,endOfFile);
153    annotation (Library="ModelicaExternalC",Documentation(info="<html>
154<h4>Syntax</h4>
155<blockquote><pre>
156(string, endOfFile) = Streams.<b>readLine</b>(fileName, lineNumber)
157</pre></blockquote>
158<h4>Description</h4>
159<p>
160Function <b>readLine</b>(..) opens the given file, reads enough of the
161content to get the requested line, and returns the line as a string.
162Lines are separated by LF or CR-LF; the returned string does not
163contain the line separator. The file might remain open after
164the call.
165</p>
166<p>
167If lineNumber > countLines(fileName), an empty string is returned
168and endOfFile=true. Otherwise endOfFile=false.
169</p>
170</html>"));
171  end readLine;
172
173  function countLines "Returns the number of lines in a file"
174    extends Modelica.Icons.Function;
175    input String fileName "Name of the file that shall be read" 
176                       annotation(Dialog(__Dymola_loadSelector(filter="Text files (*.txt)",
177                        caption="Open text file for coutning lines")));
178
179    output Integer numberOfLines "Number of lines in file";
180  external "C" numberOfLines=  ModelicaInternal_countLines(fileName);
181    annotation (Library="ModelicaExternalC",Documentation(info="<html>
182<h4>Syntax</h4>
183<blockquote><pre>
184numberOfLines = Streams.<b>countLines</b>(fileName)
185</pre></blockquote>
186<h4>Description</h4>
187<p>
188Function <b>countLines</b>(..) opens the given file, reads the complete
189content, closes the file and returns the number of lines. Lines are
190separated by LF or CR-LF.
191</p>
192</html>"));
193  end countLines;
194
195  function error "Print error message and cancel all actions"
196    extends Modelica.Icons.Function;
197    input String string "String to be printed to error message window";
198    external "C" ModelicaError(string);
199    annotation (Library="ModelicaExternalC",
200  Documentation(info="<html>
201<h4>Syntax</h4>
202<blockquote><pre>
203Streams.<b>error</b>(string);
204</pre></blockquote>
205<h4>Description</h4>
206<p>
207Print the string \"string\" as error message and
208cancel all actions. Line breaks are characterized
209by \"\\n\" in the string.
210</p>
211<h4>Example</h4>
212<blockquote><pre>
213  Streams.error(\"x (= \" + String(x) + \")\\nhas to be in the range 0 .. 1\");
214</pre></blockquote>
215<h4>See also</h4>
216<p>
217<a href=\"Modelica://Modelica.Utilities.Streams\">Streams</a>,
218<a href=\"Modelica://Modelica.Utilities.Streams.print\">Streams.print</a>,
219<a href=\"Modelica://ModelicaReference.Operators.string\">String</a>
220</p>
221</html>"));
222  end error;
223
224  function close "Close file"
225    extends Modelica.Icons.Function;
226    input String fileName "Name of the file that shall be closed" 
227                 annotation(Dialog(__Dymola_loadSelector(filter="Text files (*.txt)",
228                        caption="Close text file")));
229    external "C" ModelicaStreams_closeFile(fileName);
230    annotation (Library="ModelicaExternalC",Documentation(info="<html>
231<h4>Syntax</h4>
232<blockquote><pre>
233Streams.<b>close</b>(fileName)
234</pre></blockquote>
235<h4>Description</h4>
236<p>
237Close file if it is open. Ignore call if
238file is already closed or does not exist.
239</p>
240</html>"));
241  end close;
242end Streams;
Note: See TracBrowser for help on using the browser.