File class

The File class allows you to read and write from text files. More...

The REPORTER JavaScript API provides many class constants, properties and methods. For Arup to be able to extend and enhance the API in the future any constant, property or method names beginning with a lowercase or uppercase letter are reserved.
If you need to add your own properties or methods to one of the existing classes then to avoid any potential future conflict you should ensure that the name begins with either an underscore (_) or a dollar sign ($) or the name is prefixed with your own unique identifier.
For example if company 'ABC' need to add a property called 'example' then to avoid any potential future conflict use one of:

Class functions

Member functions

File constants

Name Description
File.APPEND Flag to open file for appending
File.EOF Flag to indicate end of file
File.READ Flag to open file for reading
File.WRITE Flag to open file for writing

Detailed Description

The File class allows you to read text and write text to files. There are various functions available that allow to to find lines matching specific strings or regular expressions when reading.
Additionally, there are a number of utility functions to check if a file exists or is a directory etc.

Constructor

new File(filename[string], mode[constant])

Description

Create a new File object for reading and writing text files.

Arguments

  • filename (string)

    Filename of the file you want to read/write. If reading, the file must exist. If writing, the file will be overwritten if it already exists

  • mode (constant)

    The mode to open the file with. Can be File.READ, File.WRITE or File.APPEND

    Returns

    File object

    Return type

    File

    Example

    To create a new file object to read file "/data/test/file.txt" 

    var f = new File("/data/test/file.txt", File.READ);

    Details of functions

    Close()

    Description

    Close a file opened by a File object.

    Arguments

    No arguments

    Returns

    No return value

    Example

    To close File object f. 

    f.Close();

    ConvertSeparators(filename[string]) [static]

    Description

    Convert directory separators to the correct type for this operating system

    Arguments

  • filename (string)

    Filename you want to convert separators on.

    Returns

    string filename

    Return type

    String

    Example

    e.g. on windows the filename "c:/test/file.key" would be converted to "c:\test\file.key" by 

    var converted = File.ConvertSeparators("c:/test/file.key");

    Copy(source[string], dest[string]) [static]

    Description

    Copy a file

    Arguments

  • source (string)

    Source filename you want to copy.

  • dest (string)

    Destination filename you want to copy source file to. Note that if a file with the name dest already exists it will not be overwritten. Delete the file first with File.Delete().

    Returns

    true if copy successful, false otherwise.

    Return type

    Boolean

    Example

    To copy the file "/data/test/file.txt" to "/data/test/file.txt_backup" 

    var copied = File.Copy("/data/test/file.txt", "/data/test/file.txt_backup");

    Delete(filename[string]) [static]

    Description

    Delete a file

    Arguments

  • filename (string)

    Filename you want to delete.

    Returns

    true if successful, false if not

    Return type

    Boolean

    Example

    To delete the file "/data/test/file.txt" 

    var deleted = File.Delete("/data/test/file.txt");

    Directory(filename[string]) [static]

    Description

    Extract directory name from an absolute filename

    Arguments

  • filename (string)

    Absolute filename you want to extract directory from.

    Returns

    string directory

    Return type

    String

    Example

    To extract the directory "/data/test/" from file "/data/test/file.key" 

    var directory = File.Directory("/data/test/file.key");

    DriveMapFilename(filename[string], format[constant]) [static]

    Description

    Changes a filename or directory name to the correct format for a specific operating system using the directory mappings (if present).

    Arguments

  • filename (string)

    Filename you want to drive map.

  • format (constant)

    The format for the file/directory name. Can be Include.NATIVE, Include.UNIX, or Include.WINDOWS.

    Returns

    string containing drive mapped filename.

    Return type

    String

    Example

    If REPORTER has drive S:\ mapped to /data/ (by using the oasys*drive_s preference) 

    var mapped = File.DriveMapFilename("/data/test/file.ptf", Include.WINDOWS);

    mapped will be "S:\test\file.ptf". 

    var mapped = File.DriveMapFilename("S:\\test\\file.ptf", Include.UNIX);

    mapped will be "/data/test/file.ptf",

    Exists(filename[string]) [static]

    Description

    Check if a file exists

    Arguments

  • filename (string)

    Filename you want to check for existance.

    Returns

    true/false

    Return type

    Boolean

    Example

    To see if the file "/data/test/file.key" exists 

    if (File.Exists("/data/test/file.key")) { do something }

    FindFiles(directory[string], pattern[string], recursive[boolean]) [static]

    Description

    Find any files in a directory (and subdirectories if required) matching a pattern

    Arguments

  • directory (string)

    Directory to look for files in

  • pattern (string)

    Pattern to use to find matching files

  • recursive (boolean)

    If Reporter should look for files recursively or not

    Returns

    array filenames

    Return type

    String

    Example

    To find all of the files matching the pattern "*.key" recursively from directory /data/test 

    var filelist = File.FindFiles("/data/test/", "*.key", true);

    FindLineContaining(contain[string])

    Description

    Reads a line from a file which contains contain, opened for reading by a File object. To enable this function to be as fast as possible a maximum line length of 256 characters is used. If you expect a file to have lines longer than 256 characters then use ReadLongLine which allows lines of any length. If one argument is used then the line must contain that string. If more than one argument is used then lines which contain any of the arguments will be returned

    Arguments

  • contain (string)

    String which matching lines must contain (maximum length of 256 characters).

    This argument can be repeated if required
    Alternatively a single array argument containing the multiple values can be given

    Returns

    string read from file or File.EOF if end of file

    Return type

    String

    Example

    Loop, reading lines from File object f which contain 'example'. 

    var line;

while ( (line = file.FindLineContaining("example") ) != File.EOF)
{
}

    FindLineMatching(regex[RegExp])

    Description

    Reads a line from a file opened for reading by a File object. To enable this function to be as fast as possible a maximum line length of 256 characters is used. If you expect a file to have lines longer than 256 characters then use ReadLongLine which allows lines of any length. Note that this may be much slower than FindLineStarting or FindLineContaining, especially if the regular expression is very complicated.

    Arguments

  • regex (RegExp)

    Regular expression which matching lines must match with.

    Returns

    string read from file or File.EOF if end of file

    Return type

    String

    Example

    Loop, reading lines from File object f which contain digits. 

    var line;
var regex = new RegExp("\\d+");

while ( (line = file.FindLineMatching(regex) ) != File.EOF)
{
}

    FindLineStarting(start[string])

    Description

    Reads a line from a file which starts with start, opened for reading by a File object. To enable this function to be as fast as possible a maximum line length of 256 characters is used. If you expect a file to have lines longer than 256 characters then use ReadLongLine which allows lines of any length. If one argument is used then the line must start with that string. If more than one argument is used then lines which start with any of the arguments will be returned

    Arguments

  • start (string)

    String which matching lines must start with (maximum length of 256 characters).

    This argument can be repeated if required
    Alternatively a single array argument containing the multiple values can be given

    Returns

    string read from file or File.EOF if end of file

    Return type

    String

    Example

    Loop, reading lines from File object f which start 'example'. 

    var line;

while ( (line = file.FindLineStarting("example") ) != File.EOF)
{
}

    Flush()

    Description

    Flushes a file opened for writing by a File object.

    Arguments

    No arguments

    Returns

    No return value

    Example

    To flush File object f. 

    f.Flush();

    IsAbsolute(filename[string]) [static]

    Description

    Check if a filename is absolute

    Arguments

  • filename (string)

    Filename you want to test if absolute.

    Returns

    true/false

    Return type

    Boolean

    Example

    To see if the file "/data/test/file.key" is absolute 

    if (File.IsAbsolute("/data/test/file.key")) { do something }

    IsDirectory(filename[string]) [static]

    Description

    Check if a filename is a directory

    Arguments

  • filename (string)

    Filename you want to test to see if it is a directory.

    Returns

    true/false

    Return type

    Boolean

    Example

    To see if "/data/test" is a directory 

    if (File.IsDirectory("/data/test")) { do something }

    IsFile(filename[string]) [static]

    Description

    Check if a filename is a file

    Arguments

  • filename (string)

    Filename you want to test to see if it is a file (i.e. not a directory).

    Returns

    true/false

    Return type

    Boolean

    Example

    To see if "/data/test" is a file 

    if (File.IsFile("/data/test")) { do something }

    Mkdir(name[string]) [static]

    Description

    makes a directory

    Arguments

  • name (string)

    Directory you want to create.

    Returns

    true if successful

    Return type

    Boolean

    Example

    To make directory "/data/test" if it does not exist: 

    if (!File.IsDirectory("/data/test")) File.Mkdir("/data/test");

    Move(source[string], dest[string]) [static]

    Description

    Move a file

    Arguments

  • source (string)

    Source filename you want to move.

  • dest (string)

    Destination filename you want to move (rename) source file to. Note that if a file with the name dest already exists it will not be overwritten. Delete the file first with File.Delete().

    Returns

    true if move successful, false otherwise.

    Return type

    Boolean

    Example

    To move the file "/data/test/file.txt" to "/data/test/file.txt_backup" 

    var moved = File.Move("/data/test/file.txt", "/data/test/file.txt_backup");

    ReadChar()

    Description

    Reads a single character from a file opened for reading by a File object.

    Arguments

    No arguments

    Returns

    character read from file or File.EOF if end of file

    Return type

    String

    Example

    Loop, reading characters from File object f. 

     var c;

while ( (c = f.ReadChar()) != undefined) { ... }

    ReadLine()

    Description

    Reads a line from a file opened for reading by a File object. To enable this function to be as fast as possible a maximum line length of 256 characters is used. If you expect a file to have lines longer than 256 characters then use ReadLongLine which allows lines of any length.

    Arguments

    No arguments

    Returns

    string read from file or File.EOF if end of file

    Return type

    String

    Example

    Loop, reading lines from File object f. 

    var line;

while ( (line = file.ReadLine() ) != File.EOF)
{
}

    ReadLongLine()

    Description

    Reads a line from a file opened for reading by a File object. The line can be any length. If your file has lines shorter than 256 characters then you may want to use ReadLine instead which is faster.

    Arguments

    No arguments

    Returns

    string read from file or File.EOF if end of file

    Return type

    String

    Example

    Loop, reading lines from File object f. 

    var line;

while ( (line = file.ReadLongLine() ) != File.EOF)
{
}

    Seek(position[integer])

    Description

    Sets the file position for reading a file

    Arguments

  • position (integer)

    Position you want to seek to.

    Returns

    No return value

    Example

    To seek to position 1000 in file object f: 

    f.Seek(1000);

    SimplifyName(filename[string]) [static]

    Description

    Simplify the name of a file by removing //, /./ and /../

    Arguments

  • filename (string)

    Filename you want to simplify.

    Returns

    string filename

    Return type

    String

    Example

    To simplify the filename "/data/test//../file.key" 

    var simple = File.SimplifyName("/data/test//../file.key");

    This simplifies to "/data/file.key"

    Size(filename[string]) [static]

    Description

    Get the size of a file

    Arguments

  • filename (string)

    File you want to find the size of.

    Returns

    integer

    Return type

    Number

    Example

    To find the size of file "/data/test" 

    var size = File.Size("/data/test");

    Write(string[Any valid javascript type])

    Description

    Write a string to a file opened for writing by a File object

    Arguments

  • string (Any valid javascript type)

    The string/item that you want to write

    Returns

    No return value

    Example

    To write string "Hello, world!" to File object f 

    f.Write("Hello, world!\n");

    To write the title of model 2 to File object f 

    f.Write("The title of model 2 is " + models[2].title + "\n");