| # Section 8.10.1.4: $FILES |

###### abstract class $FILES

#### Formal Definitions

This abstract class defines a state component which is a set of all instantiations of objects of any class sub-typing from this class in addition to the vdm model types used wherever this class name is used. Note that SAME has to be an instantiated class, not an abstract one.

types
SAME = object_type ;
$FILES = set of object_type
state
multi : $FILES
inv multi_types ==
forall obj in set multi_types & sub_type($FILES,obj)

NOTE | See the important note about vdm state in the notes on vdm-sl usage in this specification.

This abstraction models the conventional notion of a file as a container for data which is is held externally to a program in some filing system. This abstraction can be extended to consider any named external entity which has a similar uniform interface to the program.

## General Pre-conditions

Compared with most Sather required library classes the group of file opening/creating features which follow are tightly constrained by the state of the environment at the time the program executes. There are a number of general conditions which are pre-requisite to them all but which are not amenable to the use of formal specification tools. These are :-

- Naming - The name by which a file is known is usually considered to be some kind of text string acceptable to a local Command Line Interface.
- Encoding - The text string used to identify a file must be encoded in the repertoire and encoding of the environment in which the program is executing. There is specifically no requirement for this to be the environment in which the program was created.
- File Path - The form of file path used for identifying a file will generally be highly operating system specific. It is strongly recommended that the class FILE_PATH is used for any path construction/parsing which may be needed since it is operating system independent.
- Existence - Where a file is to be opened then the file must exist. Where it is to be created then it must not exist before attempting creation. If it is necessary to delete an existing file then facilities for doing this are provided in the File System section of the Required Library (in particular see the class DIRECTORY).
- Access - The required actions can only be taken if the user of the program has access permission to take the desired actions in respect of the file concerned. Access testing features are available in the FILE_LABEL class in the Required Library.

#### open_for_read

This feature opens an existing file for reading - providing all of the general pre-requisites have been met. The notional file pointer is positioned at the beginning of the file.

open_for_read | (
| name : STR
| ) : SAME

##### Formal Signature

open_for_read(name : STR) res : [SAME]

##### Pre-condition

The general pre-conditions given should be satisfied for successful operation - but are necessarily tested during execution - in addition to the one given below.

pre STR.size(name) > 0

##### Post-condition

Providing all general pre-conditions are satisfied then a new connection to the named file is returned.

This feature determines if the file with the given name exists and attempts to open it if it does exist providing that the file access permission criteria for opening the file for reading are met. If these necessarily dynamic checks are met then a connection to the file object will be returned with the file pointer set to the beginning of the file, otherwise void is returned.

#### open_for_write

This feature opens an existing file for writing - providing all of the general pre-requisites have been met. The notional file pointer is positioned at the beginning of the file ready for writing. Note that any existing contents is lost.

open_for_write | (
| name : STR
| ) : SAME

##### Formal Signature

open_for_write(name : STR) res : [SAME]

##### Pre-condition

The general pre-conditions given should be satisfied for successful operation - but are necessarily tested during execution - in addition to the one given below.

pre STR.size(name) > 0

##### Post-condition

Providing all general pre-conditions are satisfied then a new connection to the named file is returned.

This feature determines if the file with the given name exists and attempts to open it if it does exist providing that the file access permission criteria for opening the file for writing are met. If these necessarily dynamic checks are met then a connection to the file object will be returned with the file pointer set to the beginning of the file ready for writing only, otherwise void is returned.

#### open_at_end

This feature opens an existing file for writing - providing all of the general pre-requisites have been met. The notional file pointer is positioned at the end of the current file contents ready for writing. Note that any existing contents are inaccessible.

open_at_end | (
| name : STR
| ) : SAME

##### Formal Signature

open_at_end(name : STR) res : [SAME]

##### Pre-condition

The general pre-conditions given should be satisfied for successful operation - but are necessarily tested during execution - in addition to the one given below.

pre STR.size(name) > 0

##### Post-condition

Providing all general pre-conditions are satisfied then a new connection to the named file is returned.

This feature determines if the file with the given name exists and attempts to open it if it does exist providing that the file access permission criteria for opening the file for appending are met. If these necessarily dynamic pre-conditions are met then a connection to the file object will be returned with the file pointer set to the end of the file ready for writing only, otherwise void is returned.

#### open_for_update

This feature opens an existing file for update - providing all of the general pre-requisites have been met. The notional file pointer is positioned at the beginning of the file.

open_for_update | (
| name : STR
| ) : SAME

##### Formal Signature

open_for_update(name : STR) res : [SAME]

##### Pre-condition

The general pre-conditions given should be satisfied for successful operation - but are necessarily tested during execution - in addition to the one given below.

pre STR.size(name) > 0

##### Post-condition

Providing all general pre-conditions are satisfied then a new connection to the named file is returned.

This feature determines if the file with the given name exists and attempts to open it if it does exist providing that the file access permission criteria for opening the file for both reading and writing are met. If these necessarily dynamic pre-conditions are met then a connection to the file object will be returned with the file pointer set to the beginning of the file, otherwise void is returned. Reading and writing of any part of the file may then be undertaken in any desired combination.

#### open_at_end_for_update

This feature opens an existing file with the notional file pointer at the end for update - providing all of the general pre-requisites have been met.

open_at_end_for_update | (
| name : STR
| ) : SAME

##### Formal Signature

open_at_end_for_update(name : STR) res : [SAME]

##### Pre-condition

The general pre-conditions given should be satisfied for successful operation - but are necessarily tested during execution - in addition to the one given below.

pre STR.size(name) > 0

##### Post-condition

Providing all general pre-conditions are satisfied then a new connection to the named file is returned.

This feature determines if the file with the given name exists and attempts to open it if it does exist providing that the file access permission criteria for opening the file for reading and writing are met. Providing that these necessarily dynamic pre-conditions are met then a connection to the file object will be returned with the file pointer set to the end of the file, otherwise void is returned. Reading and writing of any part of the file may then be undertaken in any desired combination.

#### create_for_write

This feature creates a new file with the notional file pointer at the beginning for writing only - providing all of the general pre-requisites have been met.

create_for_write | (
| name : STR
| ) : SAME

##### Formal Signature

create_for_write(name : STR) res : [SAME]

##### Pre-condition

The general pre-conditions given should be satisfied for successful operation - but are necessarily tested during execution - in addition to the one given below.

pre STR.size(name) > 0

##### Post-condition

Providing all general pre-conditions are satisfied then a new empty file is created and a connection to it returned.

This feature determines if the file with the given name exists. Providing that the file does not exist and that access permission criteria for creating the file are met then a connection to the new file object will be returned with the file pointer set to the beginning of the file for writing only, otherwise void is returned.

#### create_for_update

This feature creates a new file with the notional file pointer at the beginning for writing and reading - providing all of the general pre-requisites have been met.

create_for_update | (
| name : STR
| ) : SAME

##### Formal Signature

create_for_update(name : STR) res : [SAME]

##### Pre-condition

The general pre-conditions given should be satisfied for successful operation - but are necessarily tested during execution - in addition to the one given below.

pre STR.size(name) > 0

##### Post-condition

Providing all general pre-conditions are satisfied then a new empty file is created and a connection to it returned.

This feature determines if the file with the given name exists. Providing that the file does not exist and that access permission criteria for creating the file are met then a connection to the new file object will be returned with the file pointer set to the beginning of the file for writing, otherwise void is returned. Writing and reading may be carried out in any order.

#### create_temp

This feature creates a new temporary file with the notional file pointer at the beginning for writing and reading - providing all of the general pre-requisites have been met. When closed the file, being temporary, will no longer exist.

create_temp | : SAME

##### Formal Signature

create_temp() res : [SAME]

##### Pre-condition

The only general pre-condition which need be met is the ability to create a temporary directory somewhere - in addition to the one which follows.

pre STR.size(name) > 0

##### Post-condition

Providing the creation pre-condition is satisfied then a new empty temporary file is created and a connection to it returned.

Providing that the creatioin pre-conditioin is satisfied thena new temporary file will be created and a connection to it will be returned with the file pointer set to the beginning of the file for writing, otherwise void is returned. Writing and reading may be carried out in any order.

#### close

This feature is provided to close the connection to the underlying file storage object.

close

##### Formal Signature

close(self : SAME)

##### Pre-condition

pre true

##### Post-condition

post not is_open(self)

This feature closes the connection to the external file and invalidates this object for further file access.

#### readable

This predicate returns true if and only if the file is readable.

readable | : BOOL

##### Formal Signature

readable(self : SAME) res : BOOL

##### Pre-condition

Being a predicate the pre-condition is vacuously true.

##### Post-condition

Being a predicate the post-condition is also vacuously true.

This feature returns true if and only if the file is both open and readable, otherwise false.

#### writable

This predicate returns true if and only if the file is writable.

writable | : BOOL

##### Formal Signature

writable(self : SAME) res : BOOL

##### Pre-condition

Being a predicate the pre-condition is vacuously true.

##### Post-condition

Being a predicate the post-condition is also vacuously true.

This feature returns true if and only if the file is both open and writable, otherwise false.

#### is_open

This predicate returns true if and only if the file connected has not been closed.

is_open | : BOOL

##### Formal Signature

is_open(self : SAME) res : BOOL

##### Pre-condition

Being a predicate the pre-condition is vacuously true.

##### Post-condition

Being a predicate the post-condition is also vacuously true.

This feature returns true if and only if the file has not been closed.

#### update

This predicate returns true if and only if the file is both open for update and has not been closed.

update | : BOOL

##### Formal Signature

writable(self : SAME) res : BOOL

##### Pre-condition

Being a predicate the pre-condition is vacuously true.

##### Post-condition

Being a predicate the post-condition is also vacuously true.

This feature returns true if and only if the file has not been closed and is open for update, otherwise false.

#### error

This predicate may be used to determine whether there has been a problem relating to the file connection.

error | : BOOL

##### Formal Signature

error(self : SAME) res : BOOL

##### Pre-condition

Being a predicate the pre-condition is vacuously true.

##### Post-condition

Being a predicate the post-condition is also vacuously true.

This feature provides an indication whether some error in the program environment has affected the behaviour of the file since either creation or the most recent use of the clear feature defined below.

#### error_message

This feature provides a program environment dependent string indicating the nature of any error which may have been detected. Note that the message only refers to the latest error (if any) in an environment-defined manner.

error_message | : STR

##### Formal Signature

error_message(self : SAME) res : STR

##### Pre-condition

pre error(self)

##### Post-condition

post STR.size(res) > 0

This feature provides an environment defpendent message describing the most recent error in the program environment which has affected the behaviour of the file connection since opening/creation or the most recent use of the clear feature defined below.

#### clear

This feature clears any error which may have occurred in the underlying file system in relation to the file.

clear

##### Formal Signature

clear(self : SAME)

##### Pre-condition

pre true

##### Post-condition

post not error(self)

This feature provides a way of clearing any error which may have occurred in relation to the file.

| Language Index |  | Library Index |  | Input/Output Index

Comments or enquiries should be made to Keith Hopper. Page last modified: Tuesday, 18 July 2000. |