paneron-register

= Paneron Register Ruby Gem

image:https://img.shields.io/gem/v/paneron-register.svg["Gem Version", link="https://rubygems.org/gems/paneron-register"] image:https://github.com/paneron/ruby-paneron-register/actions/workflows/test.yaml/badge.svg["Build Status",Link="https://github.com/paneron/ruby-paneron-register/actions/workflows/test.yaml"] image:https://codeclimate.com/github/paneron/ruby-paneron-register/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/paneron/ruby-paneron-register"] image:https://img.shields.io/github/issues-pr-raw/paneron/ruby-paneron-register.svg["Pull Requests", link="https://github.com/paneron/ruby-paneron-register/pulls"] image:https://img.shields.io/github/commits-since/paneron/ruby-paneron-register/latest.svg["Commits since latest",link="https://github.com/paneron/ruby-paneron-register/releases"]

== Installation

gem install paneron-register

== Usage

[source,ruby]

require "paneron/register" include Paneron::Register

Initialize a new data set

This example uses a working copy of Paneron's data set.

=> 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" )

=> DataSet < Lutaml::Model::Serializable

data_set = raw_data_set.to_lutaml

Alternatively, initialize a new register:

=> Paneron::Register::Raw::Register

raw_register = Raw::Register.new( "/Users/username/Library/Application Support/Electron/working_copies/00000000-0001-0000-0000-000000000001", )

This example uses a Git URL

=> 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,

)

=> Raw::DataSet

raw_data_set = raw_register.data_sets("data_set_name-1")

=> DataSet < Lutaml::Model::Serializable

data_set = raw_data_set.to_lutaml

Get all item class objects

=> { item-class-name: Raw::ItemClass }

raw_data_set.item_classes

=> [ ItemClass ]

data_set.item_classes

Get a specific item class object

=> Raw::ItemClass

raw_item_class = raw_data_set.item_classes("item-class-1")

=> ItemClass < Lutaml::Model::Serializable

item_class = raw_item_class.to_lutaml

Get all item objects in Ruby Hash format

=> { item-uuid: Raw::Item }

raw_item_class.items

=> [ Item ]

item_class.items

Get a specific item property, using normal Ruby Hash methods

=> 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

=> 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 link:LICENSE.txt[LICENSE.txt]