paneron-register 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52d7cfff231080db14c14453bd757db38f58b35ffcdbe69588c34fc97facc331
-  data.tar.gz: f5d14ee0605cc362800849f463a08bacf6cf2e1ef3a055244425b7264933bdf1
+  metadata.gz: 560320c2a03e90f346dafccc8a2088c4637ce9d80bf789a01b79d6711409b812
+  data.tar.gz: 6a2996fe23f059d525a1ecb8b2d71384a22ba67adcfba27814855c5a2a18fc37
 SHA512:
-  metadata.gz: 5a8588a75ec028ce6faa1083f615c120ed289a31924a19276383e8309ac40c2aa0733b299de94d1af23d98406faf67b06548351a605f2ead260ee1f927be30e7
-  data.tar.gz: '049798fcb8d8308ada3f45ce7effb8d960e3546890c5780c34178c5ad2bd94653f82be52f63a29945d3cf3b98d1b1a251055a1dec529b8056103c8da1ac5b268'
+  metadata.gz: 9885fa28ebdcf9c5dfc8899b125480e88d4876cba6473cff144e0f2dc5178d5478a8478b92eb44fd31e638d1a94a68362dd0bef9e324f51919189da601d904eb
+  data.tar.gz: ef8c656a0d9c76bd1e38b43befc4689045e00e4cc88a966b9734ef4e2dd473139a037eeabc0f2e784743878748d572c5ac56290b3c8e9be56cfcecf1f23b2352

data/.irbrc

@@ -1 +1,2 @@
 require "paneron/register"
+include Paneron::Register

data/.pryrc

@@ -1 +1,2 @@
 require "paneron/register"
+include Paneron::Register

data/README.adoc

@@ -15,75 +15,219 @@ gem install paneron-register
 
 == Usage
 
-```ruby
+[source,ruby]
+----
 require "paneron/register"
+include Paneron::Register
 
 # Initialize a new data set
 # This example uses a working copy of Paneron's data set.
-# => Paneron::Register::Raw::DataSet
-raw_data_set = Paneron::Register::Raw::DataSet.new(
+# => Raw::DataSet
+raw_data_set = Raw::DataSet.new(
   "/Users/username/Library/Application Support/Electron/working_copies/00000000-0001-0000-0000-000000000001",
   "data_set_name-1"
 )
 
-# => Paneron::Register::DataSet < Lutaml::Model::Serializable
+# => DataSet < Lutaml::Model::Serializable
 data_set = raw_data_set.to_lutaml
 
 # Alternatively, initialize a new register:
 # => Paneron::Register::Raw::Register
-raw_register = Paneron::Register::Raw::Register.new(
+raw_register = Raw::Register.new(
   "/Users/username/Library/Application Support/Electron/working_copies/00000000-0001-0000-0000-000000000001",
 )
 
 # This example uses a Git URL
-# => Paneron::Register::Raw::Register
-raw_register = Paneron::Register::Raw::Register.from_git(
+# => Raw::Register
+raw_register = Raw::Register.from_git(
   "https://github.com/isogr/registry",
 
   # optional.  For previously cloned repos, pulls from repo iff true.
   # update: true,
 )
 
-# => Paneron::Register::Raw::DataSet
+# => Raw::DataSet
 raw_data_set = raw_register.data_sets("data_set_name-1")
 
-# => Paneron::Register::DataSet < Lutaml::Model::Serializable
+# => DataSet < Lutaml::Model::Serializable
 data_set = raw_data_set.to_lutaml
 
 # Get all item class objects
-# => { item-class-name: Paneron::Register::Raw::ItemClass }
+# => { item-class-name: Raw::ItemClass }
 raw_data_set.item_classes
 
-# => [ Paneron::Register::ItemClass ]
+# => [ ItemClass ]
 data_set.item_classes
 
 # Get a specific item class object
-# => Paneron::Register::Raw::ItemClass
+# => Raw::ItemClass
 raw_item_class = raw_data_set.item_classes("item-class-1")
 
-# => Paneron::Register::ItemClass < Lutaml::Model::Serializable
+# => ItemClass < Lutaml::Model::Serializable
 item_class = raw_item_class.to_lutaml
 
 # Get all item objects in Ruby Hash format
-# => { item-uuid: Paneron::Register::Raw::Item }
+# => { item-uuid: Raw::Item }
 raw_item_class.items
 
-# => [ Paneron::Register::Item ]
+# => [ Item ]
 item_class.items
 
 # Get a specific item property, using normal Ruby Hash methods
-# => Paneron::Register::Raw::Item
+# => Raw::Item
 raw_item = raw_item_class.items["00000000-0000-0000-0000-000000000001"]
 id = raw_item["id"]
 blob1 = raw_item["data"]["blob1"]
 
 # Get a specific item property, from a Lutaml object
-# => Paneron::Register::Item < Lutaml::Model::Serializable
+# => Item < Lutaml::Model::Serializable
 item = raw_item.to_lutaml
 id = item.to_h["id"]
 blob1 = item.to_h["data"]["blob1"]
-```
+----
+
+For more usage examples, see link:docs/examples.adoc[`Examples`^]
+and related link:spec/worked_examples_spec.rb[`spec/worked_examples_spec.rb`^].
+
+
+== Development
+
+Git clone this repository, then install dependencies.
+
+[source,shell]
+----
+git clone https://github.com/paneron/ruby-paneron-register
+cd ruby-paneron-register
+bundle install
+----
+
+=== Without Nix
+
+Open development shell (`irb`) with:
+
+[source,shell]
+----
+bundle exec irb
+----
+
+Open development shell (`pry`) with:
+
+[source,shell]
+----
+bundle exec pry
+----
+
+Run tests with:
+
+[source,shell]
+----
+bundle exec rspec
+# or
+bundle exec rake spec
+----
+
+Run lint with:
+
+[source,shell]
+----
+bundle exec rubocop
+----
+
+Run lint with autocorrect with:
+
+[source,shell]
+----
+bundle exec rubocop -a
+----
+
+Release to Rubygem (adds a Git tag, pushes to GitHub and releases to Rubygem) with:
+
+[source,shell]
+----
+bundle exec rake release
+----
+
+=== With Nix
+
+If your system is using Nix, run the following to gain access to shell aliases:
+
+[source,shell]
+----
+nix develop
+----
+
+Open development shell (`irb`) with:
+
+[source,shell]
+----
+irb
+# or
+console
+----
+
+Open development shell (`pry`) with:
+
+[source,shell]
+----
+pry
+----
+
+Run tests with:
+
+[source,shell]
+----
+rspec
+----
+
+Run lint with:
+
+[source,shell]
+----
+lint
+# or
+rubocop
+----
+
+Run lint with autocorrect with:
+
+[source,shell]
+----
+lint -a
+# or
+rubocop -a
+----
+
+Release to Rubygem (adds a Git tag, pushes to GitHub and releases to Rubygem) with:
+
+[source,shell]
+----
+release
+----
+
+Update Nix flakes with:
+
+[source,shell]
+----
+update-flakes
+----
+
+== Release workflow
+
+When actually creating a new version for release, do the following:
+
+. Update the `VERSION` in file link:lib/paneron/register/version.rb[`lib/paneron/register/version.rb`^].
+. [[:space:]]
++
+[source,shell]
+----
+git add lib/paneron/register/version.rb
+git commit -m 'chore: Release vX.Y.Z' # change X.Y.Z to actual version
+git push
+
+# Run rake release
+bundle exec rake release
+----
 
 == License
 
-See LICENSE.txt
+See link:LICENSE.txt[`LICENSE.txt`]

data/docs/examples.adoc

@@ -0,0 +1,91 @@
+= Examples
+
+NOTE: Follow link:../spec/worked_examples_spec.rb[`spec/worked_examples_spec.rb`] for continuously integrated examples.
+
+In this document, you'll find examples of how to use the library.
+
+The following examples assume this preamble:
+
+[source,ruby]
+----
+require "paneron/register"
+include Paneron::Register
+----
+
+
+== Create a register
+
+=== From scratch
+
+[source,ruby]
+----
+register = Raw::Register.generate(
+  "/local/path/to/directory/can/be/empty",
+  git_url: "git URL",
+  )
+
+# Create a data set
+ds =
+  register.spawn_data_set("data_set_name")
+
+# Register#save commits the data to git.
+register.save
+
+# Register#sync pushes the commits to git remote.
+register.sync
+----
+
+
+=== From an existing Git repository
+
+[source,ruby]
+----
+register = Raw::Register.from_git("git URL")
+----
+
+
+== Register an item class
+
+[source,ruby]
+----
+data_set = register.spawn_data_set("data_set_name").save
+item_class = data_set.spawn_item_class("item_class_name").save
+----
+
+== Store a file in the item
+
+[source,ruby]
+----
+item = item_class.spawn_item
+item.data = "file contents"
+item.save
+
+# Take a note of its UUID for future retrieval
+item_uuid = item.uuid
+----
+
+== Write the item to register (sync local to remote)
+
+[source,ruby]
+----
+# Register#sync
+# Register#sync pushes the commits to git remote.
+register.sync
+----
+
+== Fetch the item for use
+
+[source,ruby]
+----
+# Register.from_git clones the repo to local cache.
+# It automatically calls `git pull --rebase` to sync with remote.
+register = Raw::Register.from_git("git URL")
+item = register.items(item_uuid)
+----
+
+== Obtain the file from the item
+
+[source,ruby]
+----
+file = item.data
+----

data/lib/paneron/register/hierarchical.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Paneron
+  module Register
+    module Hierarchical
+      # def self.included(base)
+      #   base.class_eval do
+      #   end
+      # end
+      # Split into parent path and base name
+
+      def self.split_path(full_path)
+        # {
+        #   parent_path: File.dirname(full_path),
+        #   basename: File.basename(full_path),
+        # }
+        [
+          File.dirname(full_path),
+          File.basename(full_path),
+        ]
+      end
+    end
+  end
+end