README.adoc from relaton/relaton-cen

README.adoc
Summary

Maintainability

Test Coverage

Issues
= RelatonCen retrieve CEN Standards for bibliographic use using the BibliographicItem model

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

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

== Installation

Add this line to your application's `Gemfile`:

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

And then execute:

[source,sh]
----
$ bundle install
----

Or install it yourself as:

[source,sh]
----
$ gem install relaton-cen
----

== Usage

For CENELEC standards, use references with the prefix `CEN/CLC`. For example, `CEN/CLC Guide 6`.

=== Search for a standard using keywords

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

hit_collection = RelatonCen::CenBibliography.search("CEN ISO/TS 21003-7")
=> <RelatonCen::HitCollection:0x00000000017de0 @ref=ISO/TS 21003-7 @fetched=false>

item = hit_collection[0].fetch
=> #<RelatonIsoBib::IsoBibliographicItem:0x00007fadcd45fad8
 ...
----

=== Get a standard by its code

Use `RelatonCen::CenBibliography.get(ref, year, options)` to get a standard by its code.

- `ref` is the standard code, e.g. `CEN ISO/TS 21003-7`
- `year` is the year of the standard, e.g. `2019` (optional)
- `options` is a hash of options:
  - `keep_year` - keep the year in ID if true (optional)

[source,ruby]
----
# With year in reference
RelatonCen::CenBibliography.get "EN 10160:1999"
[relaton-cen] (EN 10160:1999) Fetching from standards.cencenelec.eu ...
[relaton-cen] (EN 10160:1999) Found: `EN 10160:1999`
=> #<RelatonCen::BibliographicItem:0x0000000112d8b900
...

# With a year as a separate argument
RelatonCen::CenBibliography.get "EN 10160", "1999"

# To get the most recent version of a standard by its code use reference without year
> RelatonCen::CenBibliography.get "CEN/CLC Guide 6"
[relaton-cen] (CEN/CLC Guide 6) Fetching from standards.cencenelec.eu ...
[isoics] code   not found in ICS list
[relaton-cen] (CEN/CLC Guide 6) Found: `CEN/CLC Guide 6`
=> #<RelatonCen::BibliographicItem:0x0000000112d81680
...

# To keep the year in ID use `keep_year` option
> RelatonCen::CenBibliography.get "CEN/CLC Guide 6", nil, keep_year: true
[relaton-cen] (CEN/CLC Guide 6) Fetching from standards.cencenelec.eu ...
[isoics] code   not found in ICS list
[relaton-cen] (CEN/CLC Guide 6) Found: `CEN/CLC Guide 6:2014`
=> #<RelatonCen::BibliographicItem:0x0000000112d8b400
...
----

=== XML serialization

[source,ruby]
----
item.to_xml
=> "<bibitem id="CENISO/TS21003-7-2019" type="standard" schema-version="v1.2.1">
      <fetched>2022-12-03</fetched>
      <title type="title-main" format="text/plain" language="en" script="Latn">Multilayer piping systems for hot and cold water installations inside buildings</title>
      ...
    </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 type="title-main" format="text/plain" language="en" script="Latn">Multilayer piping systems for hot and cold water installations inside buildings</title>
      ...
      <ext schema-version="v1.0.1">
        <doctype>international-standard</doctype>
        ...
      </ext>
    </bibdata>"
----

=== Typed links

Each CEN document has `src` type link.

[source,ruby]
----
item.link
=> [#<RelatonBib::TypedUri:0x00007f865cf9a328 @content=#<Addressable::URI:0xbea0 URI:https://standards.cencenelec.eu/dyn/www/f?p=CEN:110:0::::FSP_PROJECT,FSP_ORG_ID:68120,6137&cs=19764D9131733FD9E70037E7A6E6740B2>, @type="src">]
----

=== Get code, and year

[source,ruby]
----
RelatonCen::CenBibliography.get "CEN ISO/TS 21003-7:2019"
[relaton-cen] (CEN ISO/TS 21003-7) Fetching from standards.cencenelec.eu ...
[relaton-cen] (CEN ISO/TS 21003-7) Found: CEN `ISO/TS 21003-7:2019`
=> #<RelatonIsoBib::IsoBibliographicItem:0x00007fadcd596c58
...

RelatonCen::CenBibliography.get "CEN ISO/TS 21003-7", "2019"
[relaton-cen] (CEN ISO/TS 21003-7) Fetching from standards.cencenelec.eu ...
[relaton-cen] (CEN ISO/TS 21003-7) Found: CEN `ISO/TS 21003-7:2019`
=> #<RelatonIsoBib::IsoBibliographicItem:0x00007fadcd5df9f8
...
----

=== Create bibliographic item form YAML

[source,ruby]
----
hash = YAML.load_file 'spec/fixtures/bibdata.yaml'
=> {"id"=>"CENISO/TS21003-7-2019",
...

 RelatonCen::BibliographicItem.from_hash hash
=> #<RelatonCen::BibliographicItem:0x00007f9d0118cb58
...
----

=== Create bibliographic item from XML

[source,ruby]
----
RelatonCen::XMLParser.from_xml File.read("spec/fixtures/bibdata.xml", encoding: "UTF-8")
=> #<RelatonCen::BibliographicItem:0x00007f9cf12bc5b0
...
----

=== Logging

RelatonCen 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](https://rubygems.org).

== Contributing

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

== License

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