= RelatonIetf

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

_Formerly known as_ `rfcbib`.

RelatonIetf is a Ruby gem that search and fetch standards from the https://www.ietf.org[Internet Engineering Task Force (IETF)], including RFCs.

The standards scrape form https://www.rfc-editor.org/search/rfc_search.php

== Installation

Add this line to your application's Gemfile:

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

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install relaton-ietf

== Usage

=== Search document

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

item = RelatonIetf::IetfBibliography.search 'RFC 8341'
=> #<RelatonIetf::IetfBibliographicItem:0x007fd1875e7f58
...

# Return nil if document doesn't exist.
RelatonIetf::IetfBibliography.search '1111'
RelatonBib::RequestError: 1111: not recognised for RFC
=> nil
----

=== Serialization

[source,ruby]
----
item.to_xml
=>"<bibitem id="RFC8341">
  <fetched>2019-06-05</fetched>
  <title format="text/plain" language="en" script="Latn">Network Configuration Access Control Model</title>
  <uri type="src">https://www.rfc-editor.org/info/rfc8341</uri>
  <docidentifier type="IETF">RFC 8341</docidentifier>
  <docidentifier type=\"rfc-anchor\">RFC8341</docidentifier>
  <docidentifier type="DOI">10.17487/RFC8341</docidentifier>
  ....
</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-05</fetched>
  <title format="text/plain" language="en" script="Latn">Network Configuration Access Control Model</title>
  <uri type="src">https://www.rfc-editor.org/info/rfc8341</uri>
  ...
  <ext>
    <doctype>rfc</doctype>
  </ext>
</bibdata>"
----

=== Parse a file locally

[source,ruby]
----
item = Relaton::Provider::Ietf.from_rfcxml File.read("spec/examples/rfc.xml")
=> #<RelatonIetf::IetfBibliographicItem:0x007fa8cda79ab8
...

item.to_xml bibdata: true
=>"<bibdata>
  <fetched>2020-09-15</fetched>
  <title format="text/plain" language="en" script="Latn">ACVP Secure Hash Algorithm (SHA) JSON Specification</title>
  ...
</bibdata>"
----

=== Create bibliographic item form YAML
[source,ruby]
----
hash = YAML.load_file 'spec/examples/ietf_bib_item.yml'
=> {"id"=>"RFC 8341",
...

bib_hash = RelatonIetf::HashConverter.hash_to_bib hash
=> {:id=>"RFC 8341",
...

RelatonIetf::IetfBibliographicItem.new bib_hash
=> #<RelatonIetf::IetfBibliographicItem:0x007f9a929dde40
...
----

== Contributing

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

== License

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