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

[sourse,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

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

----
> item.to_xml
 => "<bibitem id=\"528-2019\">
      <fetched>2020-06-01</fetched>
      <title type=\"main\" format=\"text/plain\" language=\"en\" script=\"Latn\">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\">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.

----
> item.to_xml bibdata: true
 => "<bibdata>
      <fetched>2020-06-01</fetched>
      <title type="main" format="text/plain" language="en" script="Latn">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">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="sponsor">
          <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
----
> 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
...
----

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

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

 > bib_hash = RelatonIeee::HashConverter.hash_to_bib hash
 => {:id=>"528-2019", :title=>[{
 ...

 > RelatonIeee::IeeeBibliographicItem.new bib_hash
 => #<RelatonIeee::IeeeBibliographicItem:0x007fce940b3eb0
 ...
----

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