relaton-nist 1.12.5 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c73a4a75166a362d34e2d1a4bec088d74863cf1ac9a4eee0798cfa84cbceca6
-  data.tar.gz: 398bd9b074c7c10da66c86047e617e7b643ea6cc3e45f1daa6fdd6f43d38bb4c
+  metadata.gz: c997f338c657a003a0bff7e75b650f59b86d4a72026a0b12734357bc48c10cdc
+  data.tar.gz: 5d76af2d37037bb027f9875180bbcc967ca133260eb4a5494112fe81cccf5e04
 SHA512:
-  metadata.gz: 7695197e53d2d8b8b2048f034c6d47db2ce293f7f8dedafacefae8efb4ad85ed96169f5b317957a228b32bfa1e9a8899b80238aa8be594edd94e89619c9fbb51
-  data.tar.gz: 1b2eb51d32d0b0eb9456242e5727b891468509a55cdc2ce2251fa84857b83d6d29966bb3799557672da7cabc126949f0cc18d6581cb9464caa38293a317a7265
+  metadata.gz: 5971a572c9a7a5aefb4087f96787255687195c3e0cc75a49f740b57af1bb05fa48f56c2bd721cbb4b5aa7e5178cb93048c97a8782d152b4b040dd3158129ba14
+  data.tar.gz: f266510c36ce07666a74b9881e439df01067f6baee05e03c267ce3754bef5dcf24b7391082a4fdc1d8122121f17b1fc30e3ba8377dadd86692ff80cd8efa962d

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

@@ -157,13 +157,13 @@ module RelatonNist
     # @return [RelatonBib::FullName] full name object
     #
     def fullname(person, doc)
-      forename, initial = forename_initial(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,
-                               initial: initial, identifier: ident)
+                               initials: initials, identifier: ident)
     end
 
     #
@@ -174,17 +174,33 @@ module RelatonNist
     #
     # @return [Array<Array<RelatonBib::LocalizedString>>] forename and initials
     #
-    def forename_initial(person, doc)
-      forename = []
-      initial = []
+    def forename_initial(person, doc) # rubocop:disable Metrics/MethodLength
+      fnames = []
       fname = person.at("given_name")&.text
       if fname
         if /^(?<inits>(?:\w[.\s]+|[A-Z]{1,2}$)+)$/ =~ fname
-          inits.split(/[.\s]*/).each { |i| initial << localized_string(i, doc) }
-        else forename << localized_string(fname, doc)
+          ints = inits.split(/[.\s]*/)
+          fnames << forename(doc, fname, ints.shift)
+          ints.each { |i| fnames << forename(doc, nil, i) }
+        else fnames << forename(doc, fname)
         end
       end
-      [forename, initial]
+      [fnames, localized_string(inits, doc)]
+    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)
+      RelatonBib::Forename.new(
+        content: cnt, language: doc["language"], script: "Latn", initial: init,
+      )
     end
 
     #

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.5".freeze
+  VERSION = "1.13.0".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.5
+  version: 1.13.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-07-23 00:00:00.000000000 Z
+date: 2022-08-21 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