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

image:https://img.shields.io/gem/v/nistbib.svg["Gem Version", link="https://rubygems.org/gems/nistbib"]
image:https://img.shields.io/travis/metanorma/nistbib/master.svg["Build Status", link="https://travis-ci.com/metanorma/nistbib"]
image:https://ci.appveyor.com/api/projects/status/vk85u3df4f3kertr?svg=true["Appveyor Build Status", link="https://ci.appveyor.com/project/ribose/nistbib"]
image:https://codeclimate.com/github/metanorma/nistbib/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/nistbib"]


NistBib 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 'nistbib'
----

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install nistbib

== Usage

=== Search for a standard using keywords

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

hit_collection = NistBib::NistBibliography.search("8200")
=> [<NistBib::Hit:0x007f82b9b2b298 @text="8200" @fetched="false" @fullIdentifier="" @title="8200">,
 <NistBib::Hit:0x007f82b9b2a1e0 @text="8200" @fetched="false" @fullIdentifier="" @title="8200">]

 item = hit_collection[1].fetch
 => #<NistBib::NistBibliographicItem:0x007f82b986e668
 ...
----

=== XML serialization
[source,ruby]
----
item.to_xml
=> "<nist-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>
      ...
    </nist-standard>"
----

=== Get code, and year
[source,ruby]
----
NistBib::NistBibliography.get("8200", "2018", {})
fetching 8200...
=> #<NistBib::NistBibliographicItem:0x007f82bb3370a8
...
----

=== 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), optioal}
# or
{abbrev(series)} {docnumber} {(edition), optional} {(stage), optioal}
----
- `(stage)` is empty if the state is "final" (published)
- `(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]
----
NistBib::NistBibliography.get("8200", "2018", {})
fetching 8200...
=> #<NistBib::NistBibliographicItem:0x007f82bb3370a8
...
----

== 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/nistbib.

== License

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