![]() |
Section 8.10.1.4:
|
![]() |
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 Object_Type = seq of Obj_Type ; -- see $OB specification 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 sequence of objects stored in the environment in which th program is executing. This abstraction could be extended to consider any named external entity which has a similar uniform interface to the program.
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 :-
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 |
open_for_read(name : STR) res : [SAME]
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 len name > 0 and let path = FILE_PATH.create(name) in (path <> nil) and let dir = DIRECTORY.existent(FILE_PATH.head(path)) in (dir <> nil) and DIRECTORY.exists(dir, FILE_PATH.leaf(path))
Providing all general pre-conditions are satisfied then a new connection to the named file is returned.
post res = nil or (readable(res) and not writable(res) and (position(res) = 0)
Providing that the file access permission criteria for opening the file for reading are met the file object will be returned with the file pointer set to the beginning of the file, otherwise void is returned.
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 |
open_for_write(name : STR) res : [SAME]
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 len name > 0 and let path = FILE_PATH.create(name) in (path <> nil) and let dir = DIRECTORY.existent(FILE_PATH.head(path)) in (dir <> nil) and DIRECTORY.exists(dir, FILE_PATH.leaf(path))
post res = nil or (writable(res) and not readable(res) and (position(res) = 0)
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.
This feature opens an existing file for writing - providing file access criteria are 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 |
open_at_end(name : STR) res : [SAME]
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 len name > 0 and let path = FILE_PATH.create(name) in (path <> nil) and let dir = DIRECTORY.existent(FILE_PATH.head(path)) in (dir <> nil) and DIRECTORY.exists(dir, FILE_PATH.leaf(path))
post res = nil or (writable(res) and not readable(res) and (position(res) = size(res))
Providing that file access permission criteria for opening the file for appending are met 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.
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 |
open_for_update(name : STR) res : [SAME]
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 len name > 0 and let path = FILE_PATH.create(name) in (path <> nil) and let dir = DIRECTORY.existent(FILE_PATH.head(path)) in (dir <> nil) and DIRECTORY.exists(dir, FILE_PATH.leaf(path))
post res = nil or (writable(res) and readable(res) and (position(res) = 0)
Providing that file access permission criteria for opening the file for both reading and writing are met the routine returns the file object desired with the file pointer indicateing the beginning of the file, otherwise void is returned. Reading and writing of any part of the file may be undertaken in any desired sequence.
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 |
open_at_end_for_update(name : STR) res : [SAME]
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 len name > 0 and let path = FILE_PATH.create(name) in (path <> nil) and let dir = DIRECTORY.existent(FILE_PATH.head(path)) in (dir <> nil) and DIRECTORY.exists(dir, FILE_PATH.leaf(path))
post res = nil
or (writable(res)
and readable(res)
and (position(res) = size(res))
Providing that file access permission criteria for opening the file for reading and writing are met then the file object will be returned with the file pointer set to the end of the file, otherwise void is returned. After an initial write reading and writing of any part of the file may be undertaken in any desired sequence.
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 |
create_for_write(name : STR) res : [SAME]
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 len name > 0 and let path = FILE_PATH.create(name) in (path <> nil) and let dir = DIRECTORY.existent(FILE_PATH.head(path)) in (dir <> nil) and not DIRECTORY.exists(dir, FILE_PATH.leaf(path))
Providing all general pre-conditions are satisfied then a new empty file is created and a connection to it returned.
post res = nil or (writable(res) and not readable(res) and (position(res) = 0)
Providing that no environment detected errors occur the feature returns the new file object with the file pointer set to the beginning of the file for writing only, otherwise void is returned.
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 |
create_for_update(name : STR) res : [SAME]
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 len name > 0 and let path = FILE_PATH.create(name) in (path <> nil) and let dir = DIRECTORY.existent(FILE_PATH.head(path)) in (dir <> nil) and not DIRECTORY.exists(dir, FILE_PATH.leaf(path))
post res = nil or (writable(res) and not readable(res) and (position(res) = 0)
provided that no environment detected error is encountered then this feature returns a new file object with the file pointer set to the beginning of the file for writing. Writing and reading may be carried out in any order.
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 |
create_temp() res : [SAME]
The only general pre-condition which need be met is the ability to create a temporary directory in some implementation-defined location in file space.
post res = nil or (writable(res) and readable(res) and (position(res) = 0)
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.
This feature is provided to close the connection to the underlying file storage object.
close(self : SAME)
The pre-condition is true since one of the three following conditions hold, none of which influence the way in which a close operation can or cannot succeed -
pre true
post not is_open(self)
This feature closes the connection to the external file and invalidates this object for further file access.
This predicate returns true if and only if the file is readable.
readable(self : SAME) res : BOOL
Since this routine is a predicate, the pre-condition is vacuously true.
Since this routine is 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.
This predicate returns true if and only if the file is writable.
writable(self : SAME) res : BOOL
Since this routine is a predicate, the pre-condition is vacuously true.
Since this routine is 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.
This predicate returns true if and only if the file connected has not been closed.
is_open(self : SAME) res : BOOL
Since this routine is a predicate, the pre-condition is vacuously true.
Since this routine is a predicate, the post-condition is also vacuously true.
This feature returns true if and only if the file has not been closed.
This predicate returns true if and only if the file is both open for update and has not been closed.
writable(self : SAME) res : BOOL
Since this routine is a predicate, the pre-condition is vacuously true.
Since this routine is 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.
This routine returns the current position of the notional file pointer. Note that it is not possible to set this value unless a $FILE_CURSOR object is being used!
position(self : SAME) res : CARD
pre is_open(self) and not error(self)
post (res <> CARD.nil) or error(self)
This routine returns the current position of a notional file cursor providing that the file is open, otherwise if some error occurred in the execution environment then the value CARD::maxval.
This feature provides the current size of the file. Note that a file opened for reading only will always have the same size.
size(self : SAME) res : CARD
pre is_open(self) and not error(self)
post res = len self
This routine returns the current size of the file. Note that this may not reflect the current file stored in the environment's actual size, since this depends on whether current contents have been flushed.
This predicate may be used to determine whether there has been a problem relating to the file connection.
error(self : SAME) res : BOOL
Since this routine is a predicate, the pre-condition is vacuously true.
Since this routine is 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.
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(self : SAME) res : STR
pre error(self)
post len 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.
This feature clears any error which may have occurred in the underlying file system in relation to the file.
clear(self : SAME)
pre true
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 toKeith Hopper. Page last modified: Wednesday, 4 April 2001. |
![]() |