root/branches/maintenance/2.2.2/Modelica/Utilities/package.mo

Revision 597, 11.9 kB (checked in by otter, 15 months ago)

Changed inconsistent writing of "user's guide" at all places to
"User's Guide" (reported by Dietmar Winkler)
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1within Modelica;
2package Utilities "Library of utility functions dedicated to scripting (operating on files, streams, strings, system)"
3  extends Modelica.Icons.Library;
4
5
6    annotation (
7  version="1.0",
8  versionDate="2004-10-01",
9  preferedView="info",
10Documentation(info="<html>
11<p>
12This package contains Modelica <b>functions</b> that are
13especially suited for <b>scripting</b>. The functions might
14be used to work with strings, read data from file, write data
15to file or copy, move and remove files.
16</p>
17<p>
18For an introduction, have especially a look at:
19</p>
20<ul>
21<li> <a href=\"Modelica://Modelica.Utilities.UsersGuide\">Modelica.Utilities.User's Guide</a>
22     discusses the most important aspects of this library.</li>
23<li> <a href=\"Modelica://Modelica.Utilities.Examples\">Modelica.Utilities.Examples</a>
24     contains examples that demonstrate the usage of this library.</li>
25</ul>
26<p>
27The following main sublibraries are available:
28</p>
29<ul>
30<li> <a href=\"Modelica://Modelica.Utilities.Files\">Files</a>
31     provides functions to operate on files and directories, e.g.,
32     to copy, move, remove files.</li>
33<li> <a href=\"Modelica://Modelica.Utilities.Streams\">Streams</a>
34     provides functions to read from files and write to files.</li>
35<li> <a href=\"Modelica://Modelica.Utilities.Strings\">Strings</a>
36     provides functions to operate on strings. E.g.
37     substring, find, replace, sort, scanToken.</li>
38<li> <a href=\"Modelica://Modelica.Utilities.System\">System</a>
39     provides functions to interact with the environment.
40     E.g., get or set the working directory or environment
41     variables and to send a command to the default shell.</li>
42</ul>
43
44<p>
45Copyright &copy; 1998-2007, Modelica Association, DLR and Dynasim.
46</p>
47<p>
48<i>This Modelica package is <b>free</b> software; it can be redistributed and/or modified
49under the terms of the <b>Modelica license</b>, see the license conditions
50and the accompanying <b>disclaimer</b> 
51<a href=\"Modelica://Modelica.UsersGuide.ModelicaLicense\">here</a>.</i>
52</p><br>
53</html>
54"));
55
56
57package UsersGuide "User's Guide of Utilities Library" 
58 
59  annotation (DocumentationClass=true, Documentation(info="<HTML>
60<p>
61Library <b>Modelica.Utilities</b> contains Modelica <b>functions</b> that are
62especially suited for <b>scripting</b>. Currently, only a rudimentary
63User's Guide is present. This will be improved in the next releases.
64The User's Guide has currently the following chapters:
65</p>
66<ol>
67<li>
68<a href=\"Modelica://Modelica.Utilities.UsersGuide.ReleaseNotes\">Release Notes</a>
69  summarizes the differences between different versions of this
70  library.
71</li>
72<li>
73<a href=\"Modelica://Modelica.Utilities.UsersGuide.ImplementationNotes\">ImplementationNotes</a>
74  describes design decisions for this library especially for
75  Modelica tool vendors.
76</li>
77<li>
78<a href=\"Modelica://Modelica.Utilities.UsersGuide.Contact\">Contact</a> provides
79  information about the authors of the library as well as acknowledgments.
80</li>
81</ol>
82<p>
83<b>Error handling</b><br>
84In case of error, all functions in this library use a Modelica \"assert(..)\"
85to provide an error message and to cancel all actions. This means that
86functions do not return, if an error is triggered inside the function.
87In the near future, an exception handling mechanism will be introduced
88in Modelica that will allow to catch errors at a defined place.
89</p>
90</HTML>"));
91 
92  class ImplementationNotes "Implementation Notes" 
93   
94    annotation (Documentation(info="<html>
95<p>
96Below the major design decisions of this library are summarized.
97<p>
98<ul>
99<li> <b>C-Function Interface</b><br>
100     This library contains several interfaces to C-functions in order
101     to operate with the environment. As will become clear, it is usally
102     required that a Modelica tool vendor provides an implementation
103     of these C-functions that are suited for his environment.
104     In directory \"Modelica.Utilities\\C-Sources\" a reference implementation
105     is given for Microsoft Windows Systems and for POSIX environments.
106     The files \"ModelicaInternal.c\" and \"ModelicaStrings.c\" can be
107     used as a basis for the integration in the vendors environment.<br>&nbsp;</li>
108<li> <b>Character Encoding</b><br>
109     The representation of characters is different in operating systems.
110     The more modern ones (e.g. Windows-NT) use an early variant of
111     Unicode (16 bit per character)
112     other (e.g. Windows-ME) use 8-bit encoding. Also 32 bit per character
113     and multi-byte representations are in use. This is important, since e.g.,
114     Japanese Modelica users need Unicode representation. The design in this
115     library is done in such a way that a basic set of calls to the operating
116     system hides the actual character representation. This means, that all
117     functions of this package can be used independent from the underlying
118     character representation.<br>
119     The C-interface of the Modelica language provides only an 8-bit
120     character encoding passing mechanism of strings. As a result, the
121     reference implementation in \"Modelica.Utilities\\C-Source\" needs to
122     be adapted to the character representation supported in the
123     Modelica vendor environment.<br>&nbsp;</li>
124<li> <b>Internal String Representation</b><br>
125     The design of this package was made in order that string handling
126     is convenient. This is in contrast to, e.g., the C-language, where
127     string handling is inconvenient, cumbersome and error prone, but on the
128     other hand is in some sense \"efficient\".
129     The standard reference implementation in \"Modelica.Utilities\\C-Source\"
130     is based on the standard C definition of a string, i.e., a pointer to
131     a sequence of characters, ended with a null terminating character.
132     In order that the string handling in this package is convenient,
133     some assumptions have been made, especially, that the access to
134     a substring is efficient (O(1) access instead of O(n) as in standard C).
135     This allows to hide string pointer arithmetic from the user.
136     In such a case, a similiar efficiency as in C can be expected for
137     most high level operations, such as find, sort, replace.
138     The \"efficient character access\" can be reached if, e.g.,
139     the number of characters
140     are stored in a string, and the length of a character is fixed,
141     say 16 or 32 bit (if all Unicode characters shall be represented).
142     A vendor should adapt the reference implementation in this
143     respect.<br>&nbsp;</li>
144<li> <b>String copy = pointer copy</b><br>
145     The Modelica language has no mechanism to change a character
146     of a string. When a string has to be modified, the only way
147     to achieve this is to generate it newly. The advantage is that
148     a Modelica tool can treat a string as a constant entity and
149     can replace (expensive) string copy operations by pointer
150     copy operations. For example, when sorting a set of strings
151     the following type of operations occur:
152     <pre>
153     String s[:], s_temp;
154      ...
155     s_temp := s[i];
156     s[i]   := s[j];
157     s[j]   := s_temp;
158     </pre>
159     Formally, three strings are copied. Due to the feature
160     sketched above, a Modelica tool can replace this
161     copy operation by pointer assignments, a very \"cheap\"
162     operation. The Modelica.Utilities functions will perform
163     efficiently, if such types of optimizations are supported
164     by the tool.</li>
165</ul>
166</html>
167"));
168  end ImplementationNotes;
169 
170  class ReleaseNotes "Release notes" 
171   
172    annotation (Documentation(info="<HTML>
173<h4>Version 1.0, 2004-09-29</h4>
174<p>
175First version implemented.
176</p>
177</HTML>
178"));
179  equation 
180   
181  end ReleaseNotes;
182 
183  class Contact "Contact" 
184   
185    annotation (Documentation(info="<html>
186<dl>
187<dt><b>Responsible for Library:</b>
188<dd>Dag Br&uuml;ck, Dynasim AB, Sweden.<br>
189    email: <A HREF=\"mailto:Dag@Dynasim.se\">Dag@Dynasim.se</A><br>
190</dl>
191<p><b>Acknowledgements:</b></p>
192<ul>
193<li> This library has been designed by:<br> 
194     <blockquote>
195     Dag Br&uuml;ck, Dynasim AB, Sweden <br>
196     Hilding Elmqvist, Dynasim AB, Sweden <br>
197     Hans Olsson, Dynasim AB, Sweden <br>
198     Martin Otter, DLR Oberpfaffenhofen, Germany.
199     </blockquote></li>
200<li> The library including the C reference implementation has
201     been implemented by Martin Otter and Dag Br&uuml;ck.</li>
202<li> The Examples.calculator demonstration to implement a calculator
203     with this library is from Hilding Elmqvist.</li>
204<li> Helpful comments from Kaj Nystr&ouml;m, PELAB, Link&ouml;ping, Sweden,
205     are appreciated, as well as discussions at the 34th, 36th, and 40th
206     Modelica Design Meetings in Vienna, Link&ouml;ping, and Dresden. </li>
207</ul>
208</html>
209"));
210  end Contact;
211 
212end UsersGuide;
213
214
215package Internal "Internal package as interface to the operating system" 
216 extends Modelica.Icons.Library;
217  annotation (  preferedView="info",
218Documentation(info="<html>
219<p>
220Package <b>Internal</b> is an internal package that contains
221low level functions as interface to the operating system.
222These functions should not be called directly in a scripting
223environment since more convenient functions are provided
224in packages Files and Systems.
225</p>
226<p>
227Note, the functions in this package are direct interfaces to
228functions of POSIX and of the standard C library. Errors
229occuring in these functions are treated by triggering
230a Modelica assert. Therefore, the functions in this package
231return only for a successful operation. Furthermore, the
232representation of a string is hidden by this interface,
233especially if the operating system supports Unicode characters.
234</p>
235</html>"));
236 
237  function mkdir "Make directory (POSIX: 'mkdir')" 
238    extends Modelica.Icons.Function;
239    input String directoryName "Make a new directory";
240  external "C" ModelicaInternal_mkdir(directoryName);
241  end mkdir;
242 
243  function rmdir "Remove empty directory (POSIX function 'rmdir')" 
244    extends Modelica.Icons.Function;
245    input String directoryName "Empty directory to be removed";
246  external "C" ModelicaInternal_rmdir(directoryName);
247  end rmdir;
248 
249  function stat "Inquire file information (POSIX function 'stat')" 
250    extends Modelica.Icons.Function;
251    input String name "Name of file, directory, pipe etc.";
252    output Types.FileType.Type fileType "Type of file";
253  external "C" fileType=  ModelicaInternal_stat(name);
254  end stat;
255 
256  function rename "Rename existing file or directory (C function 'rename')" 
257    extends Modelica.Icons.Function;
258    input String oldName "Current name";
259    input String newName "New name";
260  external "C" ModelicaInternal_rename(oldName, newName);
261  end rename;
262 
263  function removeFile "Remove existing file (C function 'remove')" 
264    extends Modelica.Icons.Function;
265    input String fileName "File to be removed";
266  external "C" ModelicaInternal_removeFile(fileName);
267  end removeFile;
268 
269  function copyFile
270    "Copy existing file (C functions 'fopen', 'getc', 'putc', 'fclose')" 
271    extends Modelica.Icons.Function;
272    input String fromName "Name of file to be copied";
273    input String toName "Name of copy of file";
274  external "C" ModelicaInternal_copyFile(fromName, toName);
275  end copyFile;
276 
277  function readDirectory
278    "Read names of a directory (POSIX functions opendir, readdir, closedir)" 
279    extends Modelica.Icons.Function;
280    input String directory
281      "Name of the directory from which information is desired";
282    input Integer nNames
283      "Number of names that are returned (inquire with getNumberOfFiles)";
284    output String names[nNames] 
285      "All file and directory names in any order from the desired directory";
286    external "C" ModelicaInternal_readDirectory(directory,nNames,names);
287  end readDirectory;
288 
289function getNumberOfFiles
290    "Get number of files and directories in a directory (POSIX functions opendir, readdir, closedir)" 
291  extends Modelica.Icons.Function;
292  input String directory "Directory name";
293  output Integer result
294      "Number of files and directories present in 'directory'";
295  external "C" result = ModelicaInternal_getNumberOfFiles(directory);
296end getNumberOfFiles;
297 
298end Internal;
299end Utilities;
Note: See TracBrowser for help on using the browser.