= RelatonEcma

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

RelatonEcma is a Ruby gem that searches and fetches standards from the https://www.ecma-international.org[European Computer Manufacturers Association].

== Installation

Add this line to your application's Gemfile:

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

And then execute:

    $ bundle install

Or install it yourself as:

    $ gem install relaton-ecma

== Usage

=== Fetch documents

Documents can be fetched by reference. The structure of the reference depends on the type of the document. There are three types of documents:

- ECMA standards
- ECMA technical reports
- ECMA mementos

ECMA standards have the following reference structure: `ECMA-{NUMBER}[ ed{EDITION}][ vol{VOLUME}]`. Where: `NUMBER` is a number of the standard, `EDITION` is an edition of the standard, and `VOLUME` is a volume of the standard. The `EDITION` and `VOLUME` are optional. If `EDITION` is not specified, the latest edition of the standard will be fetched. If `VOLUME` is not specified, the first volume of the standard will be fetched. +

ECMA technical reports have the following reference structure: `ECMA TR/{NUMBER}[ ed{EDITION}]`. Where: `NUMBER` is a number of the technical report, and `EDITION` is an edition of the technical report. The `EDITION` is optional. If `EDITION` is not specified, the latest edition of the technical report will be fetched. +

ECMA mementos have the following reference structure: `ECMA MEM/{YEAR}`. Where: `YEAR` is an year of the memento.

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

# fetch ECMA standard
item = RelatonEcma::EcmaBibliography.get 'ECMA-6'
[relaton-ecma] (ECMA-6) Fetching from Relaton repository ...
[relaton-ecma] (ECMA-6) Found: `ECMA-6`
#<RelatonEcma::BibliographicItem:0x00007fc645b11c10
...

# fetch ECMA standard with edition and volume
RelatonEcma::EcmaBibliography.get "ECMA-269 ed3 vol2"
[relaton-ecma] (ECMA-269 ed3 vol2) Fetching from Relaton repository ...
[relaton-ecma] (ECMA-269 ed3 vol2) Found: `ECMA-269`
=> #<RelatonEcma::BibliographicItem:0x0000000106ac8210
...

# fetch the last edition of ECMA standard
bib = RelatonEcma::EcmaBibliography.get "ECMA-269"
[relaton-ecma] (ECMA-269) Fetching from Relaton repository ...
[relaton-ecma] (ECMA-269) Found: `ECMA-269`
=> #<RelatonEcma::BibliographicItem:0x000000010a408480
...

bib.edition.content
=> "9"

# fetch the first volume of ECMA standard
bib = RelatonEcma::EcmaBibliography.get "ECMA-269 ed3"
[relaton-ecma] (ECMA-269 ed3) Fetching from Relaton repository ...
[relaton-ecma] (ECMA-269 ed3) Found: `ECMA-269`
=> #<RelatonEcma::BibliographicItem:0x000000010a3ed0e0
...

bib.extent.first.reference_from
=> "1"

# fetch ECMA technical report
RelatonEcma::EcmaBibliography.get 'ECMA TR/18'
[relaton-ecma] (ECMA TR/18) Fetching from Relaton repository ...
[relaton-ecma] (ECMA TR/18) Found: `ECMA TR/18`
=> #<RelatonEcma::BibliographicItem:0x00007fc645c00cc0
...

# fetch ECMA memento
RelatonEcma::EcmaBibliography.get "ECMA MEM/2021"
[relaton-ecma] (ECMA MEM/2021) Fetching from Relaton repository ...
[relaton-ecma] (ECMA MEM/2021) Found: `ECMA MEM/2021`
=> #<RelatonEcma::BibliographicItem:0x00007fc665b2f060
...

# Return nil if a document doesn't exist.
RelatonEcma::EcmaBibliography.get '1111'
[relaton-ecma] (1111) Fetching from Relaton repository ...
[relaton-ecma] (1111) Not found.
=> nil
----

=== Serialization

[source,ruby]
----
item.to_xml
=> "<bibitem id="ECMA-6" type="standard" schema-version="v1.2.1">
      <fetched>2022-12-03</fetched>
      <title format="text/plain" language="en" script="Latn">7-bit coded character set</title>
      <uri type="src">https://www.ecma-international.org/publications-and-standards/standards/ecma-6/</uri>
      <uri type="doi">https://www.ecma-international.org/wp-content/uploads/ECMA-6_6th_edition_december_1991.pdf</uri>
      <docidentifier type="ECMA" primary="true">ECMA-6</docidentifier>
      ...
    </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" schema-version="v1.2.1">
  <fetched>2022-12-03</fetched>
  <title format="text/plain" language="en" script="Latn">7-bit coded character set</title>
  <uri type="src">https://www.ecma-international.org/publications-and-standards/standards/ecma-6/</uri>
  <uri type="doi">https://www.ecma-international.org/wp-content/uploads/ECMA-6_6th_edition_december_1991.pdf</uri>
  <docidentifier type="ECMA" primary="true">ECMA-6</docidentifier>
  ...
  <ext schema-version="v1.0.0">
    <doctype>document</doctype>
  </ext>
</bibdata>"
----

=== Typed links

Each ECMA document has `src` and `doi` link types.

[source,ruby]
----
item.link
=> [#<RelatonBib::TypedUri:0x00007fb16ecde728 @content=#<Addressable::URI:0x7e4 URI:https://www.ecma-international.org/publications-and-standards/standards/ecma-6/>, @type="src">,
 #<RelatonBib::TypedUri:0x00007fb16ecde070 @content=#<Addressable::URI:0x7f8 URI:https://www.ecma-international.org/wp-content/uploads/ECMA-6_6th_edition_december_1991.pdf>, @type="doi">]
----

=== Parse a file locally

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

=== Fetch data

This gem uses a https://github.com/relaton/relaton-data-ecma[ecma-standards] prefetched dataset as a data source. The dataset contains documents from ECMA https://www.ecma-international.org/publications-and-standards/standards/[Standards], https://www.ecma-international.org/publications-and-standards/technical-reports/[Technical Reports], and https://www.ecma-international.org/publications-and-standards/mementos/[Mementos] pages.

The method `RelatonEcma::DataFetcher.new(output: "data", format: "yaml").fetch` fetches all the documents from the pages 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`, `bibxxml` (default `yaml`).

[source,ruby]
----
RelatonEcma::DataFetcher.new.fetch
Started at: 2022-06-23 09:36:55 +0200
Stopped at: 2022-06-23 09:36:58 +0200
Done in: 752 sec.
=> nil
----

=== Logging

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

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


== License

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