= RelatonCie

image:https://img.shields.io/gem/v/relaton-cie.svg["Gem Version", link="https://rubygems.org/gems/relaton-cie"]
image:https://github.com/relaton/relaton-cie/workflows/macos/badge.svg["Build Status (macOS)", link="https://github.com/relaton/relaton-cie/actions?workflow=macos"]
image:https://github.com/relaton/relaton-cie/workflows/windows/badge.svg["Build Status (Windows)", link="https://github.com/relaton/relaton-cie/actions?workflow=windows"]
image:https://github.com/relaton/relaton-cie/workflows/ubuntu/badge.svg["Build Status (Ubuntu)", link="https://github.com/relaton/relaton-cie/actions?workflow=ubuntu"]
image:https://codeclimate.com/github/relaton/relaton-cie/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/relaton/relaton-cie"]
image:https://img.shields.io/github/issues-pr-raw/relaton/relaton-cie.svg["Pull Requests", link="https://github.com/relaton/relaton-cie/pulls"]
image:https://img.shields.io/github/commits-since/relaton/relaton-cie/latest.svg["Commits since latest",link="https://github.com/relaton/relaton-cie/releases"]

RelatonCie is a Ruby gem that search and fetch standards from the https://www.techstreet.com/cie/searches/31156444[International Commision on Illuminantion].

== Installation

Add this line to your application's Gemfile:

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

And then execute:

    $ bundle install

Or install it yourself as:

    $ gem install relaton-cie

== Usage

=== Search document

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

item = RelatonCie::CieBibliography.get 'CIE 001-1980'
[relaton-cie] ("CIE 001-1980") fetching...
[relaton-cie] ("CIE 001-1980") found CIE 001-1980
=> #<RelatonBib::BibliographicItem:0x007fb3f6098920
...

# Return nil if document doesn't exist.
RelatonCie::CieBibliography.get '1111'
[relaton-cie] ("1111") fetching...
[relaton-cie] WARNING no match found online for 1111. The code must be exactly like it is on the standards website.
=> nil
----

=== Serialization

[source,ruby]
----
item.to_xml
"<bibitem id="CIE001-1980" type="standard">
  <fetched>2021-03-17</fetched>
  <title type="title-main" format="text/plain">
    Guidelines for minimizing urban sky glow near astronomical observatories (Joint Publication IAU/CIE)
  </title>
  <title type="main" format="text/plain">
    Guidelines for minimizing urban sky glow near astronomical observatories (Joint Publication IAU/CIE)
  </title>
  <uri type="src">https://www.techstreet.com/cie/standards/cie-001-1980?product_id=1210107</uri>
  <docidentifier type="CIE">CIE 001-1980</docidentifier>
  <docidentifier type="ISBN">9783901906657</docidentifier>
  <date type="published">
    <on>1980-01-01</on>
  </date>
  <contributor>
    <role type="publisher"/>
    <organization>
      <name>Commission Internationale de L'Eclairage</name>
      <abbreviation>CIE</abbreviation>
      <uri>cie.co.at</uri>
    </organization>
  </contributor>
  <language>en</language>
  <script>Latn</script>
  <abstract format="text/plain" language="en" script="Latn">
    The increase of outdoor lighting in urban areas has resulted in levels of sky glow which seriously threaten astronomical observatories, even where these have purposely been located more than 100 km from large cities. The International Astronomical Union (IAU) and the CIE have worked together to prepare these guidelines in order to stimulate collective action that minimizes the degradation of the astronomical environment near cities.

    The problem and its solutions are stated in a manner that provides a basis for understanding, cooperation, and action by astronomers, lighting engineers and public authorities. The report explains the effect of man-made sky glow, the degree of glow likely to be produced by lighting near an observatory, the level above which sky glow should not be allowed to rise, and how it can be contained by good lighting practice and public ordinances.

    The publication contains 24 pages and 2 figures.

    This publication has been prepared by:

        * R. Cayrel and F. G. Smith (IAU)
        * A. J. Fisher and J. B. de Boer (CIE)
  </abstract>
</bibitem>"
----

With `bibdata: true` option XML output wrapped with `bibdata` element and `ext` element added.
[source,ruby]
----
item.to_xml bibdata: true
"<bibdata type="standard">
  <fetched>2021-03-17</fetched>
  <title type="title-main" format="text/plain">
    Guidelines for minimizing urban sky glow near astronomical observatories (Joint Publication IAU/CIE)
  </title>
  <title type="main" format="text/plain">
    Guidelines for minimizing urban sky glow near astronomical observatories (Joint Publication IAU/CIE)
  </title>
  <uri type="src">https://www.techstreet.com/cie/standards/cie-001-1980?product_id=1210107</uri>
  <docidentifier type="CIE">CIE 001-1980</docidentifier>
  ...
  <ext>
    <doctype>document</doctype>
  </ext>
</bibdata>"
----
 === Typed links

Each CIE document has `src` type link.

[source,ruby]
----
item.link
=> [#<RelatonBib::TypedUri:0x00007fe58e8d4048 @content=#<Addressable::URI:0xbe50 URI:https://www.techstreet.com/cie/standards/cie-001-1980?product_id=1210107>, @type="src">]
----

=== Parse a file locally

[source,ruby]
----
item = RelatonBib::XMLParser.from_xml File.read("spec/fixtures/bibdata.xml")
=> #<RelatonBib::BibliographicItem:0x007fb4061aa498
...
----

=== Fetch data

This gem uses the https://www.techstreet.com/cie/searches/31156444 dataset as one of data sources.

The method `RelatonCie::DataFetcher.fetch(output: "data", format: "yaml")` fetches all the documents from the datast 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]
----
RelatonCie::DataFetcher.fetch
Started at: 2021-09-08 16:37:53 +0200
Stopped at: 2021-09-08 16:49:17 +0200
Done in: 684 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-cie.


== License

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