iocursors.sa
Generated by gen_html_sa_files from ICSI. Contact gomes@icsi.berkeley.edu for details
-------------------------> GNU Sather - sourcefile <-------------------------
-- Copyright (C) 2000 by K Hopper, University of Waikato, New Zealand --
-- This file is part of the GNU Sather library. It is free software; you may --
-- redistribute and/or modify it under the terms of the GNU Library General --
-- Public License (LGPL) as published by the Free Software Foundation; --
-- either version 2 of the license, or (at your option) any later version. --
-- This library is distributed in the hope that it will be useful, but --
-- WITHOUT ANY WARRANTY without even the implied warranty of MERCHANTABILITY --
-- or FITNESS FOR A PARTICULAR PURPOSE. See Doc/LGPL for more details. --
-- The license text is also available from: Free Software Foundation, Inc., --
-- 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA --
--------------> Please email comments to <bug-sather@gnu.org> <--------------
abstract class $FILE_CURSORS
abstract class $FILE_CURSORS is
-- This is the class abstraction which provides for buffered
-- input/output for very large files which it is impractical to read into
-- the system all at once.
--
-- The common operations all relate to cursor positioning rather than
-- the input/output actions which are necessarily specialised for text and
-- binary objects.
-- Version 1.1 Oct 98. Copyright K Hopper, U of Waikato
-- Development History
-- -------------------
-- Date Who By Detail
-- ---- ------ ------
-- 9 Apr 97 kh Original
-- 26 Oct 98 kh Improved portability
position : CARD ;
position(
at : CARD
) : SAME ;
-- This pair provide a facility to set the cursor at an absolute position
-- in the file and to discover its current position.
forward(
cnt : CARD
) : SAME ;
-- This routine returns the cursor which has moved forward by the
-- given number of octets in the file -- unless that position does not exist!
skip(
cnt : CARD
) : SAME ;
-- This is the same as forward.
backward(
cnt : CARD
) : SAME ;
-- This routine returns the cursor which has moved backward by the
-- given number of octets in the file -- unless that is before the beginning!
size : CARD ;
-- This is a convenience routine for use when manipulating file contents.
-- It provides the same value as may be found from the FILE_LABEL!
readable : BOOL ;
writable : BOOL ;
-- These two features reflect the value of the associated file features.
at_end : BOOL ;
-- This returns true iff the cursor is positioned after the last octet
-- in the file, otherwise false.
error : BOOL ;
-- This returns true if an error has occurred since the last use of the
-- clear routine (or since object creation)!
error_message : STR ;
-- Provided that error would return true, this routine returns an
-- appropriate error message, otherwise void.
clear ;
-- This routine clears any error condition for the cursor and associated
-- file.
end ; -- $FILE_CURSORS
abstract class $FILE_CURSORS{ETP < $IS_EQ, STP < $STRING{ETP}}
abstract class $FILE_CURSORS{ETP < $IS_EQ, STP < $STRING{ETP}}
< $FILE_CURSORS is
-- This class abstraction defines buffered output features for very
-- large files which it is impractical to read into the system all at once.
-- Version 1.0 Nov 2000. Copyright K Hopper, U of Waikato
-- Development History
-- -------------------
-- Date Who By Detail
-- ---- ------ ------
-- 18 Nov 00 kh Original
end ; -- $FILE_CURSORS{ETP,STP}
partial class FILE_CURSOR{KIND, BUFF < $FSTRINGS} < $FILE_CURSORS
partial class FILE_CURSOR{KIND, BUFF < $FSTRINGS} < $FILE_CURSORS is
-- This class embodies the common file cursor attributes and operations.
-- variant specific operations are provided by each variant.
--
-- NOTE Positioning operations on the underlying file are only carried out
-- when it is necessary to conduct input/output activity!
-- Version 1.2 Oct 98. Copyright K Hopper, U of Waikato
-- Development History
-- -------------------
-- Date Who By Detail
-- ---- ------ ------
-- 9 Apr 97 kh Original
-- 21 Oct 98 kh Improved portability and added pre/posts
readonly attr position : CARD ; -- file position
private attr buffer : BUFF ;
private attr buff_position : CARD ;
private attr buff_contents : CARD ;
private attr buff_length : CARD ;
private attr buff_valid : BOOL ; -- the buffer contents may be used
private attr buff_altered : BOOL ; -- needs writing back!
private attr index : CARD ; -- from the beginning of buffer.
private attr fyle : REFERENCE ; -- the OS file handle!
readonly attr readable : BOOL ;
readonly attr writable : BOOL ;
create(
handle : REFERENCE,
buff_size : CARD,
rd,
wr : BOOL
) : SAME
pre ~void(handle)
and (buff_size % 4 = 0) -- to avoid character code across boundary!
post ~void(result)
is
-- THIS ROUTINE IS NOT FOR DIRECT USE -- IT IS ONLY FOR USE BY AN
-- OBJECT OF THE BIN_FILE CLASS!!!
--
-- This routine establishes a new buffer for the specified file. It
-- does NOT fill the buffer until an actual input/output operation is
-- required!
me : SAME := new ;
me.fyle := handle ;
me.buffer := BUFF::create(buff_size) ;
me.position := void ;
me.buff_position := void ;
me.buff_length := buff_size ;
me.buff_valid := false ;
me.buff_altered := false ;
me.index := 0 ;
me.writable := wr ;
me.readable := rd ;
return me
end ;
position(
at : CARD
) : SAME
pre ~void(self)
and (at < size)
post true
is
-- This routine sets the cursor at the given absolute position
-- in the file and returns the altered cursor.
position := at ;
return self
end ;
forward(
cnt : CARD
) : SAME
pre ~void(self)
and ((cnt + position) < size)
post (position = (initial(position) + cnt))
is
-- This routine returns the cursor which has moved forward by the
-- given number of octets in the file.
position := position + cnt ;
return self
end ;
skip(
cnt : CARD
) : SAME
pre ~void(self)
and ((cnt + position) < size)
post (position = (initial(position) + cnt))
is
-- This is the merely a renaming of forward above.
return forward(cnt)
end ;
backward(
cnt : CARD
) : SAME
pre ~void(self)
and (cnt <= position)
post (position = (initial(position) - cnt))
is
-- This routine returns the cursor which has moved backward by the
-- given number of octets in the file.
position := position - cnt ;
return self
end ;
size : CARD
pre ~void(self)
and ~void(fyle)
post true
is
-- This is a convenience routine for use when manipulating file contents.
-- It provides the same value as may be found from the FILE_LABEL.
res : CARD ;
if FILE_SYS::size(fyle,out res) then
return res
else -- Oops! file problem - return null
return CARD::nil
end
end ;
private emptybuff
pre ~void(self)
post ~buff_altered
is
-- Provided that the buffer contents has been altered previously
-- then its contents are written to the file. No change is made to
-- position since it always correctly reflects the file position.
if buff_altered then -- something to do!
if ~FILE_SYS::seek(fyle,buff_position.int,FILE_LOCS::Beginning) then
SYS_ERROR::create.error(self,SYS_EXCEPT::Bad_Value,
FILE_LOCS::Beginning.str +
LIBCHARS::default.Plus_Sign.char + buff_position.str)
end ;
if ~FILE_SYS::file_write(buffer.array_ptr,1,
inout buff_contents,fyle) then
error := true ;
return -- nothing has been done!
end ;
buff_altered := false
end
end ;
private fillbuff
pre true
post buff_valid and (index = 0) and (buff_position = position)
is
-- If the current buffer contents has been altered then this routine
-- first empties it, then refills from the current file position, resetting
-- index, buff_position, buff_contents, buff_valid in doing so.
if buff_altered then emptybuff; end ;
if ~FILE_SYS::seek(fyle,position.int,FILE_LOCS::Beginning) then
SYS_ERROR::create.error(self,SYS_EXCEPT::Bad_Value,
FILE_LOCS::Beginning.str + LIBCHARS::default.Plus_Sign.char + buff_position.str);
end ;
buff_contents := buff_length ;
if ~FILE_SYS::file_read(buffer,1,inout buff_contents,fyle) then
error := true ;
return
end ;
buffer.loc := buff_contents ;
buff_position := position ;
index := 0 ;
buff_valid := true;
end ;
at_end : BOOL is
-- This predicate returns true if and only if the cursor is positioned
-- after the last octet in the file, otherwise false.
return (position = size)
end ;
readonly attr error : BOOL ;
-- This returns true if an error has occurred since the last use of the
-- clear routine (or since object creation)!
error_message : STR
pre true
post (error and void(result))
or (result.size > 0)
is
-- Provided that error would return true, this routine returns an
-- appropriate error message, otherwise void.
if error then
return FILE_SYS::error_msg(fyle)
else
return void
end
end ;
clear
pre true
post ~error
is
-- This routine clears any error condition for the cursor and associated
-- file.
error := false ;
FILE_SYS::clearerr(fyle)
end ;
flush
pre true
post ~buff_altered
is
-- This routine ensures that the file contents accurately reflect
-- any altered buffer. This should be used before closing the file
-- when any writing has been done.
if buff_altered then emptybuff end
end ;
close
pre ~void(self) and ~void(fyle)
post void(fyle)
is
-- This routine closes the file, having flushed any buffers and
-- makes this object invalid as a file object.
FILE_SYS::close(fyle) ;
readable := false ;
writable := false ;
fyle := void
end ;
end ; -- FILE_CURSOR