[Chicken-users] on HDF4 support for Chicken

[Ivan Shmakov]

       I'm currently working on implementing HDF4 [1] support for
       Chicken.  Essentially, an HDF4 file is a sort of archive,
       consisting of a number of (annotated) arbitrary rank arrays,
       called scientific data sets (SDS) in HDF's own terminology.

       While the data sets contained in an HDF4 file could be saved to
       the raw data files (using, e. g., hdp [2] or hdfdump [3]) and
       read later using the facilities already provided by Chicken, it
       would be much more convenient to have the functions to manage
       HDF4 files directly.

       The source (alpha-quality currently) could be downloaded from
       [4].  I'll appreciate any suggestions (better with the code.)

       So far, the implementation basically wraps over the SD interface
       provided by the HDF4 library.  The interface implemented is
       currently roughly as follows:

   (hdf4-sd? OBJECT)

       Return #t if the object is a valid (non-closed) HDF4 SD
       (``file'') object.  Return #f otherwise.

   (hdf4-sd-open FILE ACCESS-MODE)

       Open an HDF4 file and return a new HDF4 SD (``file'') object
       associated with it.  It's an error for the given file to not
       exists, be inaccessible, or to be in a format different to HDF4.

   (hdf4-sd-close SD)

       Close the HDF4 file associated with SD.  Further operations on a
       given SD object will signal an error, with the expection of the
       `hdf4-sd-close' operation itself, which will be no-op.  The
       value returned is unspecified.

   (hdf4-sd-info SD)

       Return two values: the number of data sets and the number of
       global attributes contained in the HDF4 file associated with SD,
       respectively.

   (hdf4-sd-lookup SD SDS-NAME)

       Return the index of the SDS contained in the HDF4 file
       associated with SD under the name SDS-NAME, or #f if no such SDS
       exists.

   (hdf4-sds? SDS)

       Return #t if the object is a valid (non-closed) HDF4 SDS
       (``array'') object.  Return #f otherwise.

   (hdf4-sds-open SD NAME-OR-INDEX)

       Open an HDF4 data set contained within the HDF4 file associated
       with SD under the name (string) or index (integer)
       NAME-OR-INDEX.  Return a new HDF4 SDS (``array'') object
       associated with the SDS opened.

   (hdf4-sds-close SDS)

       Close the HDF4 data set associated with SDS.  Further operations
       on a given SDS object will signal an error, with the expection
       of the `hdf4-sds-close' operation itself, which will be no-op.
       The value returned is unspecified.

   (hdf4-sds-create SD NAME DATA-TYPE DIMENSIONS)

       Create a new HDF4 data set within the HDF4 file associated with
       SD.  The data set created is assigned NAME, DATA-TYPE and a
       vector of DIMENSIONS.  The latter must be an SRFI-4 [5]
       s32vector, or an R5RS vector convertible to one, or an error
       will be signalled.  It's an error to to specify a NAME which
       already exists within the HDF4 file, or to specify an invalid
       DATA-TYPE, or to specify non-positive values in the DIMENSIONS
       vector.

   (hdf4-sds-info SDS)

       Return four values: name, the vector of dimensions, data type
       and the number of attributes for the HDF4 data set associated
       with SDS.  The dimensions is returned as an SRFI-4 s32vector.

   (hdf4-sds-slab-get SDS ORIGIN STRIDE COUNTS)
   (hdf4-sds-slab-get SDS ORIGIN STRIDE COUNTS BUFFER)

       Read a part of the HDF4 data set associated with SDS to a
       buffer.  The part specification is as follows (where RANK is the
       number of dimensions of the data set):

       * ORIGIN -- a vector or SRFI-4 s32vector of RANK non-negative
         integers specifying the origin of the part to be read, or #f,
         meaning a vector of all zeros;

       * STRIDE -- a vector or SRFI-4 s32vector of RANK positive
         integers specifying the ``steps'' to be made along each of the
         dimensions, or #f, meaning a vector of all ones;

       * COUNTS -- a vector or SRFI-4 s32vector of RANK positive
         integers specifying the number of elements to be read along
         each of the dimensions.

       E. g.:

     (hdf4-sds-slab-get sds #f #f #(5))
         => the elements 0 .. 4 of the data set;

     (hdf4-sds-slab-get sds '#(1) '#(2) #(3))
         => the elements 1, 3, 5 of the data set.

       If the BUFFER (SRFI-4 vector) is specified, it is used to store
       the data, otherwise a new suitable buffer is allocated.  It's an
       error for BUFFER to be of a different type to the SDS data type,
       or to consist of less elements than specified by COUNTS.

       The SRFI-4 vector holding the data is returned, or #f if the
       reading was unsuccessful.

   (hdf4-sds-slab-put SDS ORIGIN STRIDE COUNTS BUFFER)

       Write to a part of the HDF4 data set associated with SDS to a
       buffer.  The part specification is the same as for
       `hdf4-sds-slab-get'.

       It's an error for BUFFER to be of a different type to the SDS
       data type, or to consist of less elements than specified by
       COUNTS.

[1] http://www.hdfgroup.org/hdf4.html
[2] http://www.hdfgroup.org/hdp.html
[3] http://theory.asu.ru/~ivan/devel/hdfdump/
[4] http://theory.asu.ru/~ivan/devel/chicken/libhdf4-chicken-pre-0.1.tar.gz
[5] http://srfi.schemers.org/srfi-4/srfi-4.html