= RelatonIso: retrieve ISO Standards for bibliographic use using the BibliographicItem model

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

RelatonIso 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 ISO Standards from https://www.iso.org, and access such metadata through the `IsoBibliographicItem` object.

== Installation

Add this line to your application's Gemfile:

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

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install relaton-iso

== Usage

=== Search for standards using keywords

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

hit_collection = RelatonIso::IsoBibliography.search("ISO 19115")
=> <RelatonIso::HitCollection:0x007fa5bc847038 @ref=19115 @fetched=false>

hit_collection.first
=> <RelatonIso::Hit:0x007f87e71ea9f8 @text="ISO 19115" @fetched="false" @fullIdentifier="" @title="">

item = hit_collection[2].fetch
=> #<RelatonIsoBib::IsoBibliographicItem:0x007fa5dca89510
 @abstract=
  [#<RelatonBib::FormattedString:0x007fa5dca88458
    @content=
     "ISO/TS 19115-3:2016 defines an integrated XML implementation of ISO 19115‑1, ..."
...

item.docidentifier
=> [#<RelatonBib::DocumentIdentifier:0x007fd9ce9c6878 @id="ISO/TS 19115-3:2016", @scope=nil, @type="ISO">,
 #<RelatonBib::DocumentIdentifier:0x007fd9ce9c6350 @id="urn:iso:std:iso-ts:ts:19115:-3:stage-90.92:ed-1:en,fr", @scope=nil, @type="URN">]

 item.docidentifier.detect { |di| di.type == "URN" }.id
=> "urn:iso:std:iso-ts:ts:19115:-3:stage-90.92:ed-1:en,fr"
----

=== Fetch document by reference and year

[source,ruby]
----
item = RelatonIso::IsoBibliography.get "ISO 19115:2003"
[relaton-iso] ("ISO 19115:2003") fetching...
[relaton-iso] ("ISO 19115:2003") found ISO 19115:2003
=> #<RelatonIsoBib::IsoBibliographicItem:0x00007f8c83429e30
...

item = RelatonIso::IsoBibliography.get "ISO 19115", "2003"
[relaton-iso] ("ISO 19115") fetching...
[relaton-iso] ("ISO 19115") found ISO 19115:2003
=> #<RelatonIsoBib::IsoBibliographicItem:0x00007f8c828d3180
...

item.docidentifier[0].id
=> "ISO 19115:2003"
----

=== Fetch non-part document

[source,ruby]
----
item = RelatonIso::IsoBibliography.get "ISO 19115"
[relaton-iso] ("ISO 19115") fetching...
[relaton-iso] ("ISO 19115") found ISO 19115:2003
=> #<RelatonIsoBib::IsoBibliographicItem:0x00007f8c830275a8
...

item.docidentifier[0].id
=> "ISO 19115:2003"
----

=== Fetch part document

[source,ruby]
----
item = RelatonIso::IsoBibliography.get "ISO 19115-1"
[relaton-iso] ("ISO 19115-1") fetching...
[relaton-iso] ("ISO 19115-1") found ISO 19115-1:2014
=> #<RelatonIsoBib::IsoBibliographicItem:0x00007f8c83408af0
...

item.docidentifier[0].id
=> "ISO 19115-1:2014"
----

=== Fetch all-parts document

[source,ruby]
----
item = RelatonIso::IsoBibliography.get "ISO 19115 (all parts)"
[relaton-iso] ("ISO 19115") fetching...
[relaton-iso] ("ISO 19115") found ISO 19115 (all parts)
=> #<RelatonIsoBib::IsoBibliographicItem:0x00007f8ca216e118
...

item = RelatonIso::IsoBibliography.get "ISO 19115", nil, all_parts: true
[relaton-iso] ("ISO 19115") fetching...
[relaton-iso] ("ISO 19115") found ISO 19115 (all parts)
=> #<RelatonIsoBib::IsoBibliographicItem:0x00007f8c830f3d38
...

item.docidentifier[0].id
=> "ISO 19115 (all parts)"

item = RelatonIso::IsoBibliography.get "ISO 19115-1 (all parts)"
[relaton-iso] ("ISO 19115-1") fetching...
[relaton-iso] ("ISO 19115-1") found ISO 19115 (all parts)
=> #<RelatonIsoBib::IsoBibliographicItem:0x00007f8c8290e5a0

item = RelatonIso::IsoBibliography.get "ISO 19115-1", nil, all_parts: true
[relaton-iso] ("ISO 19115-1") fetching...
[relaton-iso] ("ISO 19115-1") found ISO 19115 (all parts)
=> #<RelatonIsoBib::IsoBibliographicItem:0x00007f8c925355b8
...

item.docidentifier[0].id
=> "ISO 19115 (all parts)"
----

=== Search for ISO/IEC Directives

The ISO/IEC Derectives are stored in a static cache in a relaton gem. It needs to use the relaton gem to fetch the ISO/IEC Directives. Folloving reaferences are allowed to fetch:

- ISO/IEC DIR 1 - Procedures for the technical work
- ISO/IEC DIR 1 IEC SUP - Procedures for the technical work – Procedures specific to IEC
- ISO/IEC DIR 1 ISO SUP - Consolidated ISO Supplement -- Procedures specific to ISO
- ISO/IEC DIR 2 IEC - Principles and rules for the structure and drafting of ISO and IEC documents
- ISO/IEC DIR 2 ISO - Principles and rules for the structure and drafting of ISO and IEC documents
- ISO/IEC DIR IEC SUP - Procedures specific to IEC
- ISO/IEC DIR JTC 1 SUP - Procedures specific to JTC 1

=== XML serialization

Possible options:

- *bibdata* - If true then wrapp item with _bibdata_ element and add _ext_ element.
- *note* - Array of hashes `{ text: "Note", type: "note" }`. These notes will be added to XML.

[source,ruby]
----
item.to_xml
"<bibitem id="ISO/TS19115-3-2016" type="standard">
  <fetched>2020-09-11</fetched>
  <title type="title-intro" format="text/plain" language="en" script="Latn">Geographic information</title>
  <title type="title-main" format="text/plain" language="en" script="Latn"> Metadata</title>
  <title type="title-part" format="text/plain" language="en" script="Latn">Part 3: XML schema implementation for fundamental concepts</title>
  <title type="main" format="text/plain" language="en" script="Latn">Geographic information -  Metadata - Part 3: XML schema implementation for fundamental concepts</title>
  <title type="title-intro" format="text/plain" language="fr" script="Latn">Information géographique</title>
  <title type="title-main" format="text/plain" language="fr" script="Latn">Métadonnées</title>
  <title type="title-part" format="text/plain" language="fr" script="Latn">Partie 3: Mise en oeuvre par des schémas XML</title>
  <title type="main" format="text/plain" language="fr" script="Latn">Information géographique - Métadonnées - Partie 3: Mise en oeuvre par des schémas XML</title>
  <uri type="src">https://www.iso.org/standard/32579.html</uri>
  <uri type="obp">https://www.iso.org/obp/ui/#!iso:std:32579:en</uri>
  <uri type="rss">https://www.iso.org/contents/data/standard/03/25/32579.detail.rss</uri>
  <docidentifier type="ISO">ISO/TS 19115-3:2016</docidentifier>
  <docidentifier type="URN">urn:iso:std:iso-ts:ts:19115:-3:stage-90.92:ed-1:en,fr</docidentifier>
  ...
</bibitem>"

item.to_xml bibdata: true
=>"<bibdata type="standard">
  ...
  <ext>
    <doctype>technical-specification</doctype>
    <editorialgroup>
      <technical-committee number="211" type="TC">ISO/TC 211Geographic information/Geomatics</technical-committee>
    </editorialgroup>
    <ics>
      <code>35.240.70</code>
      <text>IT applications in science</text>
    </ics>
    <structuredidentifier type="ISO">
      <project-number>ISO/TS 19115</project-number>
    </structuredidentifier>
  </ext>
</bibdata>"

item.to_xml note: [{ text: "Note", type: "note" }]
=>"<bibitem id="ISO19115-1-2014">
  ...
  <note format="text/plain" type="note">Note</note>
  ...
</bibitem>"
----

=== Get specific language

[source,ruby]
----
item.title lang: 'en'
=> [#<RelatonBib::TypedTitleString:0x007fd9aedcf390
  @title=#<RelatonBib::FormattedString:0x007fd9aedcf250 @content="Geographic information", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-intro">,
 #<RelatonBib::TypedTitleString:0x007fd9aedcf188
  @title=#<RelatonBib::FormattedString:0x007fd9aedcf048 @content=" Metadata", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-main">,
 #<RelatonBib::TypedTitleString:0x007fd9aedcef80
  @title=#<RelatonBib::FormattedString:0x007fd9aedcee40 @content="Part 3: XML schema implementation for fundamental concepts", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-part">,
 #<RelatonBib::TypedTitleString:0x007fd9aedcecb0
  @title=
   #<RelatonBib::FormattedString:0x007fd9aedceb70
    @content="Geographic information -  Metadata - Part 3: XML schema implementation for fundamental concepts",
    @format="text/plain",
    @language=["en"],
    @script=["Latn"]>,
  @type="main">]

item.title lang: 'fr'
=> [#<RelatonBib::TypedTitleString:0x007fd9ce9c7890
  @title=#<RelatonBib::FormattedString:0x007fd9ce9c7750 @content="Information géographique", @format="text/plain", @language=["fr"], @script=["Latn"]>,
  @type="title-intro">,
 #<RelatonBib::TypedTitleString:0x007fd9ce9c7688
  @title=#<RelatonBib::FormattedString:0x007fd9ce9c7548 @content="Métadonnées", @format="text/plain", @language=["fr"], @script=["Latn"]>,
  @type="title-main">,
 #<RelatonBib::TypedTitleString:0x007fd9ce9c7480
  @title=#<RelatonBib::FormattedString:0x007fd9ce9c7340 @content="Partie 3: Mise en oeuvre par des schémas XML", @format="text/plain", @language=["fr"], @script=["Latn"]>,
  @type="title-part">,
 #<RelatonBib::TypedTitleString:0x007fd9ce9c71b0
  @title=
   #<RelatonBib::FormattedString:0x007fd9ce9c7070
    @content="Information géographique - Métadonnées - Partie 3: Mise en oeuvre par des schémas XML",
    @format="text/plain",
    @language=["fr"],
    @script=["Latn"]>,
  @type="main">]

  item.abstract lang: 'en'
=> #<RelatonBib::FormattedString:0x007fd9ce9d9bd0
 @content=
  "ISO/TS 19115-3:2016 defines an integrated XML implementation of ISO 19115‑1, ISO 19115‑2, and concepts ..."
 @format="text/plain",
 @language=["en"],
 @script=["Latn"]>
----

=== Typed links

Each ISO document has `src` type link and optional `obp`, `rss`, and `pub` link types.

[source,ruby]
----
item.link
=> [#<RelatonBib::TypedUri:0x00007ffdf001eb90 @content=#<Addressable::URI:0xaa0 URI:https://www.iso.org/standard/53798.html>, @type="src">,
 #<RelatonBib::TypedUri:0x00007ffdf001e960 @content=#<Addressable::URI:0xab4 URI:https://www.iso.org/obp/ui/#!iso:std:53798:en>, @type="obp">,
 #<RelatonBib::TypedUri:0x00007ffdf001e7a8 @content=#<Addressable::URI:0xac8 URI:https://www.iso.org/contents/data/standard/05/37/53798.detail.rss>, @type="rss">]
----

== 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).


== Exceptional Citations

This gem retrieves bibliographic descriptions of ISO documents by doing searches on the ISO website, http://www.iso.org, and screenscraping the document that matches the queried document identifier. The following documents are not returned as search results from the ISO website, and the gem returns manually generated references to them.

* `IEV`: used in the metanorma-iso gem to reference Electropedia entries generically. Is resolved to an "all parts" reference to IEC 60050, which in turn is resolved into the specific documents cited by their top-level clause.

== Contributing

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

== License

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