= RelatonNist: retrieve NIST Standards for bibliographic use using the BibliographicItem model

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


RelatonNist 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 NIST Standards from https://csrc.nist.gov, and access such metadata through the `IsoBibliographicItem` object.

== Installation

Add this line to your application's Gemfile:

[source,ruby]
----
gem 'relaton_nist'
----

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install relaton_nist

== Usage

=== Search for a standard using keywords

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

hit_collection = RelatonNist::NistBibliography.search("8200")
=> <RelatonNist::HitCollection:0x007fc069d19da0 @ref=8200 @fetched=false>

 item = hit_collection[1].fetch
=> #<RelatonNist::NistBibliographicItem:0x007fc049aa6778
 ...
----

=== XML serialization
[source,ruby]
----
item.to_xml
=> "<bibitem id="NISTIR8200(DRAFT)" type="standard">
      <fetched>2019-05-03</fetched>
      <title format="text/plain" language="en" script="Latn">
        Interagency Report on Status of International Cybersecurity Standardization for the Internet of Things (IoT)
      </title>
      ...
    <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>2019-05-17</fetched>
    <title format="text/plain" language="en" script="Latn">
      Interagency Report on Status of International Cybersecurity Standardization for the Internet of Things (IoT)
    </title>
    ...
    <ext>
      <doctype>stadard</doctype>
      <commentperiod>
        <from>2018-02-01</from>
        <to>2018-04-18</to>
      </commentperiod>
    </ext>
  </bibdata>"
----

=== Get code, and year
[source,ruby]
----
RelatonNist::NistBibliography.get("8200", "2018", {})
[relaton-nist] ("8200") fetching...
[relaton-nist] ("8200") found NISTIR 8200
=> #<RelatonNist::NistBibliographicItem:0x007fc06aa2b480
...
----

=== Get short citation
Short citation is a convetion about a citation's format. The format for NIST publications is:
----
NIST {abbrev(series)} {docnumber} {(edition), optional} {(stage), optional}
# or
{abbrev(series)} {docnumber} {(edition), optional} {(stage), optional}
----
- `(stage)` is empty if the state is "final" (published). In case state is "draft" it shoud be:
  * PD for public draft
  * IPD for initial iteration public draft or 2PD, 3PD and so one for following iterations
  * FPD for final public draft
- `(edition)` is the date of publication or update
- `docnumber` is the full NIST number, including revision, e.g., 800-52

The format for FIPS publications is:
----
FIPS {docnumber}
# or
NIST FIPS {docnumber}
----
[source,ruby]
----
RelatonNist::NistBibliography.get("SP 800-205 (February 2019) (PD)")
[relaton-nist] ("SP 800-205") fetching...
[relaton-nist] ("SP 800-205") found SP 800-205 (Draft)
=> #<RelatonNist::NistBibliographicItem:0x007fc059934768
...
----

=== Get specific part, volume, version, revision, and addendum

Referehces can contain optional parameters `{ptN}{vN}{verN}{rN}{/Add}`:
- Part is specified as `ptN` (SP 800-57pt1)
- Volume is specified as `vN` (SP 800-60v1)
- Version is specified as `verN` (SP 800-45ver2)
- Revision is specified as `rN` (SP 800-40r3)
- Addendum is specified as `/Add` (SP 800-38A/Add)

[source,ruby]
----
item = RelatonNist::NistBibliography.get 'SP 800-67r3'
[relaton-nist] ("SP 800-67r3") fetching...
[relaton-nist] ("SP 800-67r3") found SP 800-67 Rev. 3
=> #<RelatonNist::NistBibliographicItem:0x007fd87bbe9460
...

item.docidentifier.first.id
=> "SP 800-67 Rev. 3"

RelatonNist::NistBibliography.get 'SP 800-38A/Add'
[relaton-nist] ("SP 800-38A/Add") fetching...
[relaton-nist] ("SP 800-38A/Add") found SP 800-38A-Add
=> #<RelatonNist::NistBibliographicItem:0x007fd88c21d880
...

item.docidentifier.first.id
=> "SP 800-38A-Add"
----

=== Create bibliographic item from YAML
[source,ruby]
----
hash = YAML.load_file 'spec/examples/nist_bib_item.yml'
=> {"id"=>"NISTIR 8011 Vol. 3",
...

bib_hash = RelatonNist::HashConverter.hash_to_bib hash
=> {:id=>"NISTIR 8011 Vol. 3",
...

RelatonNist::NistBibliographicItem.new bib_hash
=> #<RelatonNist::NistBibliographicItem:0x007f8b708505b8
...
----

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

== License

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