= 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 searches and fetches 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

=== Configuration

Configuration is optional. The available option is `logger` which is a `Logger` instance. By default, the logger is `Logger.new($stderr)` with `Logger::WARN` level. To change the logger level, use `RelatonIetf.configure` block.

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

RelatonIetf.configure do |config|
  config.logger.level = Logger::DEBUG
end
----

=== Fetching documents

[source,ruby]
----
# Fetch RFC document
item = RelatonIetf::IetfBibliography.get 'IETF RFC 8341'
[relaton-ietf] (IETF RFC 8341) Fetching from Relaton repository ...
[relaton-ietf] (IETF RFC 8341) Found: `RFC 8341`
=> #<RelatonIetf::IetfBibliographicItem:0x007fd1875e7f58
...

# Fetch Internet-Draft document
RelatonIetf::IetfBibliography.get 'IETF I-D.draft-abarth-cake-01'
[relaton-ietf] (IETF I-D.draft-abarth-cake-01) Fetching from Relaton repository ...
[relaton-ietf] (IETF I-D.draft-abarth-cake-01) Found: `draft-abarth-cake-01`
=> #<RelatonIetf::IetfBibliographicItem:0x00007fdd129bbeb8
...

# Return nil if a document doesn't exist.
RelatonIetf::IetfBibliography.get 'IETF 1111'
[relaton-ietf] (IETF 1111) Fetching from Relaton repository ...
[relaton-ietf] (IETF 1111) Not found.
=> nil
----

=== Serialization

[source,ruby]
----
item.to_xml
=> "<bibitem id="RFC8341" type="standard" schema-version="v1.2.1">
      <fetched>2022-12-03</fetched>
      <title type="main" format="text/plain">Network Configuration Access Control Model</title>
      <uri type="src">https://www.rfc-editor.org/info/rfc8341</uri>
      <docidentifier type="IETF" primary="true">RFC 8341</docidentifier>
      ....
    </bibitem>"
----
With `bibdata: true` option XML output is wrapped with `bibdata` element and `ext` element added.
[source,ruby]
----
item.to_xml bibdata: true
=> "<bibdata type="standard" schema-version="v1.2.1">
      <fetched>2022-12-03</fetched>
      <title type="main" format="text/plain">Network Configuration Access Control Model</title>
      <uri type="src">https://www.rfc-editor.org/info/rfc8341</uri>
      <docidentifier type="IETF" primary="true">RFC 8341</docidentifier>
      <docidentifier type="DOI">10.17487/RFC8341</docidentifier>
      ...
      <ext schema-version="v1.0.1">
        <editorialgroup>
          <committee>netconf</committee>
        </editorialgroup>
      </ext>
    </bibdata>"
----

=== Typed links

IETF documents may have `src`, `xml`, and `doi` link types.

* `src` - web publication
* `xml` - BibXML publication
* `doi` - DOI reference

[source,ruby]
----
item.link
=> [#<RelatonBib::TypedUri:0x00007fe8b287a120 @content=#<Addressable::URI:0x7e4 URI:https://raw.githubusercontent.com/relaton/relaton-data-ietf/master/data/reference.RFC.8341.xml>, @type="xml">,
 #<RelatonBib::TypedUri:0x00007fe8b2237ec0 @content=#<Addressable::URI:0x7f8 URI:https://www.rfc-editor.org/info/rfc8341>, @type="src">]
----

=== Parse a file locally

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

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

RelatonIetf::IetfBibliographicItem.from_hash hash
=> #<RelatonIetf::IetfBibliographicItem:0x007f9a929dde40
...
----

=== Fetch data

There are IETF datasets that can be converted into RelatonXML/BibXML/BibYAML formats:

- `ietf-rfcsubseries` - https://www.rfc-editor.org/rfc-index.xml (`<bcp-entry>`, `<fyi-entry>`, `<std-entry>`)
- `ietf-internet-drafts` - convert files from local directory `./bibxml-ids`. Use `rsync -avcizxL rsync.ietf.org::bibxml-ids ./bibxml-ids` command to fetch the files.
- `ietf-rfc-entries` - https://www.rfc-editor.org/rfc-index.xml (`<rfc-entry>`)

The method `RelatonIetf::DataFetcher.fetch(source, output: "data", format: "yaml")` converts all the documents from the dataset and saves them to the `./data` folder in YAML format.

Arguments:

- `source` - dataset name (`ietf-rfcsubseries` or `ietf-internet-drafts`)
- `output` - folder to save documents (default './data').
- `format` - the format in which the documents are saved. Possible formats are: `yaml`, `xml`, `bibxml` (default `yaml`).

[source,ruby]
----
RelatonIetf::DataFetcher.fetch "ietf-internet-drafts"
Started at: 2021-12-17 10:23:20 +0100
Stopped at: 2021-12-17 10:29:19 +0100
Done in: 360 sec.
=> nil
----

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