relaton-nist 1.12.4 → 1.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a08c33ae20e118a973b19b9697114dd4be09331bc3322a3d75250959c4cb0880
-  data.tar.gz: 1066aab4db2167b2551fd59a76248a96bbcfddbbcc11e0894cb16d91af0fe69c
+  metadata.gz: aeed99df30e7f99bfc8d2b05dccaf5bc45eb6c8980b1b5f608eb2ce94a541382
+  data.tar.gz: 41a13eb308604d5fbf7b9b808e2397d90b6c7ad0ba19722618487434233cd315
 SHA512:
-  metadata.gz: e0b46445fda68e042630f4eccfc925a317dbe22a3331fe5ef86eebcceb7a036134bedba1a2b6679987d4a2b727ee2590887d52a26c014adbbd27b382b70b2adc
-  data.tar.gz: cdc10291398c3f037a00f7a2b013f3a159ed1b8803a0d401522cfb4df0119036cd7b1a9cbfb28ebdf05819a4f365fd4bc0d284fc3031ef34311418e279e35eba
+  metadata.gz: d2e8d7da0a19ea149b5dce1d43831a4589a39f47ddb57bbb91f6621896d614ea670aae89348479fc6f956ecc678d9493503fe6b24e44e17b2e5986e997be89dd
+  data.tar.gz: caf9ddca1f1dc8eb37541c9c5620d183f72ff4bcd389261d6173f306e4d511a3e83df84a7fc6828dbb7bdc31457e01834e9fe18fca0b7f7d46fadc54d2dc6133

data/grammars/biblio.rng

@@ -225,9 +225,9 @@
         <zeroOrMore>
           <ref name="forename"/>
         </zeroOrMore>
-        <zeroOrMore>
-          <ref name="initial"/>
-        </zeroOrMore>
+        <optional>
+          <ref name="formatted-initials"/>
+        </optional>
         <ref name="surname"/>
         <zeroOrMore>
           <ref name="addition"/>
@@ -247,8 +247,8 @@
       <ref name="LocalizedString"/>
     </element>
   </define>
-  <define name="initial">
-    <element name="initial">
+  <define name="formatted-initials">
+    <element name="formatted-initials">
       <ref name="LocalizedString"/>
     </element>
   </define>
@@ -264,6 +264,9 @@
   </define>
   <define name="forename">
     <element name="forename">
+      <optional>
+        <attribute name="initial"/>
+      </optional>
       <ref name="LocalizedString"/>
     </element>
   </define>

data/grammars/isodoc.rng

@@ -69,6 +69,17 @@
         </zeroOrMore>
       </element>
     </define>
+    <define name="AdmonitionType">
+      <choice>
+        <value>warning</value>
+        <value>note</value>
+        <value>tip</value>
+        <value>important</value>
+        <value>caution</value>
+        <value>statement</value>
+        <value>editorial</value>
+      </choice>
+    </define>
     <define name="index">
       <element name="index">
         <optional>
@@ -1274,7 +1285,12 @@
   </define>
   <define name="span">
     <element name="span">
-      <attribute name="class"/>
+      <optional>
+        <attribute name="class"/>
+      </optional>
+      <optional>
+        <attribute name="style"/>
+      </optional>
       <oneOrMore>
         <ref name="TextElement"/>
       </oneOrMore>
@@ -2493,6 +2509,16 @@
           <text/>
         </element>
       </optional>
+      <optional>
+        <element name="amendment">
+          <text/>
+        </element>
+      </optional>
+      <optional>
+        <element name="corrigendum">
+          <text/>
+        </element>
+      </optional>
       <optional>
         <element name="language">
           <text/>

data/lib/relaton_nist/data_fetcher.rb

@@ -137,26 +137,10 @@ module RelatonNist
 
     # @param doc [Nokogiri::XML::Element]
     # @return [Array<Hash>]
-    def fetch_contributor(doc) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    def fetch_contributor(doc)
       contribs = doc.xpath("contributors/person_name").map do |p|
-        forename = []
-        initial = []
-        p.at("given_name")&.text&.split&.each do |fn|
-          if /^(?<init>\w)\.?$/ =~ fn
-            initial << RelatonBib::LocalizedString.new(init, doc["language"], "Latn")
-          else
-            forename << RelatonBib::LocalizedString.new(fn, doc["language"], "Latn")
-          end
-        end
-        sname = p.at("surname").text
-        surname = RelatonBib::LocalizedString.new sname, doc["language"], "Latn"
-        ident = p.xpath("ORCID").map do |id|
-          RelatonBib::PersonIdentifier.new "orcid", id.text
-        end
-        fullname = RelatonBib::FullName.new(
-          surname: surname, forename: forename, initial: initial, identifier: ident,
-        )
-        person = RelatonBib::Person.new name: fullname, affiliation: affiliation(doc)
+        person = RelatonBib::Person.new(name: fullname(p, doc),
+                                        affiliation: affiliation(doc))
         { entity: person, role: [{ type: p["contributor_role"] }] }
       end
       contribs + doc.xpath("publisher").map do |p|
@@ -164,6 +148,78 @@ module RelatonNist
       end
     end
 
+    #
+    # Create full name object from person name element.
+    #
+    # @param [Nokogiri::XML::Element] person name element
+    # @param [Nokogiri::XML::Element] doc document element
+    #
+    # @return [RelatonBib::FullName] full name object
+    #
+    def fullname(person, doc)
+      forename, initials = forename_initial(person, doc)
+      surname = localized_string person.at("surname").text, doc
+      ident = person.xpath("ORCID").map do |id|
+        RelatonBib::PersonIdentifier.new "orcid", id.text
+      end
+      RelatonBib::FullName.new(surname: surname, forename: forename,
+                               initials: initials, identifier: ident)
+    end
+
+    #
+    # Create forename and initials objects from person name element.
+    #
+    # @param [Nokogiri::XML::Element] person person name element
+    # @param [Nokogiri::XML::Element] doc document element
+    #
+    # @return [Array<Array<RelatonBib::LocalizedString>>] forename and initials
+    #
+    def forename_initial(person, doc) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      fnames = []
+      fname = person.at("given_name")&.text
+      if fname
+        if /^(?<inits>(?:\w[.\s]+|[A-Z]{1,2}$)+)$/ =~ fname
+          ints = inits.split(/[.\s]*/)
+          fnames << forename(doc, fname, ints.shift)
+          ints.each { |i| fnames << forename(doc, nil, i) }
+        else
+          fn = forename(doc, fname)
+          fnames << fn if fn
+        end
+      end
+      initials = localized_string inits, doc if not(inits.nil? || inits.empty?)
+      [fnames, initials]
+    end
+
+    #
+    # Create forename object
+    #
+    # @param [Nokogiri::XML::Element] doc document element
+    # @param [String, nil] cnt forename content
+    # @param [String, nil] init initial content
+    #
+    # @return [RelatonBib::Forename] forename object
+    #
+    def forename(doc, cnt, init = nil)
+      return if (cnt.nil? || cnt.empty?) && (init.nil? || init.empty?)
+
+      RelatonBib::Forename.new(
+        content: cnt, language: doc["language"], script: "Latn", initial: init,
+      )
+    end
+
+    #
+    # Create localized string
+    #
+    # @param [String] content content of string
+    # @param [Nokogiri::XML::Elemrnt] doc XML element
+    #
+    # @return [RelatonBib::LocalizedString] localized string
+    #
+    def localized_string(content, doc)
+      RelatonBib::LocalizedString.new content, doc["language"], "Latn"
+    end
+
     #
     # Create publisher organization
     #

data/lib/relaton_nist/hit.rb

@@ -5,13 +5,20 @@ module RelatonNist
   class Hit < RelatonBib::Hit
     attr_writer :fetch
 
+    #
     # Parse page.
-    # @return [RelatonNist::NistBliographicItem]
+    #
+    # @return [RelatonNist::NistBliographicItem] bibliographic item
+    #
     def fetch
       @fetch ||= Scrapper.parse_page @hit
     end
 
-    # @return [Iteger]
+    #
+    # Calculate sorting weigth of hit by series, code, title, addendum, and status
+    #
+    # @return [Iteger] sorting weigth
+    #
     def sort_value # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
       @sort_value ||= begin
         sort_phrase = [hit[:series], hit[:code], hit[:title]].join " "

data/lib/relaton_nist/hit_collection.rb

@@ -7,7 +7,7 @@ require "addressable/uri"
 require "open-uri"
 
 module RelatonNist
-  # Page of hit collection.
+  # Hit collection.
   class HitCollection < RelatonBib::HitCollection
     DOMAIN = "https://csrc.nist.gov"
     PUBS_EXPORT = URI.join(DOMAIN, "/CSRC/media/feeds/metanorma/pubs-export")
@@ -15,17 +15,37 @@ module RelatonNist
     DATAFILE = File.expand_path "pubs-export.zip", DATAFILEDIR
     GHNISTDATA = "https://raw.githubusercontent.com/relaton/relaton-data-nist/main/data/"
 
+    #
+    # Create hits collection instance and search hits
+    #
+    # @param [Hash] opts options
+    # @option opts [String] :stage stage of document
+    #
+    # @return [RelatonNist::HitCollection] hits collection
+    #
     def self.search(text, year = nil, opts = {})
       new(text, year).search(opts)
     end
 
+    #
+    # Search nits in JSON file or GitHub repo
+    #
+    # @param [Hash] opts options
+    # @option opts [String] :stage stage of document
+    #
+    # @return [RelatonNist::HitCollection] hits collection
+    #
     def search(opts)
       @array = from_json(**opts)
       @array = from_ga unless @array.any?
       sort_hits!
     end
 
-    # @return [Array<RelatonNist::Hit>]
+    #
+    # Filter hits by reference's parts
+    #
+    # @return [Array<RelatonNist::Hit>] hits
+    #
     def search_filter # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
       @array.select do |item|
         %r{
@@ -53,6 +73,11 @@ module RelatonNist
 
     private
 
+    #
+    # Parse reference parts
+    #
+    # @return [Hash] reference parts
+    #
     def refparts # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       @refparts ||= {
         perfix: match(/^(NIST|NBS)\s?/, text),
@@ -71,10 +96,23 @@ module RelatonNist
       }
     end
 
+    #
+    # Match regex to reference
+    #
+    # @param [Regexp] regex regex
+    # @param [String] code reference
+    #
+    # @return [String, nil] matched string
+    #
     def match(regex, code)
       regex.match(code)&.to_s
     end
 
+    #
+    # Generate reference from parts
+    #
+    # @return [String] reference
+    #
     def full_ref # rubocop:disable Metrics/AbcSize
       @full_ref ||= begin
         ref = "#{refparts[:perfix]}#{refparts[:series]} #{refparts[:code]}"
@@ -84,9 +122,16 @@ module RelatonNist
       end
     end
 
+    #
+    # Return short version of ID part with removed "-" or convert long version to short.
+    # Converts "pt-1" to "pt1" and "Part 1" to "pt1", "v-1" to "v1" and "Vol. 1" to "v1",
+    #   "ver-1" to "ver1" and "Ver. 1" to "ver1", "r-1" to "r1" and "Rev. 1" to "r1".
+    #
     # @param short [String]
     # @param long [String]
+    #
     # @return [String, nil]
+    #
     def long_to_short(short, long)
       return short.sub(/-/, "") if short
       return unless long
@@ -94,6 +139,11 @@ module RelatonNist
       long.sub(/Part\s/, "pt").sub(/Vol\.\s/, "v").sub(/Rev\.\s/, "r").sub(/(Ver\.|Version)\s/, "ver")
     end
 
+    #
+    # Sort hits by sort_value and release date
+    #
+    # @return [self] sorted hits collection
+    #
     def sort_hits!
       @array.sort! do |a, b|
         if a.sort_value == b.sort_value
@@ -105,7 +155,14 @@ module RelatonNist
       self
     end
 
-    def from_ga # rubocop:disable Metrics/AbcSize
+    #
+    # Get hit from GitHub repo
+    #
+    # @return [Array<RelatonNist::Hit>] hits
+    #
+    # @raise [OpenURI::HTTPError] if GitHub repo is not available
+    #
+    def from_ga # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       ref = full_ref
       fn = ref.gsub(%r{[/\s:.]}, "_").upcase
       yaml = OpenURI.open_uri "#{GHNISTDATA}#{fn}.yaml"
@@ -120,9 +177,14 @@ module RelatonNist
       raise e
     end
 
+    #
     # Fetches data form json
-    # @param stage [String]
-    # @return [Array<RelatonNist::Hit>]
+    #
+    # @param opts [Hash] options
+    # @option opts [String] :stage stage of document
+    #
+    # @return [Array<RelatonNist::Hit>] hits
+    #
     def from_json(**opts)
       select_data(**opts).map do |h|
         /(?<series>(?<=-)\w+$)/ =~ h["series"]
@@ -134,8 +196,14 @@ module RelatonNist
       end
     end
 
-    # @param stage [String]
-    # @return [Array<Hach>]
+    #
+    # Select data from json
+    #
+    # @param opts [Hash] options
+    # @option opts [String] :stage stage of document
+    #
+    # @return [Array<Hash>] selected data
+    #
     def select_data(**opts) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength,Metrics/PerceivedComplexity
       ref = "#{refparts[:series]} #{refparts[:code]}"
       d = Date.strptime year, "%Y" if year
@@ -152,9 +220,14 @@ module RelatonNist
       end
     end
 
-    # @param doc [Hash]
+    #
+    # Check if issued date is match to year
+    #
+    # @param doc [Hash] document's metadata
     # @param date [Date] first day of year
-    # @return [TrueClass, FalseClass]
+    #
+    # @return [Boolean]
+    #
     def match_year?(doc, date)
       return true unless year
 
@@ -162,8 +235,11 @@ module RelatonNist
       idate.between? date, date.next_year.prev_day
     end
 
+    #
     # Fetches json data form server
-    # @return [Hash]
+    #
+    # @return [Array<Hash>] json data
+    #
     def data
       ctime = File.ctime DATAFILE if File.exist? DATAFILE
       if !ctime || ctime.to_date < Date.today || File.size(DATAFILE).zero?
@@ -172,9 +248,11 @@ module RelatonNist
       unzip
     end
 
+    #
     # Fetch data form server and save it to file
     #
-    # @prarm ctime [Time, NilClass]
+    # @prarm ctime [Time, nil] file creation time
+    #
     def fetch_data(ctime)
       if !ctime || ctime < OpenURI.open_uri("#{PUBS_EXPORT}.meta").last_modified
         @data = nil
@@ -184,9 +262,11 @@ module RelatonNist
       end
     end
 
+    #
     # upack zip file
     #
-    # @return [Hash]
+    # @return [Array<Hash>] json data
+    #
     def unzip
       return @data if @data
 

data/lib/relaton_nist/nist_bibliography.rb

@@ -11,8 +11,13 @@ require "relaton_nist/hash_converter"
 module RelatonNist
   class NistBibliography
     class << self
-      # @param text [String]
-      # @return [RelatonNist::HitCollection]
+      #
+      # Search NIST docuemnts by reference
+      #
+      # @param text [String] reference
+      #
+      # @return [RelatonNist::HitCollection] search result
+      #
       def search(text, year = nil, opts = {})
         ref = text.sub(/^NIST\sIR/, "NISTIR")
         HitCollection.search ref, year, opts
@@ -20,15 +25,18 @@ module RelatonNist
         raise RelatonBib::RequestError, e.message
       end
 
+      #
+      # Get NIST document by reference
+      #
       # @param code [String] the NIST standard Code to look up (e..g "8200")
       # @param year [String] the year the standard was published (optional)
       #
       # @param opts [Hash] options
-      # @option opts [TrueClass, FalseClass] :all_parts restricted to all parts
+      # @option opts [Boolean] :all_parts restricted to all parts
       #   if all-parts reference is required
-      # @option opts [TrueClass, FalseClass] :bibdata
       #
-      # @return [String] Relaton XML serialisation of reference
+      # @return [RelatonNist::NistBibliographicItem, nil] bibliographic item
+      #
       def get(code, year = nil, opts = {}) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         return fetch_ref_err(code, year, []) if code.match?(/\sEP$/)
 
@@ -61,6 +69,18 @@ module RelatonNist
 
       private
 
+      #
+      # Get NIST document by reference
+      #
+      # @param [String] code reference
+      # @param [String] year year
+      # @param [Hash] opts options
+      # @option opts [Date] :issued_date issued date
+      # @option opts [Date] :updated_date updated date
+      # @option opts [String] :stage stage
+      #
+      # @return [RelatonNist::NistBibliographicItem, nil] bibliographic item
+      #
       def nistbib_get(code, year, opts)
         result = nistbib_search_filter(code, year, opts) || (return nil)
         ret = nistbib_results_filter(result, year, opts)
@@ -72,6 +92,7 @@ module RelatonNist
         end
       end
 
+      #
       # Sort through the results from RelatonNist, fetching them three at a time,
       # and return the first result that matches the code,
       # matches the year (if provided), and which # has a title (amendments do not).
@@ -80,11 +101,12 @@ module RelatonNist
       # If no match, returns any years which caused mismatch, for error reporting
       #
       # @param opts [Hash] options
-      # @option opts [Time] :issued_date
-      # @option opts [Time] :issued_date
-      # @option opts [String] :stage
+      # @option opts [Date] :issued_date issued date
+      # @option opts [Date] :issued_date issued date
+      # @option opts [String] :stage stage
+      #
+      # @return [Hash] result
       #
-      # @return [Hash]
       def nistbib_results_filter(result, year, opts) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         missed_years = []
         iter = /\w+(?=PD)|(?<=PD-)\w+/.match(opts[:stage])&.to_s
@@ -119,9 +141,14 @@ module RelatonNist
         { years: missed_years }
       end
 
-      # @param hits [RelatonNist::HitCollection]
-      # @param threads [Integer]
-      # @return [Array<RelatonNist::NistBibliographicItem>]
+      #
+      # Fetch pages for all the hits in parallel
+      #
+      # @param hits [RelatonNist::HitCollection] hits
+      # @param threads [Integer] number of threads
+      #
+      # @return [Array<RelatonNist::NistBibliographicItem>] bibliographic items
+      #
       def fetch_pages(hits, threads)
         workers = RelatonBib::WorkersPool.new threads
         workers.worker { |w| { i: w[:i], hit: w[:hit].fetch } }
@@ -130,16 +157,31 @@ module RelatonNist
         workers.result.sort_by { |a| a[:i] }.map { |x| x[:hit] }
       end
 
-      # @param code [String]
-      # @param year [String, nil]
-      # @param opts [Hash]
-      # @return [RelatonNist::HitCollection]
+      #
+      # Get search results and filter them by code and year
+      #
+      # @param code [String] reference
+      # @param year [String, nil] year
+      # @param opts [Hash] options
+      # @option opts [String] :stage stage
+      #
+      # @return [RelatonNist::HitCollection] hits collection
+      #
       def nistbib_search_filter(code, year, opts)
         warn "[relaton-nist] (\"#{code}\") fetching..."
         result = search(code, year, opts)
         result.search_filter
       end
 
+      #
+      # Outputs warning message if no match found
+      #
+      # @param [String] code reference
+      # @param [String, nil] year year
+      # @param [Array<String>] missed_years missed years
+      #
+      # @return [nil] nil
+      #
       def fetch_ref_err(code, year, missed_years) # rubocop:disable Metrics/MethodLength
         id = year ? "#{code}:#{year}" : code
         warn "[relaton-nist] WARNING: no match found online for #{id}. " \

data/lib/relaton_nist/version.rb

@@ -1,3 +1,3 @@
 module RelatonNist
-  VERSION = "1.12.4".freeze
+  VERSION = "1.13.1".freeze
 end

data/relaton_nist.gemspec

@@ -32,6 +32,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "vcr"
   spec.add_development_dependency "webmock"
 
-  spec.add_dependency "relaton-bib", "~> 1.12.0"
+  spec.add_dependency "relaton-bib", "~> 1.13.0"
   spec.add_dependency "rubyzip"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: relaton-nist
 version: !ruby/object:Gem::Version
-  version: 1.12.4
+  version: 1.13.1
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-07-17 00:00:00.000000000 Z
+date: 2022-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: equivalent-xml
@@ -128,14 +128,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.12.0
+        version: 1.13.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.12.0
+        version: 1.13.0
 - !ruby/object:Gem::Dependency
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement