File: README — Documentation for relaton-ecma (1.20.0)

RelatonEcma is a Ruby gem that searches and fetches standards from the European Computer Manufacturers Association.

Installation

Add this line to your application’s Gemfile:

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.

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

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.

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.

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

item = RelatonEcma::XMLParser.from_xml File.read("spec/fixtures/bibdata.xml")
=> #<RelatonEcma::BibliographicItem:0x00007fc645b3bf10
...

Fetch data

This gem uses a ecma-standards prefetched dataset as a data source. The dataset contains documents from ECMA Standards, Technical Reports, and 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).

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