= 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

=== Fetching documents

[source,ruby]

require 'relaton_ietf' => true

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 => "

  <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 => "

  <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

=== Logging

RelatonIetf uses the relaton-logger gem for logging. By default, it logs to STDOUT. To change the log levels and add other loggers, read the https://github.com/relaton/relaton-logger#usage[relaton-logger] documentation.

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