relaton 3.0.7 → 3.1.0

data/lib/relaton/render/iso690/i18n/en.yml

@@ -0,0 +1,48 @@
+lang: en
+labels:
+  edition: "ed"
+  ordinal_word_1: "First"
+  ordinal_word_2: "Second"
+  ordinal_word_3: "Third"
+  ordinal_word_4: "Fourth"
+  ordinal_word_5: "Fifth"
+  ordinal_word_6: "Sixth"
+  ordinal_word_7: "Seventh"
+  ordinal_word_8: "Eighth"
+  ordinal_word_9: "Ninth"
+  ordinal_word_10: "Tenth"
+  size_volume: "vol."
+  size_page: "pp."
+  page: "p. %"
+  pages: "pp. %"
+  volume: "vol. %"
+  issue: "no. %"
+  no_place: "n.p."
+  version: "Version"
+  medium_website: "[website]"
+  viewed: "viewed"
+  month_1: "January"
+  month_2: "February"
+  month_3: "March"
+  month_4: "April"
+  month_5: "May"
+  month_6: "June"
+  month_7: "July"
+  month_8: "August"
+  month_9: "September"
+  month_10: "October"
+  month_11: "November"
+  month_12: "December"
+
+  series_no: "no."
+  report_no: "Report no."
+  available_from: "Available from:"
+  at_url: "At:"
+  in: "In:"
+  and: "and"
+  oxford_comma: ","
+  others: "et al."
+  ed: "ed."
+  eds: "eds."
+  date_range: "–"
+punct: {}

data/lib/relaton/render/iso690/i18n/fr.yml

@@ -0,0 +1,14 @@
+lang: fr
+labels:
+  edition: "éd"
+  series_no: "n°"
+  report_no: "Rapport no."
+  available_from: "Disponible sur :"
+  in: "Dans :"
+  and: "et"
+  oxford_comma: ""
+  ed: "éd."
+  eds: "éd."
+  date_range: "–"
+punct:
+  production_sep: " : "

data/lib/relaton/render/iso690/i18n/ja.yml

@@ -0,0 +1,38 @@
+lang: ja
+labels:
+  edition: "版"
+  size_volume: "巻"
+  size_page: "頁"
+  page: "%頁"
+  pages: "%頁"
+  volume: "巻%"
+  issue: "%号"
+  version: "版"
+  viewed: "閲覧"
+  series_no: "番号"
+  report_no: "報告番号"
+  available_from: "入手先："
+  at_url: "URL："
+  in: "収録："
+  ed: "編"
+  eds: "編"
+  updated: "更新"
+  no_place: "出版地不明"
+  edition_cardinal: "第{{ var1 }}版"
+  edition_ordinal: "第{{ var1 }}版"
+  version_cardinal: "第{{ var1 }}版"
+  in_series: "シリーズ"
+  list_separator: "、 "
+  and: ""
+  oxford_comma: ""
+  date_range: "〜"
+punct:
+  size-join: ""
+  marker-space: ""
+  production_sep: "： "
+  cjk-latin-separator: "、 "
+  period: "。"
+  comma: "、"
+  colon: "："
+  open-paren: "（"
+  close-paren: "）"

data/lib/relaton/render/iso690/i18n.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Relaton
+  module Render
+    module Iso690
+      # Language-specific labels and typographic punctuation, declared per
+      # language in i18n/<lang>.yml. Adding a language adds a YAML
+      # declaration — no code. A style instance's localized strings overlay
+      # the language pack; language-varying intra-element punctuation
+      # (e.g. French " : " production separator) is declared under
+      # `punct:`.
+      class I18n < Lutaml::Model::Serializable
+        attribute :lang, :string, default: "en"
+        attribute :labels, :hash, default: {}
+        attribute :punct, :hash, default: {}
+
+        key_value do
+          map "lang", to: :lang
+          map "labels", to: :labels
+          map "punct", to: :punct
+        end
+
+        def label(key)
+          labels.fetch(key.to_s, key.to_s)
+        end
+
+        def punct_fetch(key, default)
+          punct.fetch(key, default)
+        end
+
+        # Style-instance localized strings win over the language pack.
+        def overlay!(locale)
+          labels.merge!(locale.label_map)
+          punct.merge!(locale.punct || {})
+          self
+        end
+
+        # Runtime label overrides (a caller's i18n hash): the pack's label
+        # names win as the key mapping; unknown keys are ignored.
+        def overlay_hash!(hash)
+          known = %w[
+            edition series_no report_no available_from in and oxford_comma
+            ed eds date_range others no_date no_author at
+            edition_ordinal edition_cardinal version_cardinal
+          ]
+          hash.each do |key, value|
+            labels[key.to_s] = value if known.include?(key.to_s) && !value.nil?
+          end
+          self
+        end
+
+        class << self
+          def load(lang = "en")
+            code = lang.to_s.empty? ? "en" : lang
+            path = File.join(__dir__, "i18n", "#{code}.yml")
+            unless File.file?(path)
+              # 1.x carried declarations for every locale isodoc uses; the
+              # v2 packs are per-style data. Unknown languages fall back to
+              # the English pack rather than killing the whole conversion.
+              fallback_warn(code)
+              path = File.join(__dir__, "i18n", "en.yml")
+              raise ArgumentError, "no i18n declarations for language #{code}" unless File.file?(path)
+              # The pack supplies the labels; the requested language still
+              # governs localization (bilingual titles select by it)
+              return from_yaml(File.read(path)).tap { |i| i.lang = code }
+            end
+
+            from_yaml(File.read(path))
+          end
+
+          def fallback_warn(code)
+            (@fallback_warned ||= {})[code] and return
+            @fallback_warned[code] = true
+            warn "relaton-render: no i18n declarations for language " \
+                 "#{code}; falling back to en"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/relaton/render/iso690/identifier_kinds.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    module Iso690
+      # Standard and persistent identifiers (ISO 690 clause 7.11): each
+      # identifier kind carries its own rendering method. Kinds are keyed by
+      # the docidentifier's type attribute — never guessed from content.
+      # Flavors register additional kinds (e.g. Pubid::Iala's MRN).
+      module IdentifierKinds
+        KINDS = {
+          "DOI" => ->(content) { "https://doi.org/#{content}" },
+          "ISBN" => ->(content) { "ISBN #{content}" },
+          "ISSN" => ->(content) { "ISSN #{content}" },
+          "URN" => ->(content) { content },
+          "MRN" => ->(content) { content },
+        }.freeze
+
+        class << self
+          def render(docidentifier)
+            content = docidentifier.content.to_s
+            kind = KINDS[docidentifier.type]
+            kind ? kind.call(content) : content
+          end
+        end
+      end
+    end
+  end
+end

data/lib/relaton/render/iso690/index_renderer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    module Iso690
+      # A bibliographic index: the ordered reference list, laid out per the
+      # BibliographicStyle instance. Sorting follows the style's declared
+      # sortKey rules (creator, then date); numbering is layout data.
+      class IndexRenderer
+        def initialize(style: "author-date", lang: "en", script: "Latn")
+          @style = Style.load(style)
+          @i18n = I18n.load(lang).overlay!(@style.scheme.locale)
+          @renderer = Renderer.new(style: style, lang: lang, script: script)
+        end
+
+        # The reference strings, sorted per the style's sortKey rules.
+        def references(models)
+          sort_rules = @style.sort_keys
+          fields = models.to_h { |m| [m, field_table(m)] }
+          models.sort do |a, b|
+            fa = fields[a]
+            fb = fields[b]
+            sort_rules.each do |rule|
+              cmp = key_of(fa, rule) <=> key_of(fb, rule)
+              next if cmp.zero?
+
+              break(rule.descending? ? -cmp : cmp)
+            end || 0
+          end.map { |model| @renderer.render(model) }
+        end
+
+        # The laid-out index: numbered entries per the layout rules
+        # (arabic by default; "none" renders bare references).
+        def render(models, numbering: "arabic")
+          refs = references(models)
+          return refs if numbering == "none"
+
+          refs.each_with_index.map { |ref, i| "#{i + 1}. #{ref}" }
+        end
+
+        private
+
+        def field_table(model)
+          Fields.new(model, style: @style, i18n: @i18n).to_h
+        end
+
+        def key_of(fields, rule)
+          field = fields[rule.attribute.to_s.delete("_").downcase]
+          return "" if field.nil?
+
+          text = field.respond_to?(:text) ? field.text : field.to_s
+          text.downcase
+        end
+      end
+    end
+  end
+end

data/lib/relaton/render/iso690/kinds.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    module Iso690
+      # The vocabulary mapping from a bibliographic item's wire type value
+      # to its ISO 690 clause 8 resource kind (TemplateType). This table is
+      # the engine's charter — style instances select perType templates on
+      # kinds and never enumerate type synonyms. Unmapped values fall to
+      # the report kind (clause 8.11), the runner's fallback.
+      module Kinds
+        TO_KIND = {
+          "book" => "monograph",
+          "booklet" => "monograph",
+          "manual" => "monograph",
+          "proceedings" => "monograph",
+          "thesis" => "monograph",
+          "standard" => "report",
+          "techreport" => "report",
+          "report" => "report",
+          "patent" => "patent",
+          "journal" => "continuing",
+          "serial" => "continuing",
+          "article-journal" => "continuing",
+          "article-magazine" => "continuing",
+          "inbook" => "component_part",
+          "incollection" => "component_part",
+          "inproceedings" => "component_part",
+          "article" => "serial_part",
+          "software" => "online",
+          "unpublished" => "online",
+          "dataset" => "online",
+          "website" => "webdoc",
+          "webresource" => "webdoc",
+          "webpage" => "online",
+          "online" => "online",
+        }.freeze
+
+        DEFAULT_KIND = "report"
+
+        class << self
+          def mapped?(type)
+            TO_KIND.key?(type.to_s)
+          end
+        end
+
+        def self.kind_for(type)
+          TO_KIND.fetch(type.to_s, DEFAULT_KIND)
+        end
+      end
+    end
+  end
+end

data/lib/relaton/render/iso690/renderer.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    module Iso690
+      # Public API: relaton model in, citation string out. The style
+      # instance supplies every rendering decision; this class only wires
+      # the template evaluator to the field resolver. No XML, no
+      # intermediate hashes.
+      class Renderer
+        DEFAULT_STYLE = "author-date"
+
+        class << self
+          def render(model, style: DEFAULT_STYLE, lang: "en", script: "Latn",
+                     elements: {})
+            new(style: style, lang: lang, script: script,
+                elements: elements).render(model)
+          end
+
+          def citation(model, disambiguator: nil, style: DEFAULT_STYLE,
+                       lang: "en", script: "Latn")
+            new(style: style, lang: lang, script: script)
+              .citation(model, disambiguator: disambiguator)
+          end
+        end
+
+        def initialize(style: DEFAULT_STYLE, lang: "en", script: "Latn",
+                       labels: {}, elements: {})
+          @style = Style.load(style)
+          @elements = Rules.resolve(@style.rules, elements)
+          @i18n = I18n.load(lang)
+          @i18n.overlay_hash!(labels) unless labels.empty?
+          # The style instance is the citation-style authority: its
+          # declared strings win over the caller's generic i18n hash
+          @i18n.overlay!(@style.scheme.locale)
+          @script = script
+        end
+
+        def render(model, disambiguator: nil)
+          kind = @style.kind_for(model.type)
+          template = @style.template_for(kind, home: home_docid?(model))
+          out = Template.new(template).evaluate(
+            Fields.new(model, style: @style, i18n: @i18n,
+                       disambiguator: disambiguator,
+                       elements: @elements).to_h,
+          )
+          raise ::Relaton::Render::Unrenderable,
+                "no renderable elements" if out.strip.empty?
+
+          out
+        end
+
+        def home_docid?(model)
+          types = Array(@style.scheme.home_docid_type)
+          return false if types.empty?
+
+          Array(model.docidentifier).any? { |d| types.include?(d.type) }
+        end
+
+        # A creator list alone (flavors' document-history name forms)
+        def render_creators(model)
+          Elements.build(:creator, model, style: @style, i18n: @i18n,
+                         short: true, elements: @elements).render
+        end
+
+        # The short cite: the reference with the first-biblio marker
+        def render_short(model, delim)
+          kind = @style.kind_for(model.type)
+          template = @style.short_template_for(kind,
+                                               home: home_docid?(model)) ||
+            @style.template_for(kind, home: home_docid?(model))
+          Template.new(template).evaluate_short(
+            Fields.new(model, style: @style, i18n: @i18n, short: true,
+                       elements: @elements).to_h,
+            delim,
+          )
+        rescue ::Relaton::Render::Unrenderable
+          ""
+        end
+
+        # The in-text creator with its et-al truncation: the
+        # author-date tag's author part
+        def in_text_author(model)
+          Elements.build(:creator, model, style: @style, i18n: @i18n,
+                         elements: @elements).in_text
+        end
+
+        # The author-date in-text capsule ("Aluffi <em>et al.</em>
+        # 2022a"): the in-text creator and the disambiguated date
+        def author_date_citation(model, disambiguator: nil)
+          f = Fields.new(model, style: @style, i18n: @i18n,
+                         disambiguator: disambiguator,
+                         elements: @elements).to_h
+          [in_text_author(model), f["disambiguateddate"].text]
+            .reject(&:empty?).join(" ")
+        end
+
+        # The bracketed author-date in-text capsule ("Aluffi （2022）"):
+        # the author and the PLAIN date (un-disambiguated, the 1.x
+        # citetemplate's {{ date }}) in the locale's parentheses
+        def bracketed_date_citation(model, **)
+          f = Fields.new(model, style: @style, i18n: @i18n,
+                         elements: @elements).to_h
+          date = f["date"].text
+          return "" if date.empty?
+
+          open = @i18n.punct_fetch("open-paren", "(")
+          close = @i18n.punct_fetch("close-paren", ")")
+          [in_text_author(model), "#{open}#{date}#{close}"]
+            .reject(&:empty?).join(" ")
+        end
+
+        # The disambiguated date alone (the citation renderings' date)
+        def disambiguated_date(model, disambiguator: nil)
+          Fields.new(model, style: @style, i18n: @i18n,
+                     disambiguator: disambiguator,
+                     elements: @elements).to_h["disambiguateddate"].text
+        end
+
+        def short_from_reference?
+          @style.scheme.short_from_reference
+        end
+
+        # The title citation ("{{ title }}" in the 1.x citetemplate):
+        # the title element's plain form, no style markers
+        def title_citation(model)
+          Elements.build(:title, model, style: @style, i18n: @i18n,
+                         elements: @elements).plain
+        end
+
+        # The in-text author key (the principal creator's surname, as
+        # the citation renders it): the batch disambiguation groups by
+        # it
+        def author_key(model)
+          Fields.new(model, style: @style, i18n: @i18n,
+                     elements: @elements).to_h["surname"].text
+        end
+
+        # In-text form: SURNAME, year + disambiguator (name-and-date)
+        def citation(model, disambiguator: nil)
+          Template.new(@style.templates.citation).evaluate(
+            Fields.new(model, style: @style, i18n: @i18n,
+                       disambiguator: disambiguator,
+                       elements: @elements).to_h,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/relaton/render/iso690/rules/bipm.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    module Iso690
+      module Rules
+        # The BIPM rule set, moved verbatim from the metanorma-bipm
+        # flavor's BipmElements: the affiliation-free organization
+        # creator, the bold-volume journal numeration, the
+        # no-place-with-publisher production, the separator-carrying
+        # edition and medium, and the component-part host order.
+        # Select from pack data:
+        #   rules: { creator: bipm_creator, ... }
+        module Bipm
+          # The BIPM component-part order: the host editors before the
+          # host title, the host medium after it, and the production
+          # parenthesized with its own trailing period
+          class BipmComponentPart < Elements::ComponentPart
+            def render
+              h = host or return ""
+              out = +"#{lead}#{host_names(h)} (#{eds_label(h)})"
+              out += " #{host_title}" unless host_title_text.empty?
+              out += medium_text(h)
+              out += production_text(h)
+              out
+            end
+
+            private
+
+            def host_editors(h)
+              Array(h.contributor).select { |c| has_role?(c, "editor") }
+            end
+
+            def eds_label(h)
+              @i18n.label(host_editors(h).one? ? "ed" : "eds")
+            end
+
+            def host_names(h)
+              names = host_editors(h).map { |c|
+                person = c.person or next ""
+
+                [person_surname(person), person_given(person)].reject(&:empty?)
+                  .join(" ")
+              }.reject(&:empty?)
+              join_names(names)
+            end
+
+            def medium_text(h)
+              BipmMedium.new(h, style: @style, i18n: @i18n).render.to_s
+            end
+
+            def production_text(h)
+              production = Elements::Production
+                .new(h, style: @style, i18n: @i18n).render.to_s
+              production.empty? ? "" : " (#{production})."
+            end
+          end
+
+          # The BIPM journal numeration: the volume bold and the issue
+          # in parens, pages unlabelled. Separate extent elements join
+          # with semicolons, localities within one element with spaces
+          class BipmExtent < Elements::Extent
+            def render
+              groups = extent_locality_groups.map { |g| group_text(g) }
+                .reject(&:empty?)
+              groups.join("; ")
+            end
+
+            private
+
+            def extent_locality_groups
+              Array(@model.extent).map do |e|
+                Array(e.locality) +
+                  Array(e.locality_stack).flat_map { |s| Array(s.locality) }
+              end
+            end
+
+            def group_text(localities)
+              volume = plain_locality(localities, "volume")
+              volume = volume.empty? ? "" : "<strong>#{volume}</strong>"
+              issue = plain_locality(localities, "issue")
+              issue = issue.empty? ? "" : "(#{issue})"
+              [volume, issue, page_text(localities)].reject(&:empty?).join(" ")
+            end
+
+            def plain_locality(localities, type)
+              loc = localities.find { |l| l.type == type } or return ""
+              loc.reference_from.to_s
+            end
+
+            def page_text(localities)
+              loc = localities.find { |l| l.type == "page" } or return ""
+              from = loc.reference_from.to_s
+              to = loc.reference_to.to_s
+              text = to.empty? || to == from ? from :
+                "#{from}#{@i18n.label('date_range')}#{to}"
+              return text if item_kind == "serial_part"
+
+              label = @i18n.label(to.empty? || to == from ? "page" : "pages")
+              # the page labels are %-templates ("pp. %"); the block
+              # form keeps a % in the cited text from re-expanding
+              label.include?("%") ? label.gsub("%") { text } : "#{label} #{text}"
+            end
+          end
+
+          # The BIPM production: the no-place placeholder stands only
+          # with a publisher ("(n.p.: Publisher)"); a nameless
+          # publisher drops the production entirely
+          class BipmProduction < Elements::Production
+            private
+
+            def no_place_production
+              return "" if publishers.empty?
+
+              super
+            end
+          end
+
+          # The serial volume, bold, from the size's volume value
+          class BipmVolume < Element
+            def present?
+              !render.empty?
+            end
+
+            def render
+              volume = Array(@model.size&.value).find do |v|
+                !v.is_a?(String) && !v.is_a?(Hash) && v.type == "volume"
+              end or return ""
+
+              "<strong>#{volume.content}</strong>"
+            end
+          end
+
+          # The BIPM medium, verbatim and bracketed with its leading
+          # separator (" [Online]", " [dataset]") — an absent medium
+          # attaches to nothing
+          class BipmMedium < Elements::Medium
+            private
+
+            def medium
+              m = @model.medium or return ""
+              text = m.carrier.to_s
+              text = m.genre.to_s if text.empty?
+              text = [m.form.to_s, m.size.to_s].reject(&:empty?)
+                .join(", ") if text.empty?
+              text.empty? ? "" : " [#{text}]"
+            end
+          end
+
+          # The BIPM edition carries its own leading separator (",
+          # First edition" for monographs, ". Version 2" online), so
+          # its absence drops the separator with it
+          class BipmEdition < Elements::Edition
+            def render
+              text = super.to_s
+              sep = item_kind == "monograph" ? ", " : ". "
+              text.empty? ? "" : "#{sep}#{text}"
+            end
+          end
+
+          # The BIPM organization creator: the name alone, no
+          # abbreviation suffix. Standards without personal creators
+          # cite their publisher's name; monographs cite nothing
+          class BipmCreator < Elements::Creator
+            private
+
+            def org_name(contributor)
+              Array(contributor.organization&.name).map { |n| localized(n) }
+                .join(", ")
+            end
+
+            def fallback_name
+              return "" if %w[monograph continuing component_part]
+                .include?(@style.kind_for(@model.type))
+
+              publishers = contributors("publisher").filter_map do |c|
+                localized(Array(c.organization&.name).first)
+              end
+              publishers.reject(&:empty?).first.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end