search

relaton / relaton-oasis

MIT License
0 stars 0 forks source link

readme

= RelatonOasis: retrieve OASIS Standards for bibliographic use using the BibliographicItem model

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

RelatonOasis is a Ruby gem that implements the https://github.com/metanorma/metanorma-model-iso#iso-bibliographic-item[IsoBibliographicItem model].

You can use it to retrieve metadata of OASIS Standards from https://www.oasis-open.org/standards/ and access such metadata through the OasisBibliographicItem object.

== Installation

Add this line to your application's Gemfile:

gem 'relaton-oasis'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install relaton-oasis

== Usage

=== Get standard using reference.

All the OASIS documents are parsed from https://www.oasis-open.org/standards/ and stored in a GitHub repository https://github.com/relaton/relaton-data-oasis. You can find all possible references on the index page https://relaton.github.io/relaton-data-oasis/.

[source,ruby]

require 'relaton_oasis' => true

item = RelatonOasis::OasisBibliography.get "OASIS amqp-core" [relaton-oasis] (OASIS) amqp-core Fetching from Relaton repository ... [relaton-oasis] (OASIS amqp-core) Found: OASIS amqp-core => #<RelatonOasis::OasisBibliographicItem:0x00007fceea1aecb0 ...

=== XML serialization

[source,ruby]

item.to_xml => "

2022-12-05 
  <title type="main" format="text/plain" language="en" script="Latn">Advanced Message Queueing Protocol (AMQP) v1.0</title>
  <docidentifier type="OASIS" primary="true">OASIS amqp-core</docidentifier>
  ...
</bibitem>"

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

[source,ruby]

item.to_xml bibdata: true => "

2022-12-05 
  <title type="main" format="text/plain" language="en" script="Latn">Advanced Message Queueing Protocol (AMQP) v1.0</title>
  <docidentifier type="OASIS" primary="true">OASIS amqp-core</docidentifier>
  ...
  <ext schema-version="v1.0.1">
    <doctype>standard</doctype>
    <editorialgroup>
      <technical-committee>OASIS Advanced Message Queuing Protocol (AMQP) TC</technical-committee>
    </editorialgroup>
    <technology-area>Messaging</technology-area>
  </ext>
</bibdata>"

=== Typed links

Some OASIS documents have src type link.

[source,ruby]

item = RelatonOasis::OasisBibliography.get "OASIS amqp-core-types-v1.0-Pt1" [relaton-oasis] (OASIS amqp-core-types-v1.0-Pt1) Fetching from Relaton repository ... [relaton-oasis] (OASIS amqp-core-types-v1.0-Pt1) Found: OASIS amqp-core-types-v1.0-Pt1 => #<RelatonOasis::OasisBibliographicItem:0x00007fceda0c5e08 ...

item.link => [#<RelatonBib::TypedUri:0x00007fceda0bf990 @content=#<Addressable::URI:0xbe00 URI:http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html>, @type="src">]

=== Create bibliographic item from XML

[source,ruby]

RelatonOasis::XMLParser.from_xml File.read("spec/fixtures/oasis_bibdata.xml") => #<RelatonOasis::OasisBibliographicItem:0x00007f88ab9d1d78 ...

=== Create bibliographic item from YAML [source,ruby]

hash = YAML.load_file "spec/fixtures/oasis_bibdata.yaml" => {"schema-version"=>"v1.2.9", "id"=>"OASISamqp-core", ...

RelatonOasis::OasisBibliographicItem.from_hash hash => #<RelatonOasis::OasisBibliographicItem:0x00007fceea0b6628 ...

=== Fetch data

The OASIS documents can be fetched from https://www.oasis-open.org/standards/ and converted into RelatonXML/BibXML/BibYAML formats:

The method RelatonOasis::DataFetcher.fetch(output: "data", format: "yaml") fetches and converts all the documents from the https://www.oasis-open.org/standards/ and save them to the ./data folder in YAML format.

Arguments:

[source,ruby]

RelatonOasis::DataFetcher.fetch Started at: 2022-03-18 18:34:06 +0100 Stopped at: 2022-03-18 18:34:12 +0100 Done in: 5 sec. => nil

=== Logging

RelatonOasis 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 the created tag, and push the .gem file to rubygems.org.

== Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/relaton/relaton-oasis.

== License

The gem is available as open source under the terms of the MIT License.