relaton-index 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e593c33ab08170851f728d43821031387b3ad70ce441501429909132306880ab
+  data.tar.gz: a5445a29d744fa3ff9214274be7be64a0694f1262ee8f99820a4abef61c0398b
+SHA512:
+  metadata.gz: a0a292add233827c1298bcddad35aaab24a611a4ac4bdc9cb8a323aee92b2673740f551d68fb1591a11bda20fa01ccc55ea444233b4bc5d2719493ba9ab5dd92
+  data.tar.gz: 0e06a6dd6372fc7cca12bf05b5f83007f48ee992af18c2191b8fc0f6ea854df9401867aa9aac848bd93e228ac5de8f66ca52ee19b42cfb0f7b1c55078678804c

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,12 @@
+# This project follows the Ribose OSS style guide.
+# https://github.com/riboseinc/oss-guides
+# All project-specific additions and overrides should be specified in this file.
+
+require: rubocop-rails
+
+inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+AllCops:
+  TargetRubyVersion: 2.7
+Rails:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in relaton-index.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.46"
+gem "rubocop-performance", "~> 1.15"
+gem "rubocop-rails", "~> 2.17"
+
+gem "simplecov", "~> 0.22"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Ribose Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.adoc

@@ -0,0 +1,79 @@
+= Relaton::Index
+
+image:https://img.shields.io/gem/v/relaton-index.svg["Gem Version", link="https://rubygems.org/gems/relaton-index"]
+image:https://github.com/relaton/relaton-index/workflows/macos/badge.svg["Build Status (macOS)", link="https://github.com/relaton/relaton-index/actions?workflow=macos"]
+image:https://github.com/relaton/relaton-index/workflows/windows/badge.svg["Build Status (Windows)", link="https://github.com/relaton/relaton-index/actions?workflow=windows"]
+image:https://github.com/relaton/relaton-index/workflows/ubuntu/badge.svg["Build Status (Ubuntu)", link="https://github.com/relaton/relaton-index/actions?workflow=ubuntu"]
+image:https://codeclimate.com/github/relaton/relaton-index/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/relaton-index"]
+image:https://img.shields.io/github/issues-pr-raw/relaton/relaton-index.svg["Pull Requests", link="https://github.com/relaton/relaton-index/pulls"]
+image:https://img.shields.io/github/commits-since/relaton/relaton-index/latest.svg["Commits since latest",link="https://github.com/relaton/relaton-index/releases"]
+
+This gem is a part of [Relaton](https://github.com/relaton) project. It provides a way to index Relaton documents' files and search them by references.
+
+== Installation
+
+Install the gem and add it to the application's Gemfile by executing:
+
+    $ bundle add relaton-index
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install relaton-index
+
+== Usage
+
+The aim of this gem is to be used by Relaton libraries in two ways:
+- indexing documents' files in GitHub repositories
+- searching a document by a reference when the Relaton library fetches a document
+
+=== Indexing
+
+In this case, the Relaton library should create an index object and add documents' files to it. The index object should be saved to the `index.yaml` file in the root of the repository.
+
+[source,ruby]
+---- 
+require 'relaton/index' 
+
+# 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"
+
+# Save the index to the `index.yaml` file in the current directory.
+index.save
+----
+
+=== Searching
+
+In this case, the Relaton library should create an index object and search for a document by reference. The gem looks for the `.relaton/[TYPE]/index.yaml` file in the user's home directory. The `[TYPE]` is one of downcased ISO, IEC, IHO, etc. If the file is not found or is older than 24 hours then it will be downloaded from the URL specified in the `find_or_create` method.
+
+[source,ruby]
+----
+require 'relaton/index' 
+
+# Create a new index object or fetch an existing one. URL should be specified. If the index file is not found or is older than 24 hours, it will be downloaded from the URL. By default, the index file is saved to the `/[HOME]/.relaton/[TYPE]/index.yaml` file.
+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 2.19.0" 
+# => ["data/b-4_2_19_0.xml"] 
+
+# Remove the index from the pool.
+Relaton::Index.close :IHO
+----
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/relaton/relaton-index.
+
+== License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec]

data/lib/relaton/index/config.rb

@@ -0,0 +1,40 @@
+module Relaton
+  module Index
+    #
+    # Configuration class for Relaton::Index
+    #
+    class Config
+      attr_reader :storage, :storage_dir
+
+      #
+      # Set default values
+      #
+      def initialize
+        @storage = FileStorage
+        @storage_dir = Dir.home
+      end
+
+      #
+      # Set storage
+      #
+      # @param [#ctime, #read, #write] storage storage object
+      #
+      # @return [void]
+      #
+      def storage=(storage)
+        @storage = storage
+      end
+
+      #
+      # Set storage directory
+      #
+      # @param [String] dir storage directory
+      #
+      # @return [void]
+      #
+      def storage_dir=(dir)
+        @storage_dir = dir
+      end
+    end
+  end
+end

data/lib/relaton/index/file_io.rb

@@ -0,0 +1,86 @@
+module Relaton
+  module Index
+    #
+    # File IO class is used to read and write index files.
+    # In searh mode url is used to fetch index from external repository and save it to storage.
+    # In index mode url should be nil.
+    #
+    class FileIO
+      #
+      # Initialize FileIO
+      #
+      # @param [String] dir local directory in ~/.relaton to store index
+      # @param [String, 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)
+        @dir = dir
+        @url = url
+      end
+
+      #
+      # Read index from storage or fetch from external repository
+      #
+      # @return [Array<Hash>] index
+      #
+      def read
+        if @url
+          @file ||= File.join(Index.config.storage_dir, ".relaton", @dir, "index.yaml")
+          check_file || fetch_and_save
+        else
+          @file ||= "index.yaml"
+          read_file
+        end
+      end
+
+      #
+      # Check if index file exists and is not older than 24 hours
+      #
+      # @return [Array<Hash>, nil] index or nil
+      #
+      def check_file
+        ctime = Index.config.storage.ctime(@file)
+        return unless ctime && ctime > Time.now - 86400
+
+        read_file
+      end
+
+      #
+      # Read index from storage
+      #
+      # @return [Array<Hash>] index
+      #
+      def read_file
+        yaml = Index.config.storage.read(@file)
+        return [] unless yaml
+
+        YAML.safe_load yaml, permitted_classes: [Symbol]
+      end
+
+      #
+      # Fetch index from external repository and save it to storage
+      #
+      # @return [Array<Hash>] index
+      #
+      def fetch_and_save
+        resp = URI(@url).open
+        zip = Zip::InputStream.new resp
+        entry = zip.get_next_entry
+        index = YAML.safe_load(entry.get_input_stream.read, [Symbol])
+        save index
+        index
+      end
+
+      #
+      # Save index to storage
+      #
+      # @param [Array<Hash>] index <description>
+      #
+      # @return [void]
+      #
+      def save(index)
+        Index.config.storage.write @file, index.to_yaml
+      end
+    end
+  end
+end

data/lib/relaton/index/file_storage.rb

@@ -0,0 +1,46 @@
+module Relaton
+  module Index
+    #
+    # File storage module contains methods to read and write files
+    #
+    module FileStorage
+      #
+      # Return file creation time
+      #
+      # @param [String] file file path
+      #
+      # @return [Time, nil] file creation time or nil if file does not exist
+      #
+      def ctime(file)
+        File.exist?(file) && File.ctime(file)
+      end
+
+      #
+      # Read file
+      #
+      # @param [String] file file path
+      #
+      # @return [String, nil] file content or nil if file does not exist
+      #
+      def read(file)
+        return unless File.exist?(file)
+
+        File.read file, encoding: "UTF-8"
+      end
+
+      #
+      # Write file
+      #
+      # @param [String] file file path
+      # @param [String] data content to write
+      #
+      # @return [void]
+      #
+      def write(file, data)
+        File.write file, data, encoding: "UTF-8"
+      end
+
+      extend self
+    end
+  end
+end

data/lib/relaton/index/pool.rb

@@ -0,0 +1,35 @@
+module Relaton
+  module Index
+    #
+    # Pool of indexes
+    #
+    class Pool
+      def initialize
+        @pool = {}
+      end
+
+      #
+      # Return index by type, create if not exists
+      #
+      # @param [String] type <description>
+      # @param [String, nil] url external URL to index, used to fetch index for searching files
+      #
+      # @return [Relaton::Index::Type] typed index
+      #
+      def type(type, url)
+        @pool[type.upcase.to_sym] ||= Type.new(type, url)
+      end
+
+      #
+      # Remove index by type from pool
+      #
+      # @param [String] type index type
+      #
+      # @return [void]
+      #
+      def remove(type)
+        @pool.delete type.upcase.to_sym
+      end
+    end
+  end
+end

data/lib/relaton/index/type.rb

@@ -0,0 +1,58 @@
+module Relaton
+  module Index
+    #
+    # Relaton::Index::Type is a class for indexing Relaton files.
+    #
+    class Type
+      #
+      # Initialize a new Relaton::Index::Type object
+      #
+      # @param [String, Symbol] type type of index (ISO, IEC, etc.)
+      # @param [String, nil] url external URL to index, used to fetch index for searching files
+      #
+      def initialize(type, url = nil)
+        @file_io = FileIO.new type.to_s.downcase, url
+        @index = @file_io.read
+      end
+
+      #
+      # Add or update index item
+      #
+      # @param [String] id document ID
+      # @param [String] file file name of the document
+      #
+      # @return [void]
+      #
+      def add_or_update(id, file)
+        item = @index.find { |i| i[:id] == id }
+        if item
+          item[:file] = file
+        else
+          @index << { id: id, file: file }
+        end
+      end
+
+      #
+      # Search index for a given ID
+      #
+      # @param [Comparable] id ID to search for
+      #
+      # @return [Array<Hash>] search results
+      #
+      def search(id)
+        @index.select do |i|
+          block_given? ? yield(i) : i[:id].include?(id)
+        end
+      end
+
+      #
+      # Save index to storage
+      #
+      # @return [void]
+      #
+      def save
+        @file_io.save @index
+      end
+    end
+  end
+end

data/lib/relaton/index/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Index
+    VERSION = "0.1.0"
+  end
+end

data/lib/relaton/index.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "zip"
+
+require_relative "index/version"
+require_relative "index/file_storage"
+require_relative "index/config"
+require_relative "index/pool"
+require_relative "index/type"
+require_relative "index/file_io"
+
+module Relaton
+  module Index
+    class Error < StandardError; end
+
+    class << self
+      #
+      # Find or create index
+      #
+      # @param [String] type index type (ISO, IEC, etc.)
+      # @param [String, nil] url external URL to index, used to fetch index for searching files
+      #
+      # @return [Relaton::Index::Type] typed index
+      #
+      def find_or_create(type, url: nil)
+        pool.type(type, url)
+      end
+
+      def close(type)
+        pool.remove type
+      end
+
+      #
+      # Create new index pool object or return existing
+      #
+      # @return [Relaton::Index::Pool] index pool
+      #
+      def pool
+        @pool ||= Pool.new
+      end
+
+      #
+      # Create new config object or return existing
+      #
+      # @return [Relaton::Index::Config] config object
+      #
+      def config
+        @config ||= Config.new
+      end
+
+      #
+      # Configure Relaton::Index
+      #
+      # @return [void]
+      #
+      def configure
+        yield config
+      end
+    end
+  end
+end

data/relaton-index.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/relaton/index/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "relaton-index"
+  spec.version = Relaton::Index::VERSION
+  spec.authors = ["Ribose Inc."]
+  spec.email = ["open.source@ribose.com"]
+
+  spec.summary = "Relaton Index is a library for indexing Relaton files."
+  spec.homepage = "https://github.com/relaton/relaton-index"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rubyzip", "~> 2.3.0"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/sig/relaton/index.rbs

@@ -0,0 +1,6 @@
+module Relaton
+  module Index
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: relaton-index
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ribose Inc.
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2023-03-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+description: 
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- Gemfile
+- LICENSE.txt
+- README.adoc
+- Rakefile
+- lib/relaton/index.rb
+- lib/relaton/index/config.rb
+- lib/relaton/index/file_io.rb
+- lib/relaton/index/file_storage.rb
+- lib/relaton/index/pool.rb
+- lib/relaton/index/type.rb
+- lib/relaton/index/version.rb
+- relaton-index.gemspec
+- sig/relaton/index.rbs
+homepage: https://github.com/relaton/relaton-index
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/relaton/relaton-index
+  source_code_uri: https://github.com/relaton/relaton-index
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: Relaton Index is a library for indexing Relaton files.
+test_files: []