= RelatonIeee

RelatonIeee is a Ruby gem that implements the https://github.com/relaton/relaton-model-ieee#ieee-bibliographic-item-model[IeeeBibliographicItem model].

You can use it to retrieve metadata of IEEE Standards from standards.ieee.org, and access such metadata through the `IeeeBibliographicItem` object.

== Installation

Add this line to your application's Gemfile:

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

And then execute:

    $ bundle install

Or install it yourself as:

    $ gem install relaton-ieee

== Usage

=== Search for a standard using keywords

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

hits = RelatonIeee::IeeeBibliography.search("IEEE 528-2019")
=> <RelatonIeee::HitCollection:0x007f84c0085308 @ref=IEEE 528-2019 @fetched=false>

item = hits[0].fetch
 => #<RelatonIeee::IeeeBibliographicItem:0x007f84bf839c30
 ...
----

=== XML serialization

[source,ruby]
----
item.to_xml
 => "<bibitem id="IEEE528-2019">
      <fetched>2020-06-01</fetched>
      <title type="main" format="text/plain" language="en" script="Latn">IEEE 528-2019 - IEEE Standard for Inertial Sensor Terminology</title>
      <uri type="src">https://standards.ieee.org/content/ieee-standards/en/standard/528-2019.html</uri>
      <docidentifier type="IEEE">IEEE 528-2019</docidentifier>
      <date type="issued">
        <on>2019</on>
      </date>
      <date type="published">
        <on>2019</on>
      </date>
      <contributor>
        <role type="author"/>
        <person>
          <name>
            <completename>Ashley Moran</completename>
          </name>
        </person>
      </contributor>
      <language>en</language>
      <script>Latn</script>
      <abstract format="text/plain" language="en" script="Latn">Terms and definitions relating to inertial sensors are presented in this standard. Usage as understood by the inertial sensor community is given preference over general technical usage of the terms herein. The criterion for inclusion of a term and its definition in this standard is usefulness as related to inertial sensor technology.</abstract>
      <status>
        <stage>Active</stage>
      </status>
    </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>
      <fetched>2020-06-01</fetched>
      <title type="main" format="text/plain" language="en" script="Latn">IEEE 528-2019 - IEEE Standard for Inertial Sensor Terminology</title>
      <uri type="src">https://standards.ieee.org/content/ieee-standards/en/standard/528-2019.html</uri>
      <docidentifier type="IEEE">IEEE 528-2019</docidentifier>
      <date type="issued">
        <on>2019</on>
      </date>
      <date type="published">
        <on>2019</on>
      </date>
      <contributor>
        <role type="author"/>
        <person>
          <name>
            <completename>Ashley Moran</completename>
          </name>
        </person>
      </contributor>
      <language>en</language>
      <script>Latn</script>
      <abstract format="text/plain" language="en" script="Latn">Terms and definitions relating to inertial sensors are presented in this standard. Usage as understood by the inertial sensor community is given preference over general technical usage of the terms herein. The criterion for inclusion of a term and its definition in this standard is usefulness as related to inertial sensor technology.</abstract>
      <status>
        <stage>Active</stage>
      </status>
      <ext>
        <committee type="standard">
          <name>AES/GA - Gyro Accelerometer Panel</name>
        </committee>
        <committee type="working">
          <name>SENSR_WG - Sensors Working Group</name>
          <chair>Harry Davis</chair>
        </committee>
        <committee type="society">
          <name>IEEE Aerospace and Electronic Systems Society</name>
        </committee>
      </ext>
    </bibdata>"
----

=== Get document by reference
[source,ruby]
----
RelatonIeee::IeeeBibliography.get("IEEE 528-2019")
[relaton-ieee] ("IEEE 528-2019") fetching...
[relaton-ieee] ("IEEE 528-2019") found 528-2019
 => #<RelatonIeee::IeeeBibliographicItem:0x007fceb52a6e40
 ...

 RelatonIeee::IeeeBibliography.get("IEEE 528", "2019")
[relaton-ieee] ("IEEE 528") fetching...
[relaton-ieee] ("IEEE 528") found 528-2019
 => #<RelatonIeee::IeeeBibliographicItem:0x007fceb54af7f0
 ...

 RelatonIeee::IeeeBibliography.get("IEEE 528")
[relaton-ieee] ("IEEE 528") fetching...
[relaton-ieee] ("IEEE 528") found 528-2019
=> #<RelatonIeee::IeeeBibliographicItem:0x007fceb512c510
...
----

=== Typed links

Each IEEE document has `src` type link.

[source,ruby]
----
item.link
=> [#<RelatonBib::TypedUri:0x00007fe885219ba0 @content=#<Addressable::URI:0x8ac URI:https://standards.ieee.org/standard/528-2019.html>, @type="src">]
----

=== Create bibliographic item from XML
[source,ruby]
----
RelatonIeee::XMLParser.from_xml File.read "spec/fixtures/ieee_528_2019.xml"
 => #<RelatonIeee::IeeeBibliographicItem:0x007fceb550c978
 ...
----

=== Create bibliographic item from YAML
[source,ruby]
----
hash = YAML.load_file 'spec/fixtures/ieee_528_2019.yaml'
 => {"id"=>"528-2019", "title"=>{
 ...

 RelatonIeee::IeeeBibliographicItem.from_hash hash
 => #<RelatonIeee::IeeeBibliographicItem:0x007fce940b3eb0
 ...
----

=== Fetch data

There is an IEEE dataset https://github.com/relaton/ieee-rawbib which can be converted into BibXML/BibYAML formats. The dataset needs to be placed into local directiory.

The method `RelatonIeee::DataFetcher.fetch(output: "data", format: "yaml")` converts all the documents from the local `ieee-rawbib` directory and save them to the `./data` folder in YAML format.
Arguments:

- `output` - folder to save documents (default './data').
- `format` - format in which the documents are saved. Possimle formats are: `yaml`, `xml` (default `yaml`).

[source,ruby]
----
RelatonIeee::DataFetcher.fetch
Started at: 2021-09-24 17:55:07 +0200
Stopped at: 2021-09-24 17:57:30 +0200
Done in: 143 sec.
=> nil
----

== 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/relaton/relaton_ieee.


== License

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