allow keyword args to open_group, open_dataset, open_datatype (#1100)

* allow keyword args to open_group, open_dataset, open_datatype * Update groups.jl Co-authored-by: Mark Kittisopikul <mkitti@users.noreply.github.com> * Update groups.jl Co-authored-by: Mark Kittisopikul <mkitti@users.noreply.github.com> * add missing docs --------- Co-authored-by: Mark Kittisopikul <mkitti@users.noreply.github.com>
JuliaIO · Sep 1, 2023 · 5b15f5e · 5b15f5e
1 parent 4357231
commit 5b15f5e
Show file tree

Hide file tree

Showing 7 changed files with 56 additions and 21 deletions.
diff --git a/docs/src/interface/datatype.md b/docs/src/interface/datatype.md
@@ -6,4 +6,5 @@ CurrentModule = HDF5
 
 ```@docs
 Datatype
+open_datatype
 ```
diff --git a/docs/src/interface/properties.md b/docs/src/interface/properties.md
@@ -25,9 +25,11 @@ setproperties!
 AttributeCreateProperties
 FileAccessProperties
 FileCreateProperties
+GroupAccessProperties
 GroupCreateProperties
 DatasetCreateProperties
 DatasetAccessProperties
+DatatypeAccessProperties
 DatasetTransferProperties
 LinkCreateProperties
 ObjectCreateProperties

diff --git a/src/datasets.jl b/src/datasets.jl
@@ -4,18 +4,28 @@
 dataspace(dset::Dataset) = Dataspace(API.h5d_get_space(checkvalid(dset)))
 
 """
- open_dataset(parent::Union{File, Group}, name::AbstractString, [dapl, dxpl])
+ open_dataset(parent::Union{File, Group}, path::AbstractString; properties...)
 
-Open a dataset and return a [`HDF5.Dataset`](@ref) handle. Alternatively , just use index
-a file or group with `name`.
+Open an existing [`HDF5.Dataset`](@ref) at `path` under `parent`
+
+Optional keyword arguments include any keywords that that belong to
+[`DatasetAccessProperties`](@ref) or [`DatasetTransferProperties`](@ref).
 """
 open_dataset(
  parent::Union{File,Group},
  name::AbstractString,
- dapl::DatasetAccessProperties=DatasetAccessProperties(),
- dxpl::DatasetTransferProperties=DatasetTransferProperties()
+ dapl::DatasetAccessProperties,
+ dxpl::DatasetTransferProperties
 ) = Dataset(API.h5d_open(checkvalid(parent), name, dapl), file(parent), dxpl)
 
+function open_dataset(parent::Union{File,Group}, name::AbstractString; pv...)
+ dapl = DatasetAccessProperties()
+ dxpl = DatasetTransferProperties()
+ pv = setproperties!(dapl, dxpl; pv...)
+ isempty(pv) || error("invalid keyword options $(keys(pv))")
+ open_dataset(parent, name, dapl, dxpl)
+end
+
 # Setting dset creation properties with name/value pairs
 """
  create_dataset(parent, path, datatype, dataspace; properties...)

diff --git a/src/datatypes.jl b/src/datatypes.jl
@@ -12,11 +12,22 @@ end
 datatype(dt::Datatype) = dt
 
 open_datatype(
- parent::Union{File,Group},
- name::AbstractString,
- tapl::DatatypeAccessProperties=DatatypeAccessProperties()
+ parent::Union{File,Group}, name::AbstractString, tapl::DatatypeAccessProperties
 ) = Datatype(API.h5t_open(checkvalid(parent), name, tapl), file(parent))
 
+"""
+ open_datatype(parent::Union{File,Group}, path::AbstractString; properties...)
+
+Open an existing [`Datatype`](@ref) at `path` under the `parent` object.
+
+Optional keyword arguments include any keywords that that belong to
+[`DatatypeAccessProperties`](@ref).
+"""
+function open_datatype(parent::Union{File,Group}, name::AbstractString; pv...)
+ tapl = DatatypeAccessProperties(; pv...)
+ return open_datatype(parent, name, tapl)
+end
+
 # Note that H5Tcreate is very different; H5Tcommit is the analog of these others
 create_datatype(class_id, sz) = Datatype(API.h5t_create(class_id, sz))
 

diff --git a/src/groups.jl b/src/groups.jl
@@ -50,17 +50,22 @@ function create_group(parent::Union{File,Group}, path::AbstractString; pv...)
 end
 
 """
- open_group(parent::Union{File,Group}, path::AbstratString)
+ open_group(parent::Union{File,Group}, path::AbstractString; properties...)
 
 Open an existing [`Group`](@ref) at `path` under the `parent` object.
+
+Optional keyword arguments include any keywords that that belong to
+[`GroupAccessProperties`](@ref).
 """
 function open_group(
- parent::Union{File,Group},
- name::AbstractString,
- gapl::GroupAccessProperties=GroupAccessProperties()
+ parent::Union{File,Group}, name::AbstractString, gapl::GroupAccessProperties
 )
  return Group(API.h5g_open(checkvalid(parent), name, gapl), file(parent))
 end
+function open_group(parent::Union{File,Group}, name::AbstractString; pv...)
+ gapl = GroupAccessProperties(; pv...)
+ return open_group(parent, name, gapl)
+end
 
 # Get the root group
 root(h5file::File) = open_group(h5file, "/")

diff --git a/src/highlevel.jl b/src/highlevel.jl
@@ -77,17 +77,11 @@ function Base.getindex(parent::Union{File,Group}, path::AbstractString; pv...)
  isempty(pv) && return open_object(parent, path)
  obj_type = gettype(parent, path)
  if obj_type == API.H5I_DATASET
- dapl = DatasetAccessProperties()
- dxpl = DatasetTransferProperties()
- pv = setproperties!(dapl, dxpl; pv...)
- isempty(pv) || error("invalid keyword options $pv")
- return open_dataset(parent, path, dapl, dxpl)
+ return open_dataset(parent, path; pv...)
  elseif obj_type == API.H5I_GROUP
- gapl = GroupAccessProperties(; pv...)
- return open_group(parent, path, gapl)
+ return open_group(parent, path; pv...)
  else#if obj_type == API.H5I_DATATYPE # only remaining choice
- tapl = DatatypeAccessProperties(; pv...)
- return open_datatype(parent, path, tapl)
+ return open_datatype(parent, path; pv...)
  end
 end
 

diff --git a/src/properties.jl b/src/properties.jl
@@ -408,6 +408,8 @@ Properties used when creating a new `Dataset`. Inherits from
  - `:never`: Never fill
  - `:ifset`: Fill if a value is set
 
+- `fill_value`: the fill value for a dataset. See $(h5doc("H5P_SET_FILL_VALUE")).
+
 - `chunk`: a tuple containing the size of the chunks to store each dimension.
  See $(h5doc("H5P_SET_CHUNK")) (note that this uses Julia's column-major
  ordering).
@@ -772,9 +774,19 @@ end
 
 @propertyclass LinkAccessProperties API.H5P_LINK_ACCESS
 
+"""
+ GroupAccessProperties(;kws...)
+
+Properties used when accessing datatypes. None are currently defined.
+"""
 @propertyclass GroupAccessProperties API.H5P_GROUP_ACCESS
 superclass(::Type{GroupAccessProperties}) = LinkAccessProperties
 
+"""
+ DatatypeAccessProperties(;kws...)
+
+Properties used when accessing datatypes. None are currently defined.
+"""
 @propertyclass DatatypeAccessProperties API.H5P_DATATYPE_ACCESS
 superclass(::Type{DatatypeAccessProperties}) = LinkAccessProperties