relaton-bib 0.9.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 103eab0d5c12a5bdb75281aebd1f59ad96e81da707f69c09355d9bf05f841f1a
-  data.tar.gz: 3c51acb08e97d791e977a6752db949683f67e60e8402f7d0c6d3aa43ac4c4d95
+  metadata.gz: 2cf0aacc339840ecc4607d6b87e625eaef60ba12ab0fbeffba5876898518f138
+  data.tar.gz: e41a599b99baaa6d1002cd3ad13803bcffeaa6949840a8cd757db3689716f06b
 SHA512:
-  metadata.gz: c1c9e8003d2f2c859a6600381955e61f3bdc540a1504b17eda23cfce99271b657e178173d123f89cafff8eadb19c5dd3a67c89714ecb83035d40053debaaadb6
-  data.tar.gz: f9607f2ff6b590a10b190e00d1e512148ecbfe9ad60b7a7e1dbea3ae032617817a6aa1dd4836b5cf10ffbb497792639ab1a3ea8496d13518f81fc59df84e08c4
+  metadata.gz: 4f8e1bfe3c6ca8d2ec19733f7ea0f018bae2a102ad92d05bb0983ddf9b7e8715c86c56980ffa106500c2a6971a625143cb6bec2ae9b9a2dd0190fc8b605539c1
+  data.tar.gz: 721ba6235c7cabc380825ce184f0b2874f1ba519b2f6b9dc44fea52ae061b3bdd18ab56c5db94698535b8db10fe365a88aaf23bcd32a25fa5ce7de96bb8a93b6

data/.hound.yml

@@ -0,0 +1,2 @@
+rubocop:
+  config_file: .rubocop.yml

data/README.adoc

@@ -155,8 +155,16 @@ item = RelatonBib::BibliographicItem.new(
       bibitem: RelatonBib::BibliographicItem.new(
         formattedref: RelatonBib::FormattedRef.new(content: "ISO 19115:2003"),
       ),
-      bib_locality: [
-        RelatonBib::BibItemLocality.new("section", "Reference from"),
+      locality: [
+        RelatonBib::LocalityStack.new([
+          RelatonBib::Locality.new("volume", "1"),
+          RelatonBib::Locality.new("section", "2"),
+        ]),
+      ],
+      source_locality: [
+        RelatonBib::SourceLocalityStack.new([
+          RelatonBib::SourceLocality.new("chapter", "4"),
+        ]),
       ],
     },
     {
@@ -249,7 +257,6 @@ item.abstract
 
 item.abstract(lang: "en").to_s
 => "ISO 19115-1:2014 defines the schema required for ..."
-"
 ----
 
 === BibliographicItem references
@@ -274,11 +281,11 @@ item.to_xml
 ----
 
 Default root element is `bibitem`. With argument `bibdata: true` the XML wrapped with `bibdata` element.
-[source,ruby]
 
+[source,ruby]
 ----
-item.to_xml
-=> "<bibitem id=\"ISO/TC211\" type=\"standard\">
+item.to_xml bibdata: true
+=> "<bibdata type=\"standard\">
       <fetched>2019-04-30</fetched>
       <title type=\"main\" language=\"en\" script=\"Latn\">Geographic information</title>
       ...
@@ -288,8 +295,8 @@ item.to_xml
 ==== Date format
 
 By default date elements are formatted as year (yyyy). Option `:date_format` allows to output date elements in `:short` (yyyy-mm) and `:full` (yyyy-mm-dd) additiona formats.
-[surce,ruby]
 
+[surce,ruby]
 ----
 item.to_xml date_format: :short
 => "<bibitem id=\"ISO/TC211\" type=\"standard\">

data/docs/hash.adoc

@@ -2,24 +2,24 @@
 
 == YAML
 
-The following structure is in place for encoding bibitem as YAML objects, and is also used 
-to represent bibliographic entries in Metanorma Asciidoctor. The structure has not yet been
+The following structure is in place for encoding bibitem as YAML objects, and is also used
+to represent bibliographic entries in Metanorma AsciiDoc. The structure has not yet been
 generalised to `bibdata/ext`, the flavour-specific extensions of relaton.
 
 If an element in Relaton XML has attributes, the content of the element is represented in YAML
 with a `content` key:
 
 [source,xml]
-....
+----
 <title type="main">Geographic information</title>
-....
+----
 
 [source,yaml]
-....
+----
 title:
   type: main
   content: Geographic information
-....
+----
 
 Any elements with a cardinality of many can be represented as arrays, but
 they can also be populated by a hash or single element. For example,
@@ -27,7 +27,7 @@ a Relaton title can have multiple titles, and multiple scripts; so
 the following are equivalent:
 
 [source,yaml]
-....
+----
 title:
   - type: main
     content: Geographic information
@@ -37,7 +37,7 @@ title:
 script:
   - Latn
 script: Latn
-....
+----
 
 In YAML, "on" is a reserved word, and thus cannot be used as a key. "value" is used as a synonym for
 "on" in dates.
@@ -45,7 +45,7 @@ In YAML, "on" is a reserved word, and thus cannot be used as a key. "value" is u
 The structure below is given in YAML format:
 
 [source,yaml]
-....
+----
 # bibliographic item anchor, used to crossreference within document
 id: ISO/TC211
 # date record was created
@@ -118,11 +118,11 @@ abstract:
 # Initials, forename, additions, prefixes are arrays.
 # Name field values are either strings, or hashes, with content and language and script attributes.
 # The language and script attribute can also be given on the name.
-# Contacts are an array, containing either addresses, or other fields. 
-# Addresses are identified as hashes containing a city attribute; they can also contain a street 
+# Contacts are an array, containing either addresses, or other fields.
+# Addresses are identified as hashes containing a city attribute; they can also contain a street
 # (which is an array), a postcode, a state, and a country. The other contact fields
 # are phones, emails, uris; they contain a type giving the field name, and a value.
-# Affiliations are an array, and they contains an organization, and an optional description. 
+# Affiliations are an array, and they contains an organization, and an optional description.
 # The affiliation description can be a single string, or a hash of content, language, script, and format.
 contributor:
   - organization:
@@ -130,7 +130,7 @@ contributor:
       url: www.iso.org
       abbreviation: ISO
       subdivision: division
-    role: 
+    role:
       type: publisher
       description: Publisher role
   - person:
@@ -142,7 +142,7 @@ contributor:
         - organization:
             name: IETF
             abbreviation: IETF
-             identifier:      
+             identifier:
                - type: uri
                  id: www.ietf.org
           description: Affiliation description
@@ -181,7 +181,7 @@ contributor:
       identifier:
         - type: uri
           id: www.person.com
-    role: 
+    role:
       author
 # copyright consists of an owner (a hash containing the fields of an organisation),
 # a "from" date, and an optional "to" date
@@ -220,7 +220,7 @@ relation:
 # an abbreviation, a from, a to, a number, and a partnumber.
 # The series title, like the titles of bibliographic items, contains a type,
 # content, and optional language, script, and format attributes.
-# The abbreviation and formattedref are either a string, 
+# The abbreviation and formattedref are either a string,
 # or a hash containing content, language, and script.
 series:
   - type: main
@@ -241,7 +241,7 @@ series:
     number: serie1234
     partnumber: part5678
   - type: alt
-    formattedref: 
+    formattedref:
       content: serieref
       language: en
       script: Latn
@@ -269,30 +269,30 @@ validity:
   begins: 2010-10-10 12:21
   ends: 2011-02-03 18:30
   revision: 2011-03-04 09:00
-....
+----
 
 == Metanorma structure (AsciiBib): nested definition list
 
-The Metanorma Asciidoctor representation of the Relaton hash structure
+The Metanorma AsciiDoc representation of the Relaton hash structure
 in a bibliography
 is as a definition list of element name and element contents,
 with nested definition lists for nested structures. If a nested
 definition is given for an element, the element itself has a blank definition.
 
-As with the YAML representation, if an element in Relaton XML has attributes, 
+As with the YAML representation, if an element in Relaton XML has attributes,
 the content of the element is represented in YAML with a `content` key:
 
 [source,xml]
-....
+----
 <title type="main">Geographic information</title>
-....
+----
 
 [source,asciidoc]
-....
+----
 title::
   type::: main
   content::: Geographic information
-....
+----
 
 Likewise, as with the YAML representation,
 Repeating elements in a hash can be realised as ordered or unordered lists.
@@ -304,9 +304,9 @@ language::
   . fr
 ----
 
-Metanorma Asciidoctor also supports representing repeating elements
+Metanorma AsciiDoc also supports representing repeating elements
 by repeating the key for that entry. This will almost always be more
-straightforward to use in Asciidoctor:
+straightforward to use in AsciiDoc:
 
 [source,asciidoc]
 ----
@@ -314,19 +314,19 @@ language:: en
 language:: fr
 ----
 
-Each Relaton entry in a bibliography is represented in Metanorma Asciidoctor
+Each Relaton entry in a bibliography is represented in Metanorma AsciiDoc
 through a subclause with option attribute `[%bibitem]`. Any title given to the
 subclause is treated as the title for the bibliographic entry, with language `en`,
-script `Latn`, format `text/plain`, and type `main`. 
+script `Latn`, format `text/plain`, and type `main`.
 
-So the following is a very simple reference in Metanorma Asciidoctor:
+So the following is a very simple reference in Metanorma AsciiDoc:
 
 [source,asciidoc]
 ----
 [%bibitem]
 === Rubber latex -- Sampling
 id:: iso123
-docid:: 
+docid::
   type::: ISO
   id::: ISO 123
 docid::
@@ -355,7 +355,7 @@ content::: Latex de caoutchouc -- Échantillonnage
 Note the use of `content` as a key to represent the contents of the `title` tag.
 
 The anchor crossreference for the bibliographic entry may be encoded as either the
-`id` entry in the definition list, or as the normal Asciidoctor anchor on the
+`id` entry in the definition list, or as the normal AsciiDoc anchor on the
 subclause, which takes priority:
 
 [source,asciidoc]
@@ -363,7 +363,7 @@ subclause, which takes priority:
 [[iso123]]
 [%bibitem]
 === Rubber latex -- Sampling
-docid:: 
+docid::
   type::: ISO
   id::: ISO 123
 type:: standard
@@ -376,7 +376,7 @@ Repeating elements in a hash can be realised as ordered or unordered lists.
 [[iso123]]
 [%bibitem]
 === Rubber latex -- Sampling
-docid:: 
+docid::
   type::: ISO
   id::: ISO 123
 language::
@@ -384,23 +384,23 @@ language::
   . fr
 ----
 
-Metanorma Asciidoctor also supports representing repeating elements  
+Metanorma AsciiDoc also supports representing repeating elements
 by repeating the key for that entry. This will almost always be more
-straightforward to use in Asciidoctor:
+straightforward to use in AsciiDoc:
 
 [source,asciidoc]
 ----
 [[iso123]]
 [%bibitem]
 === Rubber latex -- Sampling
-docid:: 
+docid::
   type::: ISO
   id::: ISO 123
 language:: en
 language:: fr
 ----
 
-Asciidoctor does not recognise definition lists more than four levels
+AsciiDoc does not recognise definition lists more than four levels
 deep. If deeper nesting is needed, you will need to attach a new definition
 list with a list continuation, with the definition list depth reset back to one:
 
@@ -409,7 +409,7 @@ list with a list continuation, with the definition list depth reset back to one:
 [[iso123]]
 [%bibitem]
 === Rubber latex -- Sampling
-docid:: 
+docid::
   type::: ISO
   id::: ISO 123
 type:: standard
@@ -428,25 +428,25 @@ completename::
 (This is very awkward, and <<JSONPath>> provides a workaround.)
 
 The most heavily nested parts of a Relaton entry are the contributors,
-series, and relations. 
+series, and relations.
 Each of these can be marked up as subclauses within the entry, with the clause
 titles "contributor", "series", and "relation". Each subclause contains
 a new definition list, with its definition list reset to zero depth;
 the subclauses can be repeated for multiple instances of the same subentity.
 
-AsciiBib citations can be combined with other Asciidoctor citations in the
-same Metanorma document; but any Asciidoctor citations need be precede
+AsciiBib citations can be combined with other AsciiDoc citations in the
+same Metanorma document; but any AsciiDoc citations need be precede
 AsciiBib citations. Each AsciiBib citations constitutes a subclause of its own,
 and Metanorma will (unsuccessfully) attempt to incorporate any trailing material
-in the subclause, including  Asciidoctor citations, into the current AsciiBib
+in the subclause, including  AsciiDoc citations, into the current AsciiBib
 citation.
 
-The following is Metanorma Asciidoctor markup corresponding to the YAML
+The following is Metanorma AsciiDoc markup corresponding to the YAML
 given above:
 
 
 [source,asciidoc]
-....
+----
 [[ISO/TC211]]
 [%bibitem]
 === {blank}
@@ -547,7 +547,7 @@ organization::
   url::: www.iso.org
   abbreviation::: ISO
   subdivision::: division
-role:: 
+role::
   type::: publisher
   description::: Publisher role
 
@@ -654,15 +654,15 @@ formattedref::
   content::: serieref
   language::: en
   script::: Latn
-....
+----
 
 [[JSONPath]]
 == JSON Path style definition lists
 
 The foregoing structure requires frequent breakouts into open blocks, to deal
-with the limitation on Asciidoctor nested definition lists. An alternative is to
-represent the nested structure of Relaton records in a simple, one-level definition list, 
-and to use the key for each key-value pair to represent the hierarchical nesting of entries, 
+with the limitation on AsciiDoc nested definition lists. An alternative is to
+represent the nested structure of Relaton records in a simple, one-level definition list,
+and to use the key for each key-value pair to represent the hierarchical nesting of entries,
 as a dot-delimited path of keys. For example,
 
 [source,asciidoc]
@@ -670,7 +670,7 @@ as a dot-delimited path of keys. For example,
 [%bibitem]
 === Rubber latex -- Sampling
 id:: iso123
-docid:: 
+docid::
   type::: ISO
   id::: ISO 123
 ----
@@ -693,7 +693,7 @@ Whenever part of the key is repeated between entries, the entries are assumed to
 [%bibitem]
 === Rubber latex -- Sampling
 id:: iso123
-docid:: 
+docid::
   type::: ISO
   id::: ISO 123
 docid::
@@ -754,11 +754,11 @@ contributor.person.contact.type:: phone
 contributor.person.contact.value:: 223322
 ----
 
-The following is Metanorma Asciidoctor markup corresponding to the YAML
+The following is Metanorma AsciiDoc markup corresponding to the YAML
 given above, using JSON Path style definition lists instead of nested definition lists:
 
 [source,asciidoc]
-....
+----
 [[ISO/TC211]]
 [%bibitem]
 === {blank}

data/lib/relaton_bib/bib_item_locality.rb

@@ -1,20 +1,4 @@
 module RelatonBib
-  # class SpecificLocalityType
-  #   SECTION   = 'section'
-  #   CLAUSE    = 'clause'
-  #   PART      = 'part'
-  #   PARAGRAPH = 'paragraph'
-  #   CHAPTER   = 'chapter'
-  #   PAGE      = 'page'
-  #   WHOLE     = 'whole'
-  #   TABLE     = 'table'
-  #   ANNEX     = 'annex'
-  #   FIGURE    = 'figure'
-  #   NOTE      = 'note'
-  #   EXAMPLE   = 'example'
-  #   # generic String is allowed
-  # end
-
   # Bibliographic item locality.
   class BibItemLocality
     # @return [String]
@@ -30,6 +14,13 @@ module RelatonBib
     # @param referenceFrom [String]
     # @param referenceTo [String, NilClass]
     def initialize(type, reference_from, reference_to = nil)
+      type_ptrn = %r{section|clause|part|paragraph|chapter|page|whole|table|
+        annex|figure|note|list|example|volume|issue|time|
+        locality:[a-zA-Z0-9_]+}x
+      unless type =~ type_ptrn
+        warn "[relaton-bib] WARNING: invalid locality type: #{type}"
+      end
+
       @type           = type
       @reference_from = reference_from
       @reference_to   = reference_to
@@ -49,4 +40,56 @@ module RelatonBib
       hash
     end
   end
+
+  class Locality < BibItemLocality
+    # @param builder [Nokogiri::XML::Builder]
+    def to_xml(builder)
+      builder.locality { |b| super(b) }
+    end
+  end
+
+  class LocalityStack
+    include RelatonBib
+
+    # @return [Array<RelatonBib::Locality>]
+    attr_reader :locality
+
+    # @param locality [Array<RelatonBib::Locality>]
+    def initialize(locality)
+      @locality = locality
+    end
+
+    # @param builder [Nokogiri::XML::Builder]
+    def to_xml(builder)
+      builder.localityStack do |b|
+        locality.each { |l| l.to_xml(b) }
+      end
+    end
+
+    # @returnt [Hash]
+    def to_hash
+      { "locality_stack" => single_element_array(locality) }
+    end
+  end
+
+  class SourceLocality < BibItemLocality
+    # @param builder [Nokogiri::XML::Builder]
+    def to_xml(builder)
+      builder.sourceLocality { |b| super(b) }
+    end
+  end
+
+  class SourceLocalityStack < LocalityStack
+    # @param builder [Nokogiri::XML::Builder]
+    def to_xml(builder)
+      builder.sourceLocalityStack do |b|
+        locality.each { |l| l.to_xml(b) }
+      end
+    end
+
+    # @returnt [Hash]
+    def to_hash
+      { "source_locality_stack" => single_element_array(locality) }
+    end
+  end
 end

data/lib/relaton_bib/bibliographic_item.rb

@@ -167,8 +167,12 @@ module RelatonBib
     #
     # @param relation [Array<Hash>]
     # @option relation [String] :type
-    # @option relation [RelatonBib::BibliographicItem, RelatonIso::IsoBibliographicItem] :bibitem
-    # @option relation [Array<RelatonBib::BibItemLocality>] :bib_locality
+    # @option relation [RelatonBib::BibliographicItem,
+    #                   RelatonIso::IsoBibliographicItem] :bibitem
+    # @option relation [Array<RelatonBib::Locality,
+    #                   RelatonBib::LocalityStack>] :locality
+    # @option relation [Array<RelatonBib::SourceLocality,
+    #                   RelatonBib::SourceLocalityStack>] :source_locality
     #
     # @param link [Array<Hash, RelatonBib::TypedUri>]
     # @option link [String] :type

data/lib/relaton_bib/document_relation.rb

@@ -25,17 +25,22 @@ module RelatonBib
     # @return [RelatonBib::BibliographicItem]
     attr_reader :bibitem
 
-    # @return [Array<RelatonBib::BibItemLocality>]
-    attr_reader :bib_locality
+    # @return [Array<RelatonBib::Locality, RelatonBib::LocalityStack>]
+    attr_reader :locality
+
+    # @return [Array<RelatonBib::SourceLocality, RelatonBib::SourceLocalityStack>]
+    attr_reader :source_locality
 
     # @param type [String]
     # @param bibitem [RelatonBib::BibliographicItem, RelatonIso::IsoBibliographicItem]
-    # @param bib_locality [Array<RelatonBib::BibItemLocality>]
-    def initialize(type:, bibitem:, bib_locality: [])
-      type = "obsoletes" if type == "Now withdrawn"
-      @type         = type
-      @bib_locality = bib_locality
-      @bibitem      = bibitem
+    # @param locality [Array<RelatonBib::Locality, RelatonBib::LocalityStack>]
+    # @param source_locality [Array<RelatonBib::SourceLocality, RelatonBib::SourceLocalityStack>]
+    def initialize(type:, bibitem:, locality: [], source_locality: [])
+      type             = "obsoletes" if type == "Now withdrawn"
+      @type            = type
+      @locality        = locality
+      @source_locality = source_locality
+      @bibitem         = bibitem
     end
 
     # @param builder [Nokogiri::XML::Builder]
@@ -44,16 +49,18 @@ module RelatonBib
       opts.delete :note
       builder.relation(type: type) do
         bibitem.to_xml(builder, **opts.merge(embedded: true))
-        bib_locality.each do |l|
-          builder.locality { l.to_xml builder }
-        end
+        locality.each { |l| l.to_xml builder }
+        source_locality.each { |l| l.to_xml builder }
       end
     end
 
     # @return [Hash]
     def to_hash
       hash = { "type" => type, "bibitem" => bibitem.to_hash }
-      hash["bib_locality"] = single_element_array(bib_locality) if bib_locality&.any?
+      hash["locality"] = single_element_array(locality) if locality&.any?
+      if source_locality&.any?
+        hash["source_locality"] = single_element_array(source_locality)
+      end
       hash
     end
   end

data/lib/relaton_bib/document_relation_collection.rb

@@ -1,21 +1,31 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 module RelatonBib
   # Document relation collection
-  class DocRelationCollection < Array
+  class DocRelationCollection
+    extend Forwardable
+
+    def_delegators :@array, :<<, :[], :first, :last, :empty?, :any?, :size,
+      :each, :detect, :map, :length
+
     # @param relation [Array<RelatonBib::DocumentRelation, Hash>]
     # @option relation [String] :type
     # @option relation [String] :identifier
     # @option relation [String, NIllClass] :url (nil)
-    # @option relation [Array<RelatonBib::BibItemLocality>] :bib_locality
+    # @option relation [Array<RelatonBib::Locality,
+    #                   RelatonBib::LocalityStack>] :locality
+    # @option relation [Array<RelatonBib::SourceLocality,
+    #                   RelatonBib::SourceLocalityStack>] :source_locality
     # @option relation [RelatonBib::BibliographicItem, NillClass] :bibitem (nil)
     def initialize(relation)
-      super relation.map { |r| r.is_a?(Hash) ? DocumentRelation.new(r) : r }
+      @array =  relation.map { |r| r.is_a?(Hash) ? DocumentRelation.new(r) : r }
     end
 
-    # @return [Array<RelatonBib::DocumentRelation>]
+    # @return [RelatonBib::DocRelationCollection]
     def replaces
-      select { |r| r.type == "replace" }
+      DocRelationCollection.new @array.select { |r| r.type == "replace" }
     end
   end
 end

data/lib/relaton_bib/hash_converter.rb

@@ -252,40 +252,60 @@ module RelatonBib
         end
       end
 
+      # @param ret [Hash]
       def relations_hash_to_bib(ret)
         return unless ret[:relation]
 
         ret[:relation] = array(ret[:relation])
-        ret[:relation]&.each_with_index do |r, i|
-          relation_bibitem_hash_to_bib(ret, r, i)
-          relation_biblocality_hash_to_bib(ret, r, i)
+        ret[:relation]&.each do |r|
+          relation_bibitem_hash_to_bib(r)
+          relation_locality_hash_to_bib(r)
+          relation_source_locality_hash_to_bib(r)
         end
       end
 
-      # @param ret [Hash]
       # @param rel [Hash] relation
-      # @param idx [Integr] index of relation
-      def relation_bibitem_hash_to_bib(ret, rel, idx)
+      def relation_bibitem_hash_to_bib(rel)
         if rel[:bibitem]
-          ret[:relation][idx][:bibitem] = bib_item(hash_to_bib(rel[:bibitem], true))
+          rel[:bibitem] = bib_item hash_to_bib(rel[:bibitem], true)
         else
           warn "[relaton-bib] bibitem missing: #{rel}"
-          ret[:relation][idx][:bibitem] = nil
+          rel[:bibitem] = nil
         end
       end
 
-      # @param item [Hash]
-      # @retirn [RelatonBib::BibliographicItem]
-      def bib_item(item)
-        BibliographicItem.new(item)
+      # @param item_hash [Hash]
+      # @return [RelatonBib::BibliographicItem]
+      def bib_item(item_hash)
+        BibliographicItem.new item_hash
       end
 
-      def relation_biblocality_hash_to_bib(ret, rel, idx)
-        ret[:relation][idx][:bib_locality] =
-          array(rel[:bib_locality])&.map do |bl|
-            BibItemLocality.new(bl[:type], bl[:reference_from],
-                                bl[:reference_to])
-          end
+      # @param rel [Hash] relation
+      def relation_locality_hash_to_bib(rel)
+        rel[:locality] = array(rel[:locality])&.map do |bl|
+          ls = if bl[:locality_stack]
+                  array(bl[:locality_stack]).map do |l|
+                    Locality.new(l[:type], l[:reference_from], l[:reference_to])
+                  end
+                else
+                  [Locality.new(bl[:type], bl[:reference_from], bl[:reference_to])]
+                end
+          LocalityStack.new ls
+        end
+      end
+
+      # @param rel [Hash] relation
+      def relation_source_locality_hash_to_bib(rel)
+        rel[:source_locality] = array(rel[:source_locality])&.map do |sl|
+          sls = if sl[:source_locality_stack]
+                  array(sl[:source_locality_stack]).map do |l|
+                    SourceLocality.new(l[:type], l[:reference_from], l[:reference_to])
+                  end
+                else
+                  [SourceLocality.new(sl[:type], sl[:reference_from], sl[:reference_to])]
+                end
+          SourceLocalityStack.new sls
+        end
       end
 
       def series_hash_to_bib(ret)

data/lib/relaton_bib/version.rb

@@ -1,3 +1,3 @@
 module RelatonBib
-  VERSION = "0.9.2".freeze
+  VERSION = "1.0.0".freeze
 end

data/lib/relaton_bib/xml_parser.rb

@@ -8,9 +8,9 @@ module RelatonBib
         doc.remove_namespaces!
         bibitem = doc.at "/bibitem|/bibdata"
         if bibitem
-          BibliographicItem.new(item_data(bibitem))
+          bib_item item_data(bibitem)
         else
-          warn "[relato-bib] can't find bibitem or bibdata element in the XML"
+          warn "[relaton-bib] WARNING: can't find bibitem or bibdata element in the XML"
         end
       end
 
@@ -257,6 +257,8 @@ module RelatonBib
         end
       end
 
+      # @param item [Nokogiri::XML::Element]
+      # @return [Array<RelatonBib::ContributionInfo>]
       def fetch_contributors(item)
         item.xpath("./contributor").map do |c|
           entity = if (org = c.at "./organization") then get_org(org)
@@ -269,6 +271,8 @@ module RelatonBib
         end
       end
 
+      # @param item [Nokogiri::XML::Element]
+      # @return [Array<RelatonBib::FormattedString>]
       def fetch_abstract(item)
         item.xpath("./abstract").map do |a|
           FormattedString.new(
@@ -277,6 +281,8 @@ module RelatonBib
         end
       end
 
+      # @param item [Nokogiri::XML::Element]
+      # @return [RelatonBib::CopyrightAssociation]
       def fetch_copyright(item)
         cp     = item.at("./copyright") || return
         org    = cp&.at("owner/organization")
@@ -290,30 +296,71 @@ module RelatonBib
         CopyrightAssociation.new(owner: owner, from: from, to: to)
       end
 
+      # @param item [Nokogiri::XML::Element]
+      # @return [Arra<RelatonBib::TypedUri>]
       def fetch_link(item)
         item.xpath("./uri").map do |l|
           TypedUri.new type: l[:type], content: l.text
         end
       end
 
+      # @param item [Nokogiri::XML::Element]
+      # @return [Array<RelatonBib::DocumentRelation>]
       def fetch_relations(item)
         item.xpath("./relation").map do |rel|
-          localities = rel.xpath("./locality").map do |l|
-            ref_to = (rt = l.at("./referenceTo")) ? LocalizedString.new(rt.text) : nil
-            BibItemLocality.new(
-              l[:type],
-              LocalizedString.new(l.at("./referenceFrom").text),
-              ref_to,
-            )
-          end
           DocumentRelation.new(
             type: rel[:type]&.empty? ? nil : rel[:type],
-            bibitem: BibliographicItem.new(item_data(rel.at("./bibitem"))),
-            bib_locality: localities,
+            bibitem: bib_item(item_data(rel.at("./bibitem"))),
+            locality: localities(rel),
+            source_locality: source_localities(rel),
           )
         end
       end
 
+      # @param item_hash [Hash]
+      # @return [RelatonBib::BibliographicItem]
+      def bib_item(item_hash)
+        BibliographicItem.new item_hash
+      end
+
+      # @param rel [Nokogiri::XML::Element]
+      # @return [Array<RelatonBib::Locality, RelatonBib::LocalityStack>]
+      def localities(rel)
+        rel.xpath("./locality|./localityStack").map do |lc|
+          if lc[:type]
+            LocalityStack.new [locality(lc)]
+          else
+            LocalityStack.new lc.xpath("./locality").map { |l| locality l }
+          end
+        end
+      end
+
+      # @param loc [Nokogiri::XML::Element]
+      # @return [RelatonBib::Locality]
+      def locality(loc, klass = Locality)
+        ref_to = (rt = loc.at("./referenceTo")) ? LocalizedString.new(rt.text) : nil
+        klass.new(
+          loc[:type],
+          LocalizedString.new(loc.at("./referenceFrom").text),
+          ref_to,
+        )
+      end
+
+      # @param rel [Nokogiri::XML::Element]
+      # @return [Array<RelatonBib::SourceLocality, RelatonBib::SourceLocalityStack>]
+      def source_localities(rel)
+        rel.xpath("./sourceLocality|./sourceLocalityStack").map do |lc|
+          if lc[:type]
+            SourceLocalityStack.new [locality(lc, SourceLocality)]
+          else
+            sls = lc.xpath("./sourceLocality").map { |l| locality l, SourceLocality }
+            SourceLocalityStack.new sls
+          end
+        end
+      end
+
+      # @param item [Nokogiri::XML::Element]
+      # @return [RelatonBib::FormattedRef, NilClass]
       def fref(item)
         ident = item&.at("./formattedref")
         return unless ident

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: relaton-bib
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-04-06 00:00:00.000000000 Z
+date: 2020-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: debase
@@ -190,6 +190,7 @@ files:
 - ".github/workflows/windows.yml"
 - ".gitignore"
 - ".gitmodules"
+- ".hound.yml"
 - ".rspec"
 - ".rubocop.yml"
 - Gemfile