= RelatonItu: retrieve ITU Standards for bibliographic use using the BibliographicItem model

image:https://img.shields.io/gem/v/relaton-bib.svg["Gem Version", link="https://rubygems.org/gems/relaton-bib"]
image:https://travis-ci.com/metanorma/relaton-bib.svg?branch=master["Build Status", link="https://travis-ci.com/metanorma/relaton-bib"]
image:https://ci.appveyor.com/api/projects/status/fd39m2762jo8ve04?svg=true["Appveyor Build Status", link="https://ci.appveyor.com/project/ribose/relaton-bib"]

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

== Installation

Add this line to your application's Gemfile:

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

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install relaton-bib

== Usage

=== Search for a standard using keywords

[source,ruby]
----
require 'relaton_bib'

hit_collection = RelatonItu::ItuBibliography.search("ITU-T L.163")
=> [<RelatonItu::Hit:0x007fe50780a270 @text="ITU-T L.163" @fetched="false" @fullIdentifier="" @title="ITU-T L.163 (11/2018)">,
 <RelatonItu::Hit:0x007fe50780a220 @text="ITU-T L.163" @fetched="false" @fullIdentifier="" @title="ITU-T J.163 (12/2007)">,
 <RelatonItu::Hit:0x007fe50780a1d0 @text="ITU-T L.163" @fetched="false" @fullIdentifier="" @title="ITU-T F.163 (08/1992)">,
 <RelatonItu::Hit:0x007fe50780a180 @text="ITU-T L.163" @fetched="false" @fullIdentifier="" @title="ITU-T J.163 (11/2005)">,
 <RelatonItu::Hit:0x007fe50780a130 @text="ITU-T L.163" @fetched="false" @fullIdentifier="" @title="ITU-T J.163 (03/2004)">,
 <RelatonItu::Hit:0x007fe50780a0e0 @text="ITU-T L.163" @fetched="false" @fullIdentifier="" @title="ITU-T Q.163 (11/1988)">,
 <RelatonItu::Hit:0x007fe50780a090 @text="ITU-T L.163" @fetched="false" @fullIdentifier="" @title="ITU-T J.163 (03/2001)">,
 <RelatonItu::Hit:0x007fe50780a040 @text="ITU-T L.163" @fetched="false" @fullIdentifier="" @title="ITU-T F.163 (07/1996)">,
 <RelatonItu::Hit:0x007fe507809ff0 @text="ITU-T L.163" @fetched="false" @fullIdentifier="" @title="ITU-T X.163 (04/1995)">,
 <RelatonItu::Hit:0x007fe507809fa0 @text="ITU-T L.163" @fetched="false" @fullIdentifier="" @title="ITU-T O.163 (11/1988)">]

 item = hit_collection[1].fetch
 => #<RelatonItu::ItuBibliographicItem:0x007fe5024f3028
 ...
----

=== XML serialization
[source,ruby]
----
item.to_xml
=> "<bibitem id="ITU-TJ.163(12/2007)">
  <fetched>2019-06-07</fetched>
  <title type="title-main" format="text/plain" language="en" script="Latn">ITU-T J.163 (12/2007): Dynamic quality of service for the provision of real-time services over cable television networks using cable modems</title>
  <title type="main" format="text/plain" language="en" script="Latn">ITU-T J.163 (12/2007): Dynamic quality of service for the provision of real-time services over cable television networks using cable modems</title>
  <uri type="src">https://www.itu.int/net4/ITU-T/search/api/redirection?dest=http%3A%2F%2Fhandle.itu.int%2F11.1002%2F1000%2F9306-en&amp;position=9&amp;page=1</uri>
  <uri type="obp">https://www.itu.int/rec/T-REC-J.163-200712-I</uri>
  <docidentifier type="ITU">ITU-T J.163 (12/2007)</docidentifier>
  <date type="published">
    <on>2007</on>
  </date>
  <contributor>
    <role type="publisher"/>
    <organization>
      <name>International Telecommunication Union</name>
      <abbreviation>ITU</abbreviation>
      <uri>www.itu.int</uri>
    </organization>
  </contributor>
  <edition>4</edition>
  <language>en</language>
  <script>Latn</script>
  <abstract format="text/plain" language="en" script="Latn">ITU-T Recommendation J.163 addresses requirements for a client device to obtain access to network resources. In particular, it specifies a comprehensive mechanism for a client device to request a specific quality of service from the DOCSIS network. Extensive examples illustrate the use of this Recommendation. The scope of this Recommendation is to define the QoS architecture for the "Access" portion of the IPCablecom network, provided to requesting applications on a per-flow basis. The access portion of the network is defined to be between the multimedia terminal adapter (MTA) and the cable modem termination system (CMTS), including the DOCSIS network. The method of QoS allocation over the backbone is unspecified in this Recommendation. Interface to the managed IP backbone and issues related to IP multicast are not within the scope of this Recommendation. This Recommendation also recognizes that per-flow reservations may be required within the customer premises, and the protocol developed addresses this potential need.</abstract>
  <status>
    <stage>Published</stage>
  </status>
  <copyright>
    <from>2007</from>
    <owner>
      <organization>
        <name>International Telecommunication Union</name>
        <abbreviation>ITU</abbreviation>
        <uri>www.itu.int</uri>
      </organization>
    </owner>
  </copyright>
  <relation type="published">
    <bibitem id="JSuppl.1(11/1998)">
      <formattedref format="text/plain" language="en" script="Latn">J Suppl. 1 (11/1998)</formattedref>
    </bibitem>
  </relation>
  <relation type="published">
    <bibitem id="JSuppl.2(11/1998)">
      <formattedref format="text/plain" language="en" script="Latn">J Suppl. 2 (11/1998)</formattedref>
    </bibitem>
  </relation>
  <relation type="published">
    <bibitem id="JSuppl.3(11/1998)">
      <formattedref format="text/plain" language="en" script="Latn">J Suppl. 3 (11/1998)</formattedref>
    </bibitem>
  </relation>
  <relation type="published">
    <bibitem id="JSuppl.5(09/1999)">
      <formattedref format="text/plain" language="en" script="Latn">J Suppl. 5 (09/1999)</formattedref>
    </bibitem>
  </relation>
  <relation type="published">
    <bibitem id="JSuppl.6(09/2016)">
      <formattedref format="text/plain" language="en" script="Latn">J Suppl. 6 (09/2016)</formattedref>
    </bibitem>
  </relation>
</bibitem>"
----
With `bibdata: true` option XML output wrapped with `bibdata` element and `ext` element added.
[source,ruby]
----
item.to_xml bibdata: true
=> "<bibdata>
  <fetched>2019-06-07</fetched>
  ...
  <ext>
    <doctype>recommendation</doctype>
    <editorialgroup>
      <bureau>T</bureau>
      <group type="study-group">
        <name>ITU-T Study Group 9</name>
        <acronym>SG</acronym>
      </group>
    </editorialgroup>
  </ext>
</bibdata>"
----

=== Get code, and year
[source,ruby]
----
RelatonItu::ItuBibliography.get("ITU-T L.163", "2018", {})
fetching ITU-T L.163...
=> #<RelatonItu::ItuBibliographicItem:0x007fe502509dc8
...
----

=== Create bibliographic item form YAML
[source,ruby]
----
hash = YAML.load_file 'spec/examples/itu_bib_item.yml'
=> {"id"=>"ITU-T L.163 (11/2018)",
...

bib_hash = RelatonItu::HashConverter.hash_to_bib hash
=> {:id=>"ITU-T L.163 (11/2018)",
...

RelatonItu::ItuBibliographicItem.new bib_hash
=> #<RelatonItu::ItuBibliographicItem:0x007fd88ac02aa0
...
----

== 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/metanorma/relaton-bib.

== License

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