relaton-index 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0eaf31518d3ecfb78041891165d24d8f0e9673d2aebcfa02608694ec9f562843
-  data.tar.gz: 206c0f5fcf0b5336ff186f35da3efc79fda86cf25c93f1c499dd525cccdd6128
+  metadata.gz: bc21a3161ae2d23d6b2178a5947d07c83dd1758f6db4e093340b90f525968edd
+  data.tar.gz: 8bf654f9260aff06bb3be34e6b14a35adf1280e5d90085a57fc3c608db976b94
 SHA512:
-  metadata.gz: 3426d0303d776d0c7ecaeb17bf957a20228858ae859f85aec02d52dc833d643ead02cd14c522d6fcecc72b9f920e2efbc3667f31c86e6dcd363ebc4ef9eae516
-  data.tar.gz: 0e8809f80cc34c92100a081917ce561ccaeb287e9002171f558d62e0c6148ac68a5b4b72f96e8720815f4d3be9390cda026fe39b08c3ba0895706c15a74e8865
+  metadata.gz: faf0f893ec70ae6c5186e6fa2afe5619d9ab4757d6fef73f1637163690a1a371df999e4d85a5af896e8ae2bae479d690891bedc704f5227aa55d52a02f582217
+  data.tar.gz: b9cf08da7a80849861da0c999d0d603d0b8c1466b93ed0e898d1bdb670bb5e49eb82ce592ba75d0d276d28d0309c3e85cccf5d317263791b16784132b55da8cf

data/README.adoc

@@ -22,18 +22,34 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 == Usage
 
+=== Creating an index object
+
+The gem provides the `Relaton::Index.find_or_create {type}, url: {url}, file: {filename}, id_keys: {keys}` method to create an index object. The first argument is the type of dataset (ISO, IEC, IHO, etc.). The second argument is the URL to the zipped remote index file. The third argument is the filename of the local index file. The fourth argument is an array of ID's parts names. The URL, filename, and keys are optional.
+
+If the URL is specified and the local file in a `/{home}/.relaton/{type}` dir doesn't exist or is outdated, the index file will be downloaded from the URL saved as a local file and an index object will be created from the file. If the file in the `/{home}/.relaton/{type}` exists and is actual, the index object will be created from the local file.
+
+If the URL isn't specified, the index object will be created from the local file in the current dir `./{filename}`. If the file doesn't exist, the empty index object will be created.
+
+If the filename isn't specified, a default `index,yaml` filename will be used.
+
+If the keys are specified, the local index file will be checked for the presence of the keys. If the keys are not found, the index file will be downloaded from the URL or an empty index object will be created if the URL isn't specified.
+
+It's possible to create many index objects for different types of datasets. The index objects are saved in the pool. The pool is a hash with the type of dataset as a key and the index object as a value. The pool is a class variable of the `Relaton::Index` class. The pool is used to find an existing index object by the type of dataset. The `Relaton::Index.find_or_create` method returns an existing index object if it was created before.
+
+If the URL or filename is specified and has a new value, different from what was used to create the index object before, the index object will be recreated.
+
 [source,ruby]
 ----
 require 'relaton/index'
 
 # Create a new index object. The first argument is the type of dataset (ISO, IEC, IHO, etc.) URL and filename are optional.
-Relaton::Index.find_or_create :IHO, url: "https://raw.githubusercontent.com/relaton/relaton-data-iho/master/index.zip", filename: "index-iho.yaml"
+Relaton::Index.find_or_create :IHO, url: "https://raw.githubusercontent.com/relaton/relaton-data-iho/master/index.zip", file: "index-iho.yaml", id_keys: %i[number part year]
 
 # Find an existing index object (created before).
 Relaton::Index.find_or_create :IHO
 
 # If the URL or filename is specified and has a new value (different from what it was before), the index object will be recreated.
-Relaton::Index.find_or_create :IHO, url: nil, filename: "index.yaml"
+Relaton::Index.find_or_create :IHO, url: nil, file: "index.yaml"
 
 # Remove the index from the pool.
 Relaton::Index.close :IHO
@@ -48,12 +64,12 @@ The aim of this gem is to be used by Relaton libraries in two ways:
 In this case, the Relaton library creates an index object and adds documents' files to it. By default, the index object is saved to the `index.yaml` file in the root of the repository. The filename can be changed using the `filename` setting.
 
 [source,ruby]
----- 
+----
 # Create a new index object or fetch an existing one. The first argument is the type of dataset (ISO, IEC, IHO, etc.) URL should not be specified.
 index = Relaton::Index.find_or_create :IHO
 
 # Add a document to the index or update it if it already exists.
-index.add_or_update id: "B-4 2.19.0", file: "data/b-4_2_19_0.xml"
+index.add_or_update "B-4 2.19.0", "data/b-4_2_19_0.xml"
 
 # Save the index to the `index.yaml` file in the current directory.
 index.save
@@ -69,16 +85,16 @@ In this case, the Relaton library should create an index object and search for a
 index = Relaton::Index.find_or_create :IHO, url: "https://raw.githubusercontent.com/relaton/relaton-data-iho/master/index.zip"
 
 
-# Search for a document by reference 
-index.search "B-4" 
-# => [{ id: "B-4 2.19.0", file: "data/b-4_2_19_0.xml" }] 
+# Search for a document by reference
+index.search "B-4"
+# => [{ id: "B-4 2.19.0", file: "data/b-4_2_19_0.xml" }]
 
 # Search for a document by reference using a block
 index.search do |row|
   # do something with the index row
   row[:id] == "B-4"
 end
-# => [{ id: "B-4 2.19.0", file: "data/b-4_2_19_0.xml" }] 
+# => [{ id: "B-4 2.19.0", file: "data/b-4_2_19_0.xml" }]
 ----
 
 === Remove all index records
@@ -110,7 +126,7 @@ The gem can be configured by using the `Relaton::Index.config` method. The follo
 [source,ruby]
 ----
 Relaton::Index.config do |config|
-  config.filename = "index-new.yaml"
+  config.filename = "index-v1.yaml"
   config.storage = S3Storage
   config.storage_dir = "/"
 end
@@ -119,7 +135,7 @@ end
 It's also possible to redefine file name for a specific type of index:
 [source,ruby]
 ----
-index = Relaton::Index.find_or_create :IHO, filename: "index-iho.yaml"
+index = Relaton::Index.find_or_create :IHO, file: "index-v2.yaml"
 ----
 
 == Development

data/lib/relaton/index/file_io.rb

@@ -11,23 +11,26 @@ module Relaton
       #
       # Initialize FileIO
       #
-      # @param [String] dir local directory in ~/.relaton to store index
-      # @param [String, Boolean, nil] url git repository URL to fetch index from
-      #   (if not exists, or older than 24 hours) or nil if index is used to
-      #   index files
-      #
-      def initialize(dir, url, filename)
+      # @param [String] dir falvor specific local directory in ~/.relaton to store index
+      # @param [String, Boolean, nil] url
+      #   if String then the URL is used to fetch an index from a Git repository
+      #     and save it to the storage (if not exists, or older than 24 hours)
+      #   if true then the index is read from the storage (used to remove index file)
+      #   if nil then the fiename is used to read and write file (used to create indes in GH actions)
+      #
+      def initialize(dir, url, filename, id_keys)
         @dir = dir
         @url = url
         @filename = filename
+        @id_keys = id_keys || []
       end
 
       #
       # If url is String, check if index file exists and is not older than 24
       #   hours. If not, fetch index from external repository and save it to
       #   storage.
-      # If url is true, remove index from storage.
-      # If url is nil, read index from file.
+      # If url is true, read index from path to local file.
+      # If url is nil, read index from filename.
       #
       # @return [Array<Hash>] index
       #
@@ -36,7 +39,7 @@ module Relaton
         when String
           check_file || fetch_and_save
         else
-          read_file
+          read_file || []
         end
       end
 
@@ -65,6 +68,24 @@ module Relaton
         read_file
       end
 
+      #
+      # Check if index has correct format
+      #
+      # @param [Array<Hash>] index index to check
+      #
+      # @return [Boolean] <description>
+      #
+      def check_format(index) # rubocop:disable Metrics/AbcSize
+        keys = index.reduce(Set.new) do |acc, item|
+          if item[:id].is_a?(Hash) && @id_keys.any?
+            acc + item.keys + item[:id].keys
+          else
+            acc + item.keys
+          end
+        end
+        keys == [:id, :file, *@id_keys].to_set
+      end
+
       #
       # Read index from storage
       #
@@ -72,9 +93,11 @@ module Relaton
       #
       def read_file
         yaml = Index.config.storage.read(file)
-        return [] unless yaml
+        return unless yaml
 
-        YAML.safe_load yaml, permitted_classes: [Symbol]
+        index = YAML.safe_load yaml, permitted_classes: [Symbol]
+        return index if check_format index
+      rescue Psych::SyntaxError
       end
 
       #

data/lib/relaton/index/pool.rb

@@ -14,6 +14,7 @@ module Relaton
       # @param [String] type <description>
       # @param [String, nil] url external URL to index, used to fetch index for searching files
       # @param [String, nil] file output file name
+      # @param [Array<Symbol>, nil] id_keys keys to check if index is correct
       #
       # @return [Relaton::Index::Type] typed index
       #
@@ -21,7 +22,7 @@ module Relaton
         if @pool[type.upcase.to_sym]&.actual?(**args)
           @pool[type.upcase.to_sym]
         else
-          @pool[type.upcase.to_sym] = Type.new(type, args[:url], args[:file])
+          @pool[type.upcase.to_sym] = Type.new(type, args[:url], args[:file], args[:id_keys])
         end
       end
 

data/lib/relaton/index/type.rb

@@ -11,10 +11,10 @@ module Relaton
       # @param [String, nil] url external URL to index, used to fetch index for searching files
       # @param [String, nil] file output file name
       #
-      def initialize(type, url = nil, file = nil)
+      def initialize(type, url = nil, file = nil, id_keys = nil)
         @file = file
         filename = file || Index.config.filename
-        @file_io = FileIO.new type.to_s.downcase, url, filename
+        @file_io = FileIO.new type.to_s.downcase, url, filename, id_keys
       end
 
       def index

data/lib/relaton/index/version.rb

@@ -2,6 +2,6 @@
 
 module Relaton
   module Index
-    VERSION = "0.2.0"
+    VERSION = "0.2.2"
   end
 end

data/lib/relaton/index.rb

@@ -21,11 +21,12 @@ module Relaton
       # @param [String] type index type (ISO, IEC, etc.)
       # @param [String, nil] url external URL to index, used to fetch index for searching files
       # @param [String, nil] file output file name, default is config.filename
+      # @param [Array<Symbol>, nil] id_keys keys to check if index is correct
       #
       # @return [Relaton::Index::Type] typed index
       #
-      def find_or_create(type, url: nil, file: nil)
-        pool.type(type, url: url, file: file)
+      def find_or_create(type, url: nil, file: nil, id_keys: nil)
+        pool.type(type, url: url, file: file, id_keys: id_keys)
       end
 
       def close(type)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: relaton-index
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-05-14 00:00:00.000000000 Z
+date: 2023-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyzip