add %visit method()

Co-authored-by: 14NGiestas <14NGiestas@users.noreply.github.com>

Author: scivision

API.md

@@ -294,6 +294,30 @@ character(*), intent(in) :: dname, attr  !< dataset name, attribute name
 class(*), intent(out) :: attrval(:)  !< character, real, integer
 ```
 
+## Iterate over all datasets in a group
+
+```fortran
+call h%iterate(group, callback)
+character(*), intent(in) :: group
+subroutine callback(group_name, object_name, object_type)
+  character(len=*), intent(in) :: group_name
+  character(len=*), intent(in) :: object_name
+  character(len=*), intent(in) :: object_type
+end subroutine
+```
+
+## Visit recursively all datasets starting from a group
+
+```fortran
+call h%visit(group, callback)
+character(*), intent(in) :: group
+subroutine callback(group_name, object_name, object_type)
+  character(len=*), intent(in) :: group_name
+  character(len=*), intent(in) :: object_name
+  character(len=*), intent(in) :: object_type
+end subroutine
+```
+
 ## delete attribute
 
 ```fortran

fpm.toml

@@ -77,3 +77,11 @@ main = "test_string.f90"
 [[test]]
 name = "version"
 main = "test_version.f90"
+
+[[test]]
+name = "visit"
+main = "test_visit.f90"
+
+[[test]]
+name = "iterate"
+main = "test_iterate.f90"

src/CMakeLists.txt

@@ -2,7 +2,7 @@ set(s ${CMAKE_CURRENT_SOURCE_DIR})
 
 target_sources(h5fortran PRIVATE
 ${s}/utils.f90 ${s}/datatype.f90 ${s}/deflate.f90
-${s}/iterate.f90
+${s}/iterate.f90 ${s}/visit.f90
 ${s}/read.f90 ${s}/read_scalar.f90 ${s}/read_ascii.f90 ${s}/reader.f90
 ${s}/write.f90 ${s}/write_scalar.f90 ${s}/writer.f90
 ${s}/reader_lt.f90 ${s}/writer_lt.f90

src/interface.f90

@@ -57,7 +57,7 @@ module h5fortran
 procedure, public :: delete_attr => attr_delete
 procedure, public :: exist_attr => attr_exist
 procedure, public :: iterate => hdf_iterate
-
+procedure, public :: visit => hdf_visit
 !! procedures without mapping
 
 !> below are procedure that need generic mapping (type or rank agnostic)
@@ -803,6 +803,34 @@ subroutine user_callback_interface(group_name, object_name, object_type)
  procedure(user_callback_interface) :: callback
 end subroutine
 
+
+module subroutine hdf_visit(self, group_name, callback)
+ !! Opens the HDF5 file and the specified group, then visits recursively
+ !! all members of the group. For each member the user‐provided
+ !! callback is invoked with:
+ !!
+ !!   self - the HDF5 file object
+ !!   group_name - name of the group
+ !!   object_name - name of the member object
+ !!   object_type - a short string indicating type ("group", "dataset",
+ !!                 "datatype", or "other")
+ class(hdf5_file), intent(in) :: self
+ character(len=*), intent(in) :: group_name
+  interface
+    subroutine user_callback_interface(group_name, object_name, object_type)
+      character(len=*), intent(in) :: group_name
+        !! The name of the group being traversed.
+      character(len=*), intent(in) :: object_name
+        !! The name of the object encountered.
+      character(len=*), intent(in) :: object_type
+        !!A short description such as "group", "dataset",
+        !!                            "datatype", or "other"
+    end subroutine
+  end interface
+
+ procedure(user_callback_interface) :: callback
+end subroutine
+
 end interface
 
 

src/visit.f90

@@ -0,0 +1,116 @@
+submodule (h5fortran:hdf5_read) visit_smod
+  use, intrinsic :: iso_c_binding, only : c_long, c_char, c_funloc, c_int, c_funptr, c_null_ptr, C_associated
+  use hdf5, only : h5l_info_t, h5o_info_t, H5O_TYPE_DATASET_F, H5O_TYPE_GROUP_F, &
+                   H5O_TYPE_NAMED_DATATYPE_F, H5O_TYPE_UNKNOWN_F, &
+                   H5_INDEX_NAME_F, H5_ITER_NATIVE_F, &
+                   H5Gopen_f, H5Gclose_f, H5Oget_info_by_name_f, &
+                   H5Ovisit_f
+
+  implicit none
+
+  interface
+    subroutine user_callback_interface(group_name, object_name, object_type)
+      character(*), intent(in) :: group_name
+        !! The name of the group being traversed.
+      character(*), intent(in) :: object_name
+        !! The name of the object encountered.
+      character(*), intent(in) :: object_type
+        !!A short description such as "group", "dataset",
+        !!                            "datatype", or "other"
+    end subroutine
+  end interface
+
+  type :: visit_data_t
+     procedure(user_callback_interface), nopass, pointer :: callback => null()
+  end type visit_data_t
+
+contains
+
+  module procedure hdf_visit
+    integer(hid_t) :: group_id
+    integer(c_int) :: status
+    integer(hsize_t) :: idx
+    type(c_funptr) :: funptr
+    type(c_ptr) :: op_data_ptr
+    integer(c_int) :: return_value
+
+    type(visit_data_t) :: data
+
+    ! Fill the iteration data with the user’s group name and callback.
+    data % callback => callback
+
+    ! Open the group.
+    call H5Gopen_f(self%file_id, trim(group_name), group_id, status)
+    call estop(status, "hdf_visit:H5Gopen_f", self%filename, "Error opening group: " // trim(group_name))
+
+    idx = 0
+    op_data_ptr = C_NULL_PTR
+    ! Get the C function pointer for our internal callback.
+    funptr = c_funloc(internal_visit_callback)
+
+    ! Call H5Lvisit_f to visit over the group.
+    call H5Ovisit_f(group_id, H5_INDEX_NAME_F, H5_ITER_NATIVE_F, &
+                      funptr, op_data_ptr, return_value, status)
+    call estop(status, "hdf_visit:H5Lvisit_f", self%filename, "Error during iteration of group: " // trim(group_name))
+
+    ! Close the group and file.
+    call H5Gclose_f(group_id, status)
+
+  contains
+
+    integer(c_int) function internal_visit_callback(grp_id, name, info, op_data) bind(C)
+      !!  internal_visit_callback:
+      !!
+      !!  This is the callback procedure that will be passed to H5Lvisit_f.
+      !!  It matches HDF5’s expected signature (using bind(C)) and is called
+      !!  for each object in the group.
+      !!
+      !!  It extracts the object name from the provided character array,
+      !!  calls H5Oget_info_by_name_f to determine the object type, and then
+      !!  calls the user's callback with the high-level parameters.
+      integer(c_long), intent(in), value        :: grp_id
+      character(1, kind=c_char), intent(in) :: name(0:255)
+      type(h5l_info_t), intent(in)              :: info
+      type(c_ptr), intent(in)                   :: op_data
+
+      integer :: status, i, len
+      type(H5O_info_t) :: infobuf
+      character(256) :: name_string
+      character(:), allocatable :: object_type
+
+      ! avoid unused argument warning
+      if (C_associated(op_data) .and. info % corder == 0) i = 0
+
+      ! Build a Fortran string from the character array.
+      do i = 0, 255
+        len = i
+        if (name(i) == c_null_char) exit
+        name_string(i+1:i+1) = name(i)(1:1)
+      end do
+
+      ! Retrieve object info using the object name.
+      call H5Oget_info_by_name_f(grp_id, name_string(1:len), infobuf, status)
+      if (status /= 0) then
+        internal_visit_callback = status
+        return
+      end if
+
+      if(infobuf % type == H5O_TYPE_GROUP_F)then
+        object_type = "group"
+      else if(infobuf % type == H5O_TYPE_DATASET_F)then
+        object_type = "dataset"
+      else if(infobuf % type == H5O_TYPE_NAMED_DATATYPE_F)then
+        object_type = "datatype"
+      else
+        object_type = "other"
+      endif
+
+      ! Call the user’s callback procedure.
+      call data % callback(group_name, name_string(1:len), object_type)
+
+      internal_visit_callback = 0  ! Indicate success.
+    end function internal_visit_callback
+
+  end procedure hdf_visit
+
+end submodule

test/CMakeLists.txt

@@ -59,7 +59,7 @@ endfunction(setup_test)
 
 set(test_names array attributes attributes_read
 cast deflate_write deflate_read deflate_props destructor exist
-groups iterate layout lt scalar shape string string_read version write
+groups iterate layout lt scalar shape string string_read version visit write
 fail_read_size_mismatch fail_read_rank_mismatch fail_nonexist_variable)
 if(HAVE_IEEE_ARITH)
   list(APPEND test_names fill)

test/test_visit.f90

@@ -0,0 +1,47 @@
+program test_visit
+
+  use, intrinsic :: iso_fortran_env, only: real64
+  use h5fortran, only: hdf5_file
+
+  implicit none
+
+  type(hdf5_file) :: h
+  character(*), parameter :: filename='test_visit.h5'
+  integer :: i = 0
+
+  ! Create a sample HDF5 file
+  call h%open(filename, "w")
+
+  call h%create_group("/group1")
+  call h%create_group("/group1/group2")
+  call h%write("/dataset1", 1.0_real64)
+  call h%write("/group1/dataset2", 2.0_real64)
+
+  call h%close()
+
+  ! Reopen the file for testing
+  call h%open(filename, "r")
+
+  ! visit the root group
+  print '(a)', "test_visit: visiting root group"
+  call h%visit("/", my_callback)
+
+  print '(a)', "test_visit: visiting /group1"
+  ! visit a subgroup
+  call h%visit("/group1", my_callback)
+
+  call h%close()
+
+  print '(a,i0,a)', "test_visit: found ", i, " objects"
+  if (i /= 8) error stop "test_visit: expected 8 objects"
+
+contains
+
+  ! Define a callback subroutine
+  subroutine my_callback(group_name, object_name, object_type)
+    character(*), intent(in) :: group_name, object_name, object_type
+    print '(6a)', "test_visit: at group ", trim(group_name), ' we found ', trim(object_name), ' that is a ', trim(object_type)
+    i = i + 1
+  end subroutine my_callback
+
+end program test_visit