File Functions
[Functions]


Functions

string FileChooser (string Name, string Pattern)
 Create a dialog box to select a file.
list ReadData (string Filename, string Sep)
 This function reads a text data file.
image ReadImg (string sName)
 Read image from a file.
string ReadText (string sFilename, any_type sData)
 Read the contents of a text file and store it in a string variable.
string ReadVar (string sName, any_type vData)
 Read the contents of a data file and store the data in a variable.
string ReadXML (string sName, any_type lData)
 Read the contents of a XML file and store them in a nested list.
void SaveScreen (string Filename)
 Save the actual visualization screen as bmp image to disk.
void ShowFile (string Name)
 Open a file and show it with the appropriate viewer set by the operating system.
void WriteData (string Filename, list L, string Sep)
 This function writes a list of scalars to a file.
void WriteImg (string sName, image Img)
 Write image to a file.
string WriteText (string sFilename, string sData)
 Write the contents of a string variable to a file.
string WriteVar (string sName, any_type vData, counter iComp)
 Write the contents of a variable to a file in XML format.

Detailed Description

Functions that deal with files.

Function Documentation

string FileChooser string  Name,
string  Pattern
 

Create a dialog box to select a file.

Parameters:
Name (optional) The name of the tool (default="Select File").
Pattern (optional) A string specifying a search pattern (default="*.*").
Returns:
A string containing the name of the selected file.
Since:
v2.0
The call of this function first opens a dialog box. Depending on the value of the optional parameter Pattern the user is asked to select a file. The name of the file will then be returned.

list ReadData string  Filename,
string  Sep
 

This function reads a text data file.

Parameters:
Filename The filename of the data file to be read.
Sep The separation symbol between items. This is optional. The default separator symbol is a space.
Since:
v1.4
This function reads a text data file that contains data which is basically organized as a matrix. Each line in the text file is read in as a sublist contained in a list. The text symbol that separates elements within a line is by default a space but can be set to any other symbol. The data entries must be scalar values. The path to the data file is considered to be relative to the path where the currently executed script is located. Here is an example. Consider that the data file is called "Test.dat" and has the form

1.2 3.4 -6.2
4.3 1.2543 8.3 9.2

The code

?L = ReadData("Test.dat");

then produces the output

L = ((1.2, 3.4, -6.2), (4.3, 1.2543, 8.3, 9.2))

Similarly, if the file looks like this

1.2, 3.4, -6.2
4.3, 1.2543, 8.3, 9.2

then the following code

?L = ReadData("Test.dat", ",");

produces the same output

L = ((1.2, 3.4, -6.2), (4.3, 1.2543, 8.3, 9.2))

image ReadImg string  sName  ) 
 

Read image from a file.

Parameters:
sName A filename.
Returns:
An image variable containing the image read.
Since:
v2.2
Reads an image from a file with the name sName. Possible file formats are '.bmp', '.jpg', '.pcx', '.png', '.raw', '.sgi', '.tga', '.tif'.

string ReadText string  sFilename,
any_type  sData
 

Read the contents of a text file and store it in a string variable.

Parameters:
sFilename The filename.
sData The contents of the file.
Returns:
The string 'OK', when no error occured and an error message otherwise.
Since:
v2.3
This function reads the contents of a text file and stores them as a string in sData.

string ReadVar string  sName,
any_type  vData
 

Read the contents of a data file and store the data in a variable.

Parameters:
sName A filename.
vData A variable of any type in which the result of the read operation is stored.
Returns:
The string 'OK', when no error occured and an error message otherwise.
Since:
v2.2
This function reads the contents of a data file generated with WriteVar() and stores the results in the variable vData.

string ReadXML string  sName,
any_type  lData
 

Read the contents of a XML file and store them in a nested list.

Parameters:
sName A filename.
lData A variable of any type in which the result of the read operation is stored.
Returns:
The string 'OK', when no error occured and an error message otherwise.
Since:
v2.3
This function reads the contents of any XML file and stores the data in a nested list, which is returned in the variable lData. For example, consider the following XML data file:

    <?xml version="1.0" encoding="utf-8" ?> 
    <test version="1.0">
        Hello World!
    </test>

When this data file is read with ReadXML(), it generates the following nested list in CLUCalc:

    [ [ test , 
        [ [ 
            [ version , 1.0 ] , 
            [ _content ,  Hello World! ] , 
            [ _subtree , [  ] ] 
         ] ] 
    ] ]

The reserved tags '_content' and '_subtree' are used to reference the content and the subtree of an element. Elements with the same tag name are collected in lists as the following example shows. Consider the following XML data structure.

    <?xml version="1.0" encoding="utf-8" ?> 
    <test version="1.0">
        <name>a</name>
        <fun>Hello</fun>
        <name>b</name>
        <fun>World</fun>
    </test>

This is mapped to the following nested lists in CLUCalc.

    [ [ test , 
        [ [ 
            [ version , 1.0 ] , 
            [ _content ,  ] , 
            [ _subtree , 
                [   // List of subtree elements by name
                    [ fun , 
                        [   // List of elements with tag 'fun' 
                            [ 
                                [ _content , Hello ] , 
                                [ _subtree , [  ] ] 
                            ] , 
                            [ 
                                [ _content , World ] , 
                                [ _subtree , [  ] ] 
                            ]
                        ] 
                    ] , 
                    [ name , 
                        [   // List of elements with tag 'name' 
                            [ 
                                [ _content , a ] , 
                                [ _subtree , [  ] ] 
                            ] , 
                            [ 
                                [ _content , b ] , 
                                [ _subtree , [  ] ] 
                            ] 
                        ] 
                    ] 
                ] 
            ] 
        ] ] 
    ] ]

If this data structure is stored in the variable lData, then you can, for example, obtain a reference to the list of elements with tag 'name' with the following script.

    // Get name of root element
    sRootName = lData([1,1]);
    
    // Get reference to property list of root element
    lRootProp -> lData([1,2,1]);
    
    // Get content of 'version' property
    sVersion = lRootProp("version");
    
    // Get reference to subtree of root tree
    lRootTree -> lRootProp("_subtree");
    
    // Get reference to list of elements with tag 'name'
    lNameList -> lRootTree("name");

void SaveScreen string  Filename  ) 
 

Save the actual visualization screen as bmp image to disk.

Parameters:
Filename The name for the image.
Returns:
Nothing.
Since:
v2.0
The filename has to contain it's extension '.bmp', otherwise the file won't have an extension. An existing file with the same name will be overwritten. The following command saves the contents of the visualization window to the parent directory:
    
    SaveScreen( "..\screen.bmp" );

void ShowFile string  Name  ) 
 

Open a file and show it with the appropriate viewer set by the operating system.

Parameters:
Name A string specifying the name of the file to load.
Returns:
Nothing.
Since:
v2.0

void WriteData string  Filename,
list  L,
string  Sep
 

This function writes a list of scalars to a file.

Parameters:
Filename The filename of the data file to be written.
L A list of scalars to be written.
Sep The separation symbol between items. This is optional. The default separator symbol is a space.
Returns:
Nothing.
Since:
v2.0
This function writes scalar valued data which is basically organized as a matrix into a text data file. If the specified file already exists it will be overwritten. See also the description of the function ReadData.

The code

    ? L = [  [1.1, 2, 3, 4], [1, 2.0]  ];
    WriteData( "Test.dat", L );
    ? L = ReadData( "Test.dat" );

then produces the output

    L = [[1.1, 2, 3, 4], [1, 2]]
    L = [[1.1, 2, 3, 4], [1, 2]]

void WriteImg string  sName,
image  Img
 

Write image to a file.

Parameters:
sName A filename.
Img The image variable
Returns:
Nothing.
Since:
v2.2
Stores an image in a file with the name sName in the format specified by the extension of the filename. Possible file formats are '.bmp', '.jpg', '.pcx', '.png', '.raw', '.sgi', '.tga', '.tif'.

string WriteText string  sFilename,
string  sData
 

Write the contents of a string variable to a file.

Parameters:
sFilename The filename.
sData The string to be written.
Returns:
The string 'OK', when no error occured and an error message otherwise.
Since:
v2.3
This function writes the contents of a string variable to a file.

string WriteVar string  sName,
any_type  vData,
counter  iComp
 

Write the contents of a variable to a file in XML format.

Parameters:
sName A filename.
vData A variable of any type.
iComp The compression level of the XML file. Has to be an integer value between 0 and 9. The default is 0, which is no compression.
Returns:
The string 'OK', when no error occured and an error message otherwise.
Since:
v2.2
This function writes the contents of a variable to a file using a XML format. In particular, the variable can be a variable list containing a number of variables of different types. Note that also vertex lists can be stored in this way.