13.3 Binfile Interface

ORIGIN '~beta/basiclib/file';
LIB_DEF 'binfile' '../lib';
BODY 'private/binfilebody';

(* binfile:
 *   These fragments declare attributes for direct reading/writing 
 *   of various data sizes to a file. The data is written out exactly
 *   as is:
 *      64 -> aBinFile.putLong 
 *   will write the number 0x00000020 to aBinFile, whereas 
 *      64 -> aBinFile.putInt
 *   will write the two characters '6' (ascii 54) and '4' (ascii 52)
 *   to the file.
 * 
 *   The operations putBytes and getBytes allow an arbitrary
 *   sequence of bytes to be written/read to/from a file.
 *   E.g. 
 *      buffer: [1000]@char;
 *      putB: @aFile.putBytes;
 *   do ...
 *      (@@buffer[1],500) -> putB;
 *   This will write the first 500 characters from the buffer
 *   repetition to the file. NOTICE, that you must have a static
 *   instance of putBytes/getBytes when using them, since they require
 *   an address argument. If dynamic instances are used, a garbage-
 *   collection may be triggered, and the address argument would be
 *   illegal.
 * 
 *   These operations are declared in FileLib, e.g. they become
 *   usable for any file, by just including this fragment file.
 *   However, on some platforms, the "binary" virtual of File
 *   MUST be further bound to TrueObject for these operations
 *   to work. The binfile pattern below adds this further binding.
 * 
 *   You should remember this further binding if you are using 
 *   these operations on a file, that is not a binfile.
 * 
 *   Exceptions: 
 *   If any of the put-operations fail, they raise the WriteError 
 *   file-exception. If any of the get-operations fail, they raise 
 *   the ReadError file-exception.
 *)

-- LIB: attributes --

binfile: file
  (# <<SLOT BinFileLib: attributes>>;
     binary :: trueobject
  #);

-- FileLib: attributes --
putdouble: 
  (* Write binary representation of i (8 bytes) to file *)
  (# i: @real;
  enter i
  ...
  #);
putlong: 
  (* Write binary representation of i (4 bytes) to file *)
  (# i: @integer;
  enter i
  ...
  #);
putshort: 
  (* Write binary representation of i (2 bytes) to file *)
  (# i: @int16;
  enter i
  ...
  #);
putbyte: 
  (* Write binary representation of i (1 byte) to file *)
  (# i: @char;
  enter i
  ...
  #);
getDouble:
  (* Read binary representation of i (8 bytes) from file *)
  (# i: @real;
  ...
  exit i
  #);
getLong:
  (* Read binary representation of i (4 bytes) from file *)
  (# i: @integer;
  ...
  exit i
  #);
getShort:
  (* Read binary representation of i (2 bytes) from file *)
  (# i: @int16;
  ...
  exit i
  #);
getByte:
  (* Read binary representation of i (1 byte) from file *)
  (# i: @char;
  ...
  exit i
  #);

putBytes:
  (* Write num bytes to file from memory
   * starting at address addr.
   *)
  (# addr, num: @integer;
  enter (addr, num)
  ...
  #);
getBytes:
  (* Read in num bytes from file to memory
   * starting at address addr.
   *)
  (# addr, num: @integer;
  enter (addr, num)
  ...
  #)