The bps.File class provides functionality for reading and writing binary and text files. More...

Public Types
enum	AccessMode { ReadOnly = 0x0001, WriteOnly = 0x0002, ReadWrite = 0x0003, Append = 0x0004, Truncate = 0x0008, Text = 0x0010, Unbuffered = 0x0020 }
	This enum is used with open() to describe the mode in which a device is opened. More...

Public Member Functions
void	close ()
	Closes the file.
	File (String aFileName)
	Creates a file object with the with fileName.
void	open (AccessMode aAccessMode)
	Opens the file in the specified access mode if possible; otherwise throws an exception.
String	read ()
	Returns the entire content of the file as a string if it can be read; otherwise throws an exception.
Number	readByte ()
	Reads one byte from the file if possible; otherwise throws an exception.
String	readLine ()
	Reads one line from file if possible; otherwise throws an exception.
Array	readLines ()
	Read the contents of the file as an array of Strings, one for each line.
void	remove ()
	Deletes the file if possible; otherwise throws an exception.
String	toString () const
void	write (String aData)
	Writes data to the file if possible; otherwise throws an exception.
void	writeByte (Number aByte)
	Writes a byte to the file is possible; otherwise throws an exception.
void	writeLine (String aData)
	Writes the line data to the file and adds a linebreak.

Static Public Member Functions
static Boolean	exists (String aFileName)
	Check if file exists.
static Boolean	isDir (String aFileName)
	Check if aFileName is a directory.
static Boolean	isFile (String aFileName)
	Check if aFileName is a file.
static String	read (String aFileName)
	Reads and returns the contents of the file fileName if possible; otherwise throws an exception.
static void	remove (String aFileName)
	Deletes the file if possible; otherwise throws an exception.
static void	write (String aFileName, String aContent)
	Writes the string content to the file fileName if possible (completely replacing the original contents if the file already exists); otherwise throws an exception.

Properties
String	baseName
	The name of the file, excluding its path and extension.
Date	created
	The creation time of the file.
Number	defaultEncoding
	Default encoding used for static text read/write methods, and initial encoding for files opened subsequently in script context.
Number	encoding
	Encoding for the non-static text read and write methods.
Boolean	eof
	True if reading has reached the end of the file; otherwise false.
Boolean	executable
	True if the file is executable; otherwise false.
Boolean	exists
	True if the file exists; otherwise false.
String	extension
	The file name's extension.
String	fullName
	The fullName of the file, including path, name, and extension.
Boolean	hidden
	True if the file is hidden; otherwise false.
Date	lastModified
	The last modification time of the file.
Date	lastRead
	The last time the file was read.
String	name
	The name of the file including the extension.
String	path
	The path of the file.
Boolean	readable
	True if the file is readable; otherwise false.
Number	size
	The size of the file, in bytes.
String	symLink
	The expansion of the symlink if the file is a symlink; otherwise empty.
Boolean	writable
	True if the file is writable; otherwise false.

Detailed Description

The bps.File class provides functionality for reading and writing binary and text files.

A File can be instantiated as an object, giving the scripter complete flexibility when reading and writing files. In addition, the File class provides a set of static convenience functions for reading and writing files in one go. Text reading and writing uses the UTF-8 encoding by default, but alternate encoding may be selected as Local8Bit, Latin1 and IBM 850 for the non-static read and write methods.

// Reads an entire file in one go
var log = bps.File.read('file.log');
// Writes an entire file in one go
bps.File.write('copy_of_file.log', log);
    
// Read and write a file line by line
var infile = new bps.File('file.log');
infile.open(bps.File.ReadOnly);
    
var outfile = new bps.File('copy_of_file.log');
outfile.open(bps.File.WriteOnly);
    
while (!infile.eof) {
    var line = infile.readLine();
    outfile.write( line );
}
    
infile.close();
outfile.close();

Member Enumeration Documentation

enum bps::File::AccessMode

This enum is used with open() to describe the mode in which a device is opened.

Enumerator:

ReadOnly	Opens the file in read-only mode.
WriteOnly	Opens the file in write-only mode.
ReadWrite	The device is open for reading and writing.
Append	The device is opened in append mode, so that all data is written to the end of the file.
Truncate	If possible, the device is truncated before it is opened. All earlier contents of the device are lost.
Text	When reading, the end-of-line terminators are translated to '\n'. When writing, the end-of-line terminators are translated to the local encoding, for example '\r\n' for Win32.
Unbuffered	Any buffer in the device is bypassed.

Constructor & Destructor Documentation

bps::File::File ( String aFileName )

Creates a file object with the with fileName.

Parameters

aFileName The file name to use.

Exceptions

Error thrown if file name is missing or is not a String.

Member Function Documentation

static Boolean bps::File::exists ( String aFileName )

static

Check if file exists.

Parameters

aFileName The name of the file.

Returns: True if aFileName exists, false otherwise.

static Boolean bps::File::isDir ( String aFileName )

static

Check if aFileName is a directory.

Parameters

aFileName The name of the file.

Returns: True if aFileName is a directory; otherwise returns false.

static Boolean bps::File::isFile ( String aFileName )

static

Check if aFileName is a file.

Parameters

aFileName The name of the file.

Returns: True if aFileName is a file; otherwise returns false.

void bps::File::open ( AccessMode aAccessMode )

Opens the file in the specified access mode if possible; otherwise throws an exception.

Parameters

aAccessMode The file accessmode flag(s).

Exceptions

Error thrown if open fails.

String bps::File::read ( )

Returns the entire content of the file as a string if it can be read; otherwise throws an exception.

Returns: The file content.

Exceptions

Error thrown if read fails.

static String bps::File::read ( String aFileName )

static

Reads and returns the contents of the file fileName if possible; otherwise throws an exception.

Parameters

aFileName The name of the file.

Returns: The content of the file.

Exceptions

Error thrown if read fails.

Number bps::File::readByte ( )

Reads one byte from the file if possible; otherwise throws an exception.

Returns: The numeric code of the byte read.

Exceptions

Error thrown if read fails.

String bps::File::readLine ( )

Reads one line from file if possible; otherwise throws an exception.

Retains any trailing whitespace.

Returns: The line read if not eof.

Exceptions

Error thrown if read fails.

Array bps::File::readLines ( )

Read the contents of the file as an array of Strings, one for each line.

Linebreaks are strippped from the strings. If the file could not be read, an exception is thrown.

Returns: Array of String with the file contents.

void bps::File::remove ( )

Deletes the file if possible; otherwise throws an exception.

Exceptions

Error thrown if remove fails.

static void bps::File::remove ( String aFileName )

static

Deletes the file if possible; otherwise throws an exception.

Parameters

aFileName The name of the file.

Exceptions

Error thrown if remove fails.

String bps::File::toString ( ) const

Returns: Returns "File(file name)"

void bps::File::write ( String aData )

Writes data to the file if possible; otherwise throws an exception.

Parameters

aData The data to write.

static void bps::File::write	(	String	aFileName,
		String	aContent
	)

static

Writes the string content to the file fileName if possible (completely replacing the original contents if the file already exists); otherwise throws an exception.

Parameters

aFileName	The name of the file.
aContent	The content of the file.

Exceptions

Error thrown if write fails.

void bps::File::writeByte ( Number aByte )

Writes a byte to the file is possible; otherwise throws an exception.

Parameters

aByte The numeric code of the byte to write.

void bps::File::writeLine ( String aData )

Writes the line data to the file and adds a linebreak.

If the file could not be written error is returned.

Parameters

aData The data to write in a line.

Property Documentation

String bps::File::baseName

read

The name of the file, excluding its path and extension.

Date bps::File::created

read

The creation time of the file.

Number bps::File::defaultEncoding

readwrite

Default encoding used for static text read/write methods, and initial encoding for files opened subsequently in script context.

The initial default encoding at application start is UTF-8.

Constant	Encoding
bps.File.Utf8	UTF-8
bps.File.Latin1	Latin 1
bps.File.Local8Bit	Local 8 Bit
bps.File.IBM850	IBM 850

Note: Changing the default encoding will not change the encoding of files previously opened in script context. It will however effect existing files created in C++ context, when the encoding property was not yet changed from within a script.

Number bps::File::encoding

readwrite

Encoding for the non-static text read and write methods.

The encoding of files opened in script context is initialized to the value of defaultEncoding at opening time. The encoding of files opened in C++ context is bps.File.Default.

Constant	Encoding
bps.File.Default	Use defaultEncoding.
bps.File.Utf8	UTF-8
bps.File.Latin1	Latin 1
bps.File.Local8Bit	Local 8 Bit
bps.File.IBM850	IBM 850

Boolean bps::File::eof

read

True if reading has reached the end of the file; otherwise false.

Boolean bps::File::executable

read

True if the file is executable; otherwise false.

Boolean bps::File::exists

read

True if the file exists; otherwise false.

String bps::File::extension

read

The file name's extension.

String bps::File::fullName

read

The fullName of the file, including path, name, and extension.

Boolean bps::File::hidden

read

True if the file is hidden; otherwise false.

Date bps::File::lastModified

read

The last modification time of the file.

Date bps::File::lastRead

read

The last time the file was read.

String bps::File::name

read

The name of the file including the extension.

String bps::File::path

read

The path of the file.

Boolean bps::File::readable

read

True if the file is readable; otherwise false.

Number bps::File::size

read

The size of the file, in bytes.

String bps::File::symLink

read

The expansion of the symlink if the file is a symlink; otherwise empty.

Boolean bps::File::writable

read

True if the file is writable; otherwise false.

Public Types

Public Member Functions

Static Public Member Functions

Properties

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Property Documentation