= Relaton-DOI: retrieve bibliographic items using DOI

image:https://img.shields.io/gem/v/relaton-doi.svg["Gem Version", link="https://rubygems.org/gems/relaton-doi"]
image:https://github.com/relaton/relaton-doi/workflows/macos/badge.svg["Build Status (macOS)", link="https://github.com/relaton/relaton-doi/actions?workflow=macos"]
image:https://github.com/relaton/relaton-doi/workflows/windows/badge.svg["Build Status (Windows)", link="https://github.com/relaton/relaton-doi/actions?workflow=windows"]
image:https://github.com/relaton/relaton-doi/workflows/ubuntu/badge.svg["Build Status (Ubuntu)", link="https://github.com/relaton/relaton-doi/actions?workflow=ubuntu"]
image:https://codeclimate.com/github/relaton/relaton-doi/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/relaton/relaton-doi"]
image:https://img.shields.io/github/issues-pr-raw/relaton/relaton-doi.svg["Pull Requests", link="https://github.com/relaton/relaton-doi/pulls"]
image:https://img.shields.io/github/commits-since/relaton/relaton-doi/latest.svg["Commits since latest",link="https://github.com/relaton/relaton-doi/releases"]

RelatonDoi is a Ruby gem that implements the
https://github.com/metanorma/metanorma-model-iso#iso-bibliographic-item[IsoBibliographicItem model].

You can use it to retrieve metadata of Standards from https://crossref.org, and
access such metadata through the `BibliographicItem` object.

To collect metadata this gem makes a few requests to the CrossRef API. It may take a few seconds to get the metadata.

== Installation

Add this line to your application's Gemfile:

[source,ruby]
----
gem 'relaton-doi'
----

And then execute:

[source,sh]
----
$ bundle install
----

Or install it yourself as:

[source,ruby]
----
$ gem install relaton-doi
----

== Usage

=== Configuration

Configuration is optional. The available option is `logger` which is a `Logger` instance. By default, the logger is `Logger.new($stderr)` with `Logger::WARN` level. To change the logger level, use `RelatonDoi.configure` block.

[source,ruby]
----
require 'relaton_doi'
=> true

RelatonDoi.configure do |config|
  config.logger.level = Logger::DEBUG
end
----

=== Retrieving items of known type using DOI

If the resulting bibliographic item returned from CrossRef is a known Relaton
flavor, such as a NIST or IEEE standard, the corresponding Relaton class object
will be returned via the call.

[source,ruby]
----
require 'relaton_doi'
=> true

# get NIST standard
RelatonDoi::Crossref.get "doi:10.6028/nist.ir.8245"
[relaton-doi] (doi:10.6028/nist.ir.8245) Fetching from search.crossref.org ...
[relaton-doi] (doi:10.6028/nist.ir.8245) Found: `10.6028/nist.ir.8245`
=> #<RelatonNist::NistBibliographicItem:0x00007ff22420d820
...

# get RFC standard
RelatonDoi::Crossref.get "doi:10.17487/RFC0001"
[relaton-doi] (doi:10.17487/RFC0001) Fetching from search.crossref.org ...
[relaton-doi] (doi:10.17487/RFC0001) Found: `10.17487/rfc0001`
[relaton-ietf] WARNING: Invalid doctype report
=> #<RelatonIetf::IetfBibliographicItem:0x00007ff2241be6d0
...

# get BIPM standard
RelatonDoi::Crossref.get "doi:10.1088/0026-1394/29/6/001"
[relaton-doi] (doi:10.1088/0026-1394/29/6/001) Fetching from search.crossref.org ...
[relaton-doi] (doi:10.1088/0026-1394/29/6/001) Found: `10.1088/0026-1394/29/6/001`
=> #<RelatonBipm::BipmBibliographicItem:0x00007f9c846f0a68
...

# get IEEE standard
RelatonDoi::Crossref.get "doi:10.1109/ieeestd.2014.6835311"
[relaton-doi] (doi:10.1109/ieeestd.2014.6835311) Fetching from search.crossref.org ...
[relaton-doi] (doi:10.1109/ieeestd.2014.6835311) Found: `10.1109/ieeestd.2014.6835311`
=> #<RelatonIeee::IeeeBibliographicItem:0x00007f9cb46db688
...
----

=== Retrieving items of unknown types via DOI

If the resulting bibliographic item returned from CrossRef is of an unknown type
to Relaton, an instance of RelatonBib::BibliographicItem will be returned.

[source,ruby]
----
RelatonDoi::Crossref.get "doi:10.1109/ACCESS.2017.2739804"
[relaton-doi] (doi:10.1109/ACCESS.2017.2739804) Fetching from search.crossref.org ...
[relaton-doi] (doi:10.1109/ACCESS.2017.2739804) Found: `10.1109/access.2017.2739804`
=> #<RelatonBib::BibliographicItem:0x00007ff22435e490
...
----


== 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
https://rubygems.org[rubygems.org].

== Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/relaton/relaton-doi.

== License

The gem is available as open source under the terms of the https://opensource.org/licenses/MIT[MIT License].