= RelatonJis: retrieve JIS Standards for bibliographic use using the BibliographicItem model

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

RelatonJis 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 JIS Standards from https://webdesk.jsa.or.jp, and access such metadata through the `RelatonJis::BibliographicItem` object.

== Installation

Install the gem and add to the application's Gemfile by executing:

    $ bundle add relaton-jis

If bundler is not being used to manage dependencies, install the gem by executing:

    $ gem install relaton-jis

== Usage

=== Search for standards using keywords

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

hit_collection = RelatonJis::Bibliography.search("JIS X 0208")
=> <RelatonJis::HitCollection:0x00000000018858 @ref=JIS X 0208 @fetched=false>

hit_collection.first
=> <RelatonJis::Hit:0x00000000018880 @text="JIS X 0208" @fetched="false" @fullIdentifier="" @title="">

item = hit_collection[2].fetch
=> #<RelatonJis::BibliographicItem:0x00007fe4564a7580
...

item.docidentifier
=> [#<RelatonBib::DocumentIdentifier:0x00007fe46625c518
  @id="JIS X 0208:1997/AMENDMENT 1:2012",
  @language=nil,
  @primary=true,
  @scope=nil,
  @script=nil,
  @type="JIS">]
----

=== Fetch document by reference and year

[source,ruby]
----
item = RelatonJis::Bibliography.get "JIS X 0208:1997"
[relaton-jis] (JIS X 0208:1997) Fetching from webdesk.jsa.or.jp ...
[relaton-jis] (JIS X 0208:1997) Found: `JIS X 0208:1997`
=> #<RelatonJis::BibliographicItem:0x00007fe4478ecc08
...

item = RelatonJis::Bibliography.get "JIS X 0208", "1997"
[relaton-jis] (JIS X 0208) Fetching  from webdesk.jsa.or.jp ...
[relaton-jis] (JIS X 0208) Found: `JIS X 0208:1997`
=> #<RelatonJis::BibliographicItem:0x00007fe436b49d90
...

item.docidentifier[0].id
=> "JIS X 0208:1997"
----

=== Fetch all parts of a standard

[source,ruby]
----
item = RelatonJis::Bibliography.get "JIS B 0060 (all parts)"
[relaton-jis] (JIS B 0060 (all parts)) Fetching from webdesk.jsa.or.jp ...
[relaton-jis] (JIS B 0060 (all parts)) Found: `JIS B 0060 (all parts)`
=> #<RelatonJis::BibliographicItem:0x000000010c3e2300
...

item.docidentifier
=> [#<RelatonBib::DocumentIdentifier:0x000000010c5905f8 @id="JIS B 0060 (all parts)", @language=nil, @primary=true, @scope=nil, @script=nil, @type="JIS">]

item = RelatonJis::Bibliography.get "JIS B 0060 (規格群)"
[relaton-jis] (JIS B 0060 (規格群)) Fetching from webdesk.jsa.or.jp ...
[relaton-jis] (JIS B 0060 (規格群)) Found: `JIS B 0060 (all parts)`
=> #<RelatonJis::BibliographicItem:0x000000010c3ceb20
...

item.docidentifier
=> [#<RelatonBib::DocumentIdentifier:0x000000010c8d9b10 @id="JIS B 0060 (all parts)", @language=nil, @primary=true, @scope=nil, @script=nil, @type="JIS">]
----

=== XML serialization

Possible options:

- *bibdata* - If true then wrapp item with _bibdata_ element and add _ext_ element.

[source,ruby]
----
item.to_xml
=> "<bibitem id="JISX0208-1997" type="standard" schema-version="v1.2.9">
      <fetched>2023-03-18</fetched>
      <title format="text/plain" language="ja" script="Jpan">７ビット及び８ビットの２バイト情報交換用符号化漢字集合</title>
      <title format="text/plain" language="en" script="Lant">7-bit and 8-bit double byte coded KANJI sets for information interchange</title>
      ...
    </bibitem>"

item.to_xml bibdata: true
=> "<bibdata type="standard" schema-version="v1.2.9">
      <fetched>2023-03-18</fetched>
      <title format="text/plain" language="ja" script="Jpan">７ビット及び８ビットの２バイト情報交換用符号化漢字集合</title>
      <title format="text/plain" language="en" script="Lant">7-bit and 8-bit double byte coded KANJI sets for information interchange</title>
      ...
      <ext schema-version="v0.0.1">
        <doctype>standard</doctype>
        <editorialgroup>
          <technical-committee>一般財団法人　日本規格協会</technical-committee>
        </editorialgroup>
        <ics>
          <code>35.040</code>
          <text>Information coding</text>
        </ics>
        <structuredidentifier type="JIS">
          <project-number>X0208</project-number>
        </structuredidentifier>
      </ext>
    </bibdata>"
----

=== Typed links

Each JIS document has `src` type link and optional `pdf`.

[source,ruby]
----
item.link
=> [#<RelatonBib::TypedUri:0x00007fe436a626c0
  @content=#<Addressable::URI:0xc620 URI:https://webdesk.jsa.or.jp/books/W11M0090/index/?bunsyo_id=JIS+X+0208%3A1997>,
  @language=nil,
  @script=nil,
  @type="src">,
 #<RelatonBib::TypedUri:0x00007fe436a60ed8
  @content=#<Addressable::URI:0xc634 URI:https://webdesk.jsa.or.jp/preview/pre_jis_x_00208_000_000_1997_j_pr11_i4.pdf>,
  @language=nil,
  @script=nil,
  @type="pdf">]
----

=== Fetch data

This gem scrapes the https://webdesk.jsa.or.jp/books/W11M0270 pages to fetch the JIS Standards metadata. By default the data is saved in the `./data` folder in YAML format.

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

[source,ruby]
----
RelatonJis::DataFetcher.fetch
Start fetching JIS data at 2024-09-27 17:49:40 -0400
Fetching JIS data finished at 2024-09-27 18:40:11 -0400. It took 3031.0 seconds.
=> nil
----

=== Logging

RelatonJis 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-jis.

== License

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