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
  #);

putCharRep:
  (* Write num chars from R[1]..R[num] to file *)
  (# R: [0] @char;
     num: @integer;
  enter (R[], num)
  ...
  #);
getCharRep:
  (* Read num chars from file into a new repetition.
   * 'extra' can be used to preallocated that number of
   * chars at the end og the repetition during the same 
   * operation.
    *)
  (# R: [0] @char;
     num, extra: @integer;
  enter (num, extra)
  ...
  exit R[]
  #);

(* Put and get of repetitions of SIGNED elements 
 * using repetition references
 *)
putInt8Rep:
  (* Write num int8 from R[1]..R[num] to file *)
  (# R: [0] @int8;
     num: @integer;
  enter (R[], num)
  ...
  #);
getInt8Rep:
  (* Read num int8 from file into a new repetition.
   * 'extra' can be used to preallocated that number of
   * int8 at the end og the repetition during the same 
   * operation.
    *)
  (# R: [0] @int8;
     num, extra: @integer;
  enter (num, extra)
  ...
  exit R[]
  #);
putInt16Rep:
  (* Write num int16s from R[1]..R[num] to file *)
  (# R: [0] @int16;
     num: @integer;
  enter (R[], num)
  ...
  #);
getInt16Rep:
  (* Read num int16s from file into a new repetition.
   * 'extra' can be used to preallocated that number of
   * int16s at the end og the repetition during the same 
   * operation.
   *)
  (# R: [0] @int16;
     num, extra: @integer;
  enter (num, extra)
  ...
  exit R[]
  #);
putInt32Rep:
  (* Write num int32s from R[1]..R[num] to file *)
  (# R: [0] @int32;
     num: @integer;
  enter (R[], num)
  ...
  #);
getInt32Rep:
  (* Read num int32s from file into a new repetition.
   * 'extra' can be used to preallocated that number of
   * int32s at the end og the repetition during the same 
   * operation.
   *)
  (# R: [0] @int32;
     num, extra: @integer;
  enter (num, extra)
  ...
  exit R[]
  #);

(* Put and get of repetitions of UNSIGNED elements 
 * using repetition references
 *)
putInt8uRep:
  (* Write num int8u from R[1]..R[num] to file *)
  (# R: [0] @int8u;
     num: @integer;
  enter (R[], num)
  ...
  #);
getInt8uRep:
  (* Read num int8u from file into a new repetition.
   * 'extra' can be used to preallocated that number of
   * int8 at the end og the repetition during the same 
   * operation.
    *)
  (# R: [0] @int8u;
     num, extra: @integer;
  enter (num, extra)
  ...
  exit R[]
  #);
putInt16uRep:
  (* Write num int16u from R[1]..R[num] to file *)
  (# R: [0] @int16u;
     num: @integer;
  enter (R[], num)
  ...
  #);
getInt16uRep:
  (* Read num int16u from file into a new repetition.
   * 'extra' can be used to preallocated that number of
   * int16s at the end og the repetition during the same 
   * operation.
   *)
  (# R: [0] @int16u;
     num, extra: @integer;
  enter (num, extra)
  ...
  exit R[]
  #);
putInt32uRep:
  (* Write num int32u from R[1]..R[num] to file *)
  (# R: [0] @int32u;
     num: @integer;
  enter (R[], num)
  ...
  #);
getInt32uRep:
  (* Read num int32u from file into a new repetition.
   * 'extra' can be used to preallocated that number of
   * int32s at the end og the repetition during the same 
   * operation.
   *)
  (# R: [0] @int32u;
     num, extra: @integer;
  enter (num, extra)
  ...
  exit R[]
  #);

(* Unsafe operations retained for backward compatibility *)

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)
  ...
  #)