Modelica.Utilities.Files

Information

This package contains functions to work with files and directories. As a general convention of this package, '/' is used as directory separator both for input and output arguments of all functions. For example:

   exist("Modelica/Mechanics/Rotational.mo");

The functions provide the mapping to the directory separator of the underlying operating system. Note, that on Windows system the usage of '\' as directory separator would be inconvenient, because this character is also the escape character in Modelica and C Strings.

In the table below an example call to every function is given:

Package Content

Name	Description
list	List content of file or directory
copy	Generate a copy of a file or of a directory
move	Move a file or a directory to another place
remove	Remove file or directory (ignore call, if it does not exist)
removeFile	Remove file (ignore call, if it does not exist)
createDirectory	Create directory (if directory already exists, ignore call)
exist	Inquire whether file or directory exists
assertNew	Trigger an assert, if a file or directory exists
fullPathName	Get full path name of file or directory name
splitPathName	Split path name in directory, file name kernel, file name extension
temporaryFileName	Return arbitrary name of a file that does not exist and is in a directory where access rights allow to write to this file (useful for temporary output of files)
loadResource	Return the absolute path name of a URI or local file name

Modelica.Utilities.Files.list

Information

Syntax

Files.list(name);

Description

If "name" is a regular file, the content of the file is printed.

If "name" is a directory, the directory and file names in the "name" directory are printed in sorted order.

Inputs

Name	Description
name	If name is a directory, list directory content. If it is a file, list the file content

Modelica.Utilities.Files.copy

Information

Syntax

Files.copy(oldName, newName);
Files.copy(oldName, newName, replace = true);

Description

Function copy(..) copies a file or a directory to a new location. Via the optional argument replace it can be defined whether an already existing file may be replaced by the required copy.

If oldName/newName are directories, then the newName directory may exist. In such a case the content of oldName is copied into directory newName. If replace = false it is required that the existing files in newName are different from the existing files in oldName.

Example

  copy("C:/test1/directory1", "C:/test2/directory2");
     -> the content of directory1 is copied into directory2
        if "C:/test2/directory2" does not exist, it is newly
        created. If "replace=true", files in directory2
        may be overwritten by their copy
  copy("test1.txt", "test2.txt")
     -> make a copy of file "test1.txt" with the name "test2.txt"
        in the current directory

Inputs

Name	Description
oldName	Name of file or directory to be copied
newName	Name of copy of the file or of the directory
replace	= true, if an existing file may be replaced by the required copy

Modelica.Utilities.Files.move

Information

Syntax

Files.move(oldName, newName);
Files.move(oldName, newName, replace = true);

Description

Function move(..) moves a file or a directory to a new location. Via the optional argument replace it can be defined whether an already existing file may be replaced.

If oldName/newName are directories, then the newName directory may exist. In such a case the content of oldName is moved into directory newName. If replace = false it is required that the existing files in newName are different from the existing files in oldName.

Example

  move("C:/test1/directory1", "C:/test2/directory2");
     -> the content of directory1 is moved into directory2.
        Afterwards directory1 is deleted.
        if "C:/test2/directory2" does not exist, it is newly
        created. If "replace=true", files in directory2
        may be overwritten
   move("test1.txt", "test2.txt")
     -> rename file "test1.txt" into "test2.txt"
        within the current directory

Inputs

Name	Description
oldName	Name of file or directory to be moved
newName	New name of the moved file or directory
replace	= true, if an existing file or directory may be replaced

Modelica.Utilities.Files.remove

Information

Syntax

Files.remove(name);

Description

Removes the file or directory "name". If "name" does not exist, the function call is ignored. If "name" is a directory, first the content of the directory is removed and afterwards the directory itself.

This function is silent, i.e., it does not print a message.

Inputs

Name	Description
name	Name of file or directory to be removed

Modelica.Utilities.Files.removeFile

Information

Syntax

Files.removeFile(fileName);

Description

Removes the file "fileName". If "fileName" does not exist, the function call is ignored. If "fileName" exists but is no regular file (e.g., directory, pipe, device, etc.) an error is triggered.

This function is silent, i.e., it does not print a message.

Inputs

Name	Description
fileName	Name of file that should be removed

Modelica.Utilities.Files.createDirectory

Information

Syntax

Files.createDirectory(directoryName);

Description

Creates directory "directoryName". If this directory already exists, the function call is ignored. If several directories in "directoryName" do not exist, all of them are created. For example, assume that directory "E:/test1" exists and that directory "E:/test1/test2/test3" shall be created. In this case the directories "test2" in "test1" and "test3" in "test2" are created.

This function is silent, i.e., it does not print a message. In case of error (e.g., "directoryName" is an existing regular file), an assert is triggered.

Inputs

Name	Description
directoryName	Name of directory to be created (if present, ignore call)

Modelica.Utilities.Files.exist

Information

Syntax

result = Files.exist(name);

Description

Returns true, if "name" is an existing file or directory. If this is not the case, the function returns false.

Inputs

Name	Description
name	Name of file or directory

Outputs

Name	Description
result	= true, if file or directory exists

Modelica.Utilities.Files.assertNew

Information

Syntax

Files.assertNew(name);
Files.assertNew(name, message="This is not allowed");

Description

Triggers an assert, if "name" is an existing file or directory. The error message has the following structure:

  File "<name>" already exists.
  <message>

Inputs

Name	Description
name	Name of file or directory
message	Message that should be printed after the default message in a new line

Modelica.Utilities.Files.fullPathName

Information

Syntax

fullName = Files.fullPathName(name);

Description

Returns the full path name of a file or directory "name".

Inputs

Name	Description
name	Absolute or relative file or directory name

Outputs

Name	Description
fullName	Full path of 'name'

Modelica.Utilities.Files.splitPathName

Information

Syntax

(directory, name, extension) = Files.splitPathName(pathName);

Description

Function splitPathName(..) splits a path name into its parts.

Example

  (directory, name, extension) = Files.splitPathName("C:/user/test/input.txt")

  -> directory = "C:/user/test/"
     name      = "input"
     extension = ".txt"

Inputs

Name	Description
pathName	Absolute or relative file or directory name

Outputs

Name	Description
directory	Name of the directory including a trailing '/'
name	Name of the file without the extension
extension	Extension of the file name. Starts with '.'

Modelica.Utilities.Files.temporaryFileName

Information

Syntax

fileName = Files.temporaryFileName();

Description

Return arbitrary name of a file that does not exist and is in a directory where access rights allow to write to this file (useful for temporary output of files).

Outputs

Name	Description
fileName	Full path name of temporary file

Modelica.Utilities.Files.loadResource

Information

Syntax

fileReference = FileSystem.loadResource(uri);

Description

The function call "FileSystem.loadResource(uri)" returns the absolute path name of the file that is either defined by an URI or by a local (e.g. relative) path name. With the returned file name it is possible to access the file with function calls of the C standard library. If the data or file is stored in a data-base, this might require copying the resource to a temporary folder and referencing that.

The implementation of this function is tool specific. However, at least Modelica URIs (see "chapter 13.2.3 External Resources" of the Modelica Specification), as well as absolute and relative local file path names are supported.

Example

  file1 = loadResource("modelica://Modelica/Resources/Data/Utilities/Examples_readRealParameters.txt")
          // file1 is the absolute path name of the file
  file2 = loadResource("C:\\data\\readParameters.txt")
          file2 = "C:/data/readParameters.txt"

Inputs

Name	Description
uri	URI or local file name

Outputs

Name	Description
fileReference	Absolute path name of file