= 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 [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" # 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, file: "index.yaml" # Remove the index from the pool. Relaton::Index.close :IHO ---- 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 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 "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 ---- === 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. The URL can be specified as `true` if the index should not be fetched from the URL. [source,ruby] ---- # 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 is saved as `index.yaml` file to the `/[HOME]/.relaton/iho/` folder. If the URL is specified as `true`, the index won't be fetched from the URL. 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 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" }] ---- === Remove all index records This method removes all records from the index object. The index file is not removed. [source,ruby] ---- index.remove_all ---- === Remove index file This method removes the index file. The index object is cleared and can be used for indexing or loading a file from the specified URL. [source,ruby] ---- index.remove_file ---- === Configuration The gem can be configured by using the `Relaton::Index.config` method. The following settings are available: - `filename` - the name of the index file. By default, it is `index.yaml`. - `storage` - the storage class or module. By default, it is `FileStorage` module. It can be any class or module that implements the `ctime`, `read`, and `write` class methods. - `storage_dir` - the directory where the `.relaton/[TYPE]` folder is created. By default, it's a user's home dir. This setting works only when the gem is used for searching. When indexing, the index is always saved in a current folder. [source,ruby] ---- Relaton::Index.config do |config| config.filename = "index-new.yaml" config.storage = S3Storage config.storage_dir = "/" 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" ---- == 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).