= 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

=== 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 `RelatonIeee.configure` block.

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

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

=== Search for a standard using keywords

[source,ruby]
----
item = RelatonIeee::IeeeBibliography.search("IEEE 528-2019")
=> #<RelatonIeee::IeeeBibliographicItem:0x00007fe12ebc8cb8
...
----

=== XML serialization

[source,ruby]
----
item.to_xml
 => "<bibitem id="IEEE528-2019" type="standard" schema-version="v1.2.1">
      <fetched>2022-12-03</fetched>
      <title type="main" format="text/plain">IEEE Standard for Inertial Sensor Terminology</title>
      <uri type="src">https://ieeexplore.ieee.org/document/8863799</uri>
      <docidentifier type="IEEE" primary="true">IEEE 528-2019</docidentifier>
      ...
    </bibitem>"
----

With argument `bibdata: true` it ouputs XML wrapped by `bibdata` element and adds flavor `ext` element.

[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">IEEE Standard for Inertial Sensor Terminology</title>
      <uri type="src">https://ieeexplore.ieee.org/document/8863799</uri>
      <docidentifier type="IEEE" primary="true">IEEE 528-2019</docidentifier>
      ...
      <ext schema-version="v1.0.0">
        <editorialgroup>
          <committee>Gyro Accelerometer Panel of the IEEE Aerospace and Electronic Systems Society</committee>
        </editorialgroup>
        ...
      </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 `IEEE 528-2019`
 => #<RelatonIeee::IeeeBibliographicItem:0x007fceb52a6e40
 ...
----

=== 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"=>"IEEE528-2019",
 ...

 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 the local directory.

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

- `output` - folder to save documents (default './data').
- `format` - the format in which the documents are saved. Possible 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).