gcc/m2/gm2-libs-iso/MemStream.def

   1 (* MemStream.def provide a memory stream channel.
   2
   3 Copyright (C) 2015-2023 Free Software Foundation, Inc.
   4 Contributed by Gaius Mulley <gaius.mulley@southwales.ac.uk>.
   5
   6 This file is part of GNU Modula-2.
   7
   8 GNU Modula-2 is free software; you can redistribute it and/or modify
   9 it under the terms of the GNU General Public License as published by
  10 the Free Software Foundation; either version 3, or (at your option)
  11 any later version.
  12
  13 GNU Modula-2 is distributed in the hope that it will be useful, but
  14 WITHOUT ANY WARRANTY; without even the implied warranty of
  15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16 General Public License for more details.
  17
  18 Under Section 7 of GPL version 3, you are granted additional
  19 permissions described in the GCC Runtime Library Exception, version
  20 3.1, as published by the Free Software Foundation.
  21
  22 You should have received a copy of the GNU General Public License and
  23 a copy of the GCC Runtime Library Exception along with this program;
  24 see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
  25 <http://www.gnu.org/licenses/>.  *)
  26
  27 DEFINITION MODULE MemStream ;
  28
  29 (*
  30     Title      : MemStream
  31     Author     : Gaius Mulley
  32     System     : GNU Modula-2
  33     Date       : Wed Jan 28 16:44:30 2015
  34     Revision   : $Version$
  35     Description: provides an ISO module which can write to a memory
  36                  buffer or read from a memory buffer.
  37 *)
  38
  39 FROM IOChan IMPORT ChanId ;
  40 FROM ChanConsts IMPORT FlagSet, OpenResults ;
  41 FROM SYSTEM IMPORT ADDRESS, LOC ;
  42
  43
  44 (*
  45    Attempts to obtain and open a channel connected to a contigeous
  46    buffer in memory.  The write flag is implied; without the raw
  47    flag, text is implied.  If successful, assigns to cid the identity of
  48    the opened channel, assigns the value opened to res.
  49    If a channel cannot be opened as required,
  50    the value of res indicates the reason, and cid identifies the
  51    invalid channel.
  52
  53    The parameters, buffer, length and used maybe updated as
  54    data is written.  The buffer maybe reallocated
  55    and its address might alter, however the parameters will
  56    always reflect the current active buffer.  When this
  57    channel is closed the buffer is deallocated and
  58    buffer will be set to NIL, length and used will be set to
  59    zero.
  60 *)
  61
  62 PROCEDURE OpenWrite (VAR cid: ChanId; flags: FlagSet;
  63                      VAR res: OpenResults;
  64                      VAR buffer: ADDRESS;
  65                      VAR length: CARDINAL;
  66                      VAR used: CARDINAL;
  67                      deallocOnClose: BOOLEAN) ;
  68
  69
  70 (*
  71    Attempts to obtain and open a channel connected to a contigeous
  72    buffer in memory.  The read and old flags are implied; without
  73    the raw flag, text is implied.  If successful, assigns to cid the
  74    identity of the opened channel, assigns the value opened to res, and
  75    selects input mode, with the read position corresponding to the start
  76    of the buffer.  If a channel cannot be opened as required, the value of
  77    res indicates the reason, and cid identifies the invalid channel.
  78 *)
  79
  80 PROCEDURE OpenRead (VAR cid: ChanId; flags: FlagSet;
  81                     VAR res: OpenResults;
  82                     buffer: ADDRESS; length: CARDINAL;
  83                     deallocOnClose: BOOLEAN) ;
  84
  85
  86 (*
  87    Close - if the channel identified by cid is not open to
  88            a memory stream, the exception wrongDevice is
  89            raised; otherwise closes the channel, and assigns
  90            the value identifying the invalid channel to cid.
  91 *)
  92
  93 PROCEDURE Close (VAR cid: ChanId) ;
  94
  95
  96 (*
  97    Rewrite - assigns the buffer index to zero.  Subsequent
  98              writes will overwrite the previous buffer contents.
  99 *)
 100
 101 PROCEDURE Rewrite (cid: ChanId) ;
 102
 103
 104 (*
 105    Reread - assigns the buffer index to zero.  Subsequent
 106             reads will read the previous buffer contents.
 107 *)
 108
 109 PROCEDURE Reread (cid: ChanId) ;
 110
 111
 112 (*
 113    IsMem - tests if the channel identified by cid is open as
 114            a memory stream.
 115 *)
 116
 117 PROCEDURE IsMem (cid: ChanId) : BOOLEAN ;
 118
 119
 120 END MemStream.