= RelatonBipm: retrieve BIPM Standards for bibliographic use using the BibliographicItem model

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

RelatonBipm 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 BIPM Standards from https://www.bipm.org, and access such metadata through the `BipmBibliographicItem` object.

== Installation

Add this line to your application's Gemfile:

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

And then execute:

    $ bundle install

Or install it yourself as:

    $ gem install relaton-bipm

== Usage

=== Search for a standard using keywords

==== References for Si-Brochure documents

`BIPM {DOCUMENT_NAME}`

Allowed document names are:

- CCEM-GD-RSI-1
- CCL-GD-MeP-1
- CCL-GD-MeP-2
- CCL-GD-MeP-3
- CCM-GD-RSI-1
- CCM-GD-RSI-2
- SI MEP A1
- SI MEP Cd1
- Rapport BIPM-2019/05
- SI MEP KUPRTM
- SI MEP KAPRT
- SI MEP K1
- SI MEP KLJNT
- SI MEP KRPRT
- SI MEP Kg1
- SI MEP M1
- SI MEP Mol1
- SI MEP S1
- SI Brochure

==== Reference structire for Metrologia documents

`BIPM Metrologia {JOURNAL} {VOLUME} {ISSUE} {PAGE}`

- `{JOURNAL}` - number of journal, required
- `{VOLUME}` - number of volume, optional
- `{ISSUE}` - number of issue, optional
- `{PAGE}` - number of page, optional

==== Reference structures for CCTF (CCDS), CGMP, CIPM documents

- `{BODY} {TYPE} {YEAR}-{2_DIGITS_NUMBER}`
- `{BODY} {TYPE} {NUMBER} ({YEAR})` or `{BODY} {TYPE} {NUMBER} {YEAR}`
- `{BODY} {TYPE} {MEETING_NUMBER}-{2_DIGITS_NUMBER}`
- `{BODY} {TYPE} ({YEAR})` or `{BODY} {TYPE} {YEAR}` - in case only one Resolution/Decision/Declaration/Recommendation is available for the year
- `{BODY} Meeting {MEETING_NUMBER}` or French version `{BODY} Réunion {MEETING_NUMBER}`

The parts of the structures:

- `{BODY}` - could be `CCTF` (or old named `CCDS`), CGMP, or CIMP
- `{TYPE}` - could be English word: `Resolution`, `Decision`, `Declaration`, `Recommendation`; or French word: `Résolution`, `Décision`, `Déclaration`, `Recommandation`
- `{YEAR}` - year of Resolution/Decision/Declaration/Recommendation
- `{NUMBER}` - number of Resolution/Decision/Declaration/Recommendation
- `{2_DIGITS_NUMBER}` - two digits number of Resolution/Decision/Declaration/Recommendatio with lead zero if needs
- `{MEETING_NUMBER}` - number of mieeting

==== Examples

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

# get BIPM brochure
item = RelatonBipm::BipmBibliography.get "BIPM SI Brochure"
[relaton-bipm] ("BIPM SI Brochure") fetching...
[relaton-bipm] ("BIPM SI Brochure") found BIPM SI Brochure
=> #<RelatonBipm::BipmBibliographicItem:0x007ffb83982fe8
...

# get BIPM Metrologia page
bib = RelatonBipm::BipmBibliography.get "BIPM Metrologia 29 6 373"
[relaton-bipm] ("BIPM Metrologia 29 6 373") fetching...
[relaton-bipm] ("BIPM Metrologia 29 6 373") found Metrologia 29 6 373
=> #<RelatonBipm::BipmBibliographicItem:0x007f8857f94d40
...

# get CGPM meetings
RelatonBipm::BipmBibliography.get "CGPM Meeting 1"
[relaton-bipm] ("CGPM Meeting 1") fetching...
[relaton-bipm] ("CGPM Meeting 1") found CGPM Meeting 1
=> #<RelatonBipm::BipmBibliographicItem:0x00007fd4f7cba038
...

# get CGPM resolutions
RelatonBipm::BipmBibliography.get "CGPM Resolution 1889-00"
[relaton-bipm] ("CGPM Resolution 1889-00") fetching...
[relaton-bipm] ("CGPM Resolution 1889-00") found CGPM Resolution (1889)
=> #<RelatonBipm::BipmBibliographicItem:0x00007ff0d1ffae50
...

RelatonBipm::BipmBibliography.get "CGPM Resolution (1889)"
[relaton-bipm] ("CGPM Resolution (1889)") fetching...
[relaton-bipm] ("CGPM Resolution (1889)") found CGPM Resolution (1889)
=> #<RelatonBipm::BipmBibliographicItem:0x00007ff0d1ffae50
...

RelatonBipm::BipmBibliography.get "CGPM Resolution 1889"
[relaton-bipm] ("CGPM Resolution 1889") fetching...
[relaton-bipm] ("CGPM Resolution 1889") found CGPM Resolution (1889)
=> #<RelatonBipm::BipmBibliographicItem:0x00007ff0d1ffae50
...

# get CIPM decision by year and decision number
RelatonBipm::BipmBibliography.get "CIPM Decision 2012-01"
[relaton-bipm] ("CIPM Decision 2012-01") fetching...
[relaton-bipm] ("CIPM Decision 2012-01") found CIPM Decision 1 (2012)
=> #<RelatonBipm::BipmBibliographicItem:0x00007ff0f10dc548
...

RelatonBipm::BipmBibliography.get "CIPM Decision 1 (2012)"
[relaton-bipm] ("CIPM Decision 1 (2012)") fetching...
[relaton-bipm] ("CIPM Decision 1 (2012)") found CIPM Decision 1 (2012)
=> #<RelatonBipm::BipmBibliographicItem:0x00007fb6b9bbec08
...

# get CIPM decision by meeting number and decision number
RelatonBipm::BipmBibliography.get "CIPM Decision 101-01"
[relaton-bipm] ("CIPM Decision 101-01") fetching...
[relaton-bipm] ("CIPM Decision 101-01") found CIPM Decision 1 (2012)
=> #<RelatonBipm::BipmBibliographicItem:0x00007f9ef2acc400
...

# get CIPM recommendation
RelatonBipm::BipmBibliography.get "CIPM Recommendation (1948)"
[relaton-bipm] ("CIPM Recommendation (1948)") fetching...
[relaton-bipm] ("CIPM Recommendation (1948)") found CIPM Recommendation (1948)
=> #<RelatonBipm::BipmBibliographicItem:0x00007ff0a18a6aa8
...

RelatonBipm::BipmBibliography.get "CIPM Recommendation 1948"
[relaton-bipm] ("CIPM Recommendation 1948") fetching...
[relaton-bipm] ("CIPM Recommendation 1948") found CIPM Recommendation (1948)
=> #<RelatonBipm::BipmBibliographicItem:0x00007ff0f1164150
...
----

=== XML serialization

[source,ruby]
----
item.to_xml
=> "<bibitem id="BIPMSIBrochure" type="standard">
      <fetched>2021-01-10</fetched>
      <title format="text/plain" language="en" script="Latn">The International System of Units (SI)</title>
      <title format="text/plain" language="fr" script="Latn">Le Système international d’unités (SI)</title>
      <uri type="src">https://www.bipm.org/en/publications/si-brochure</uri>
      <docidentifier type="BIPM">BIPM SI Brochure</docidentifier>
      <date type="updated">
        <on>2019-05-20</on>
      </date>
      <edition>9</edition>
      <abstract format="text/plain" language="en" script="Latn">The BIPM and the Metre Convention</abstract>
      <abstract format="text/plain" language="fr" script="Latn">Le BIPM et la Convention du Mètre</abstract>
      <copyright>
        <from>2019</from>
        <owner>
          <organization>
            <name>Bureau International des ponds et mesures</name>
            <abbreviation>BIPM</abbreviation>
          </organization>
        </owner>
      </copyright>
    </bibitem>"
----

With argument `bibdata: true` it ouputs XML wrapped by `bibdata` element and adds flavour `ext` element.

[source,ruby]
----
item.to_xml bibdata: true
=> "<bibdata type="standard">
      <fetched>2021-01-10</fetched>
      <title format="text/plain" language="en" script="Latn">The International System of Units (SI)</title>
      <title format="text/plain" language="fr" script="Latn">Le Système international d’unités (SI)</title>
      <uri type="src">https://www.bipm.org/en/publications/si-brochure</uri>
      <docidentifier type="BIPM">BIPM SI Brochure</docidentifier>
      <date type="updated">
        <on>2019-05-20</on>
      </date>
      <edition>9</edition>
      <abstract format="text/plain" language="en" script="Latn">The BIPM and the Metre Convention</abstract>
      <abstract format="text/plain" language="fr" script="Latn">Le BIPM et la Convention du Mètre</abstract>
      <copyright>
        <from>2019</from>
        <owner>
          <organization>
            <name>Bureau International des ponds et mesures</name>
            <abbreviation>BIPM</abbreviation>
          </organization>
        </owner>
      </copyright>
      <ext>
        <doctype>brochure</doctype>
      </ext>
    </bibdata>"
----

=== Typed links

Each BIPM document has `src` type link and optional `doi` type link.

[source,ruby]
----
bib.link
=> [#<RelatonBib::TypedUri:0x00007fa6d6a51728 @content=#<Addressable::URI:0xc29c URI:https://iopscience.iop.org/article/10.1088/0026-1394/29/6/001>, @type="src">,
 #<RelatonBib::TypedUri:0x00007fa6d6a29250 @content=#<Addressable::URI:0xc2b0 URI:https://doi.org/10.1088/0026-1394/29/6/001>, @type="doi">]
----

=== Create bibliographic item from XML

[source,ruby]
----
RelatonBipm::XMLParser.from_xml File.read('spec/fixtures/bipm_item.xml')
=> #<RelatonBipm::BipmBibliographicItem:0x007ffb83827a90
...
----

=== Create bibliographic item from YAML
[source,ruby]
----
hash = YAML.load_file 'spec/fixtures/bipm_item.yml'
=> {"id"=>"Draft-Agenda-NMI-Dir-Meeting-2017-v10",
...

RelatonBipm::BipmBibliographicItem.from_hash hash
=> #<RelatonBipm::BipmBibliographicItem:0x007ffb668755a0
...
----

=== Fetch data

This gem uses following datasets as data sources:
- `bipm-data-outcomes` - looking for local directory with the repository https://github.com/metanorma/bipm-data-outcomes
- `bipm-si-brochute` - looking for local directory with the repository https://github.com/metanorma/bipm-si-brochure

The method `RelatonBipm::DataFetcher.fetch(sourece, output: "data", format: "yaml")` fetches all the documents from the datast and save them to the `./data` folder in YAML format.
Arguments:

- `source` - name of the source dataset
- `output` - folder to save documents (default './data').
- `format` - format in which the documents are saved. Possimle formats are: `yaml`, `xml`, `bibxxml` (default `yaml`).

[source,ruby]
----
RelatonBipm::DataFetcher.fetch "bipm-data-outcomes"
Started at: 2022-06-23 09:36:55 +0200
Stopped at: 2022-06-23 09:36:58 +0200
Done in: 2 sec.
=> nil

RelatonBipm::DataFetcher.fetch "bipm-si-brochure"
Started at: 2022-06-23 09:37:12 +0200
Stopped at: 2022-06-23 09:37:12 +0200
Done in: 0 sec.
=> nil
----

== 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 tags, 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-bipm.


== License

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