Add example scripts for HDF5 file operations and error handling

Author: kojix2

.gitignore

@@ -6,5 +6,6 @@
 /pkg/
 /spec/reports/
 /tmp/
+examples/*.h5
 
 *.lock

examples/01_read_fixture.rb

@@ -0,0 +1,15 @@
+require 'hdf5'
+
+fixture = File.expand_path('../test/fixtures/example.h5', __dir__)
+
+HDF5::File.open(fixture) do |file|
+  puts "Entries: #{file.list_entries.inspect}"
+
+  group = file['foo']
+  puts "Datasets in /foo: #{group.list_datasets.inspect}"
+
+  int_ds = group['bar_int']
+  puts "bar_int shape: #{int_ds.shape.inspect}"
+  puts "bar_int dtype: #{int_ds.dtype}"
+  puts "bar_int values: #{int_ds.read.inspect}"
+end

examples/02_create_numeric_file.rb

@@ -0,0 +1,19 @@
+require 'hdf5'
+
+path = File.expand_path('numeric_example.h5', __dir__)
+
+HDF5::File.create(path) do |file|
+  file.create_group('values') do |group|
+    group.create_dataset('ints', [1, 2, 3, 4, 5])
+    group.create_dataset('floats', [1.25, 2.5, 3.75])
+  end
+end
+
+HDF5::File.open(path) do |file|
+  puts "Created file: #{path}"
+  puts "Root entries: #{file.list_entries.inspect}"
+
+  values = file['values']
+  puts "ints: #{values['ints'].read.inspect}"
+  puts "floats: #{values['floats'].read.inspect}"
+end

examples/03_nested_groups.rb

@@ -0,0 +1,20 @@
+require 'hdf5'
+
+path = File.expand_path('nested_groups.h5', __dir__)
+
+HDF5::File.create(path) do |file|
+  file.create_group('experiments') do |experiments|
+    experiments.create_group('run_001') do |run|
+      run.create_dataset('temperatures', [21.1, 21.3, 21.7, 22.0])
+    end
+  end
+end
+
+HDF5::File.open(path) do |file|
+  run = file['experiments']['run_001']
+  ds = run['temperatures']
+
+  puts "Dataset shape: #{ds.shape.inspect}"
+  puts "Dataset dtype: #{ds.dtype}"
+  puts "Dataset values: #{ds.read.inspect}"
+end

examples/04_error_handling.rb

@@ -0,0 +1,15 @@
+require 'hdf5'
+
+begin
+  HDF5::File.open('/tmp/does-not-exist-ruby-hdf5.h5')
+rescue HDF5::Error => e
+  warn "HDF5::Error: #{e.message}"
+end
+
+begin
+  HDF5::File.create(File.expand_path('bad_data.h5', __dir__)) do |file|
+    file.create_dataset('invalid', %w[a b c])
+  end
+rescue HDF5::Error => e
+  warn "HDF5::Error: #{e.message}"
+end

examples/README.md

@@ -0,0 +1,12 @@
+# Examples
+
+Run examples from the repository root.
+
+```sh
+bundle exec ruby examples/01_read_fixture.rb
+bundle exec ruby examples/02_create_numeric_file.rb
+bundle exec ruby examples/03_nested_groups.rb
+bundle exec ruby examples/04_error_handling.rb
+```
+
+If the HDF5 shared library cannot be found, set `HDF5_LIB_PATH` before running examples.