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