clean up, add some docs

docs/src/interface/properties.md

@@ -29,6 +29,13 @@ StringCreateProperties
 DatatypeCreateProperties
 ```
 
+## Virtual Datasets
+
+```@docs
+VirtualMapping
+VirtualLyout
+```
+
 ## Drivers
 
 ```@meta
@@ -46,3 +53,4 @@ Core
 POSIX
 MPIO
 ```
+

src/properties.jl

@@ -431,15 +431,20 @@ Properties used when creating a new `Dataset`. Inherits from
    - `:chunked`: Store raw data separately from the object header as chunks of
      data in separate locations in the file.
 
-   - `:virtual`:  Draw raw data from multiple datasets in different files.
+   - `:virtual`:  Draw raw data from multiple datasets in different files. See
+     the `virtual` property below.
 
   See $(h5doc("H5P_SET_LAYOUT")).
 
 - `no_attrs_hint`: Minimize the space for dataset metadata by hinting that no
    attributes will be added if set to `true`. Attributes can still be added but
-   may exist elsewhere within the file.
-   See $(h5doc("H5P_SET_DSET_NO_ATTRS_HINT")).
+   may exist elsewhere within the file. See
+   $(h5doc("H5P_SET_DSET_NO_ATTRS_HINT")).
 
+- `virtual`: when specified, creates a virtual dataset (VDS). The argument
+  should be a "virtuala collection of [`VirtualMapping`](@ref) objects for
+  describing the mapping from the dataset to the source datasets. When accessed,
+  returns a [`VirtualLayout`](@ref) object.
 
 The following options are shortcuts for the various filters, and are set-only.
 They will be appended to the filter pipeline in the order in which they appear

src/virtual.jl

@@ -1,36 +1,61 @@
-# virtual dataset
+"""
+    VirtualMapping(
+        vspace::Dataspace,
+        srcfile::AbstractString,
+        srcdset::AbstractString,
+        srcspace::Dataspace
+    )
+
+Specify a map of elements of the virtual dataset (VDS) described by `vspace` to
+the elements of the source dataset described by `srcspace`. The source dataset
+is identified by the name of the file where it is located, `srcfile`, and the
+name of the dataset, `srcdset`.
+
+Both `srcfile` and `srcdset` support "printf"-style formats with `%b` being
+replaced by the block count of the selection.
+
+For more details on how source file resolution works, see
+[`H5P_SET_VIRTUAL`](https://portal.hdfgroup.org/display/HDF5/H5P_SET_VIRTUAL).
+"""
 struct VirtualMapping
-  vspace::Dataspace
-  srcfile::String
-  srcdset::String
-  srcspace::Dataspace
+    vspace::Dataspace
+    srcfile::String
+    srcdset::String
+    srcspace::Dataspace
 end
 
+"""
+    VirtualLayout(dcpl::DatasetCreateProperties)
+
+The collection of [`VirtualMapping`](@ref)s associated with `dcpl`. This is an
+`AbstractVector{VirtualMapping}`, supporting `length`, `getindex` and `push!`.
+"""
 struct VirtualLayout <: AbstractVector{VirtualMapping}
-  dcpl::DatasetCreateProperties
+    dcpl::DatasetCreateProperties
 end
 
 function Base.length(vlayout::VirtualLayout)
-  return API.h5p_get_virtual_count(vlayout.dcpl)
+    return API.h5p_get_virtual_count(vlayout.dcpl)
 end
 Base.size(vlayout::VirtualLayout) = (length(vlayout),)
 
 function Base.push!(vlayout::VirtualLayout, vmap::VirtualMapping)
-  API.h5p_set_virtual(vlayout.dcpl, vmap.vspace, vmap.srcfile, vmap.srcdset, vmap.srcspace)
-  return vlayout
+    API.h5p_set_virtual(
+        vlayout.dcpl, vmap.vspace, vmap.srcfile, vmap.srcdset, vmap.srcspace
+    )
+    return vlayout
 end
 function Base.append!(vlayout::VirtualLayout, vmaps)
-  for vmap in vmaps
-      push!(vlayout, vmap)
-  end
-  return vlayout
+    for vmap in vmaps
+        push!(vlayout, vmap)
+    end
+    return vlayout
 end
 
 function Base.getindex(vlayout::VirtualLayout, i::Integer)
-  vspace = Dataspace(API.h5p_get_virtual_vspace(vlayout.dcpl, i-1))
-  srcfile = API.h5p_get_virtual_filename(vlayout.dcpl, i-1)
-  srcdset = API.h5p_get_virtual_dsetname(vlayout.dcpl, i-1)
-  srcspace = Dataspace(API.h5p_get_virtual_srcspace(vlayout.dcpl, i-1))
-  return VirtualMapping(vspace, srcfile, srcdset, srcspace)
+    vspace = Dataspace(API.h5p_get_virtual_vspace(vlayout.dcpl, i - 1))
+    srcfile = API.h5p_get_virtual_filename(vlayout.dcpl, i - 1)
+    srcdset = API.h5p_get_virtual_dsetname(vlayout.dcpl, i - 1)
+    srcspace = Dataspace(API.h5p_get_virtual_srcspace(vlayout.dcpl, i - 1))
+    return VirtualMapping(vspace, srcfile, srcdset, srcspace)
 end
-

test/virtual_dataset.jl

@@ -25,7 +25,14 @@ d = create_dataset(
     "x",
     datatype(Float64),
     vspace;
-    virtual=[HDF5.VirtualMapping(vspace, "./sub-%b.hdf5", "x", srcspace)]
+    virtual=[HDF5.VirtualMapping(vspace, "./sub-%0b.hdf5", "x", srcspace)]
 )
 
+@test size(d) == (3,2)
 @test read(d) == hcat(fill(1.0, 3), fill(2.0, 3))
+
+dcpl = HDF5.get_create_properties(d)
+
+@test dcpl.virtual isa HDF5.VirtualLayout
+@test length(dcpl.virtual) == 1
+@test dcpl.virtual[1] isa HDF5.VirtualMapping