relaton-render 1.3.0 → 1.4.0.pre.alpha.2

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    module Iso690
+      # Field resolver: builds the template evaluator's field table from a
+      # relaton model instance. Slots resolve to ISO 690 clause 7 data
+      # elements, to name-form fields of the principal creator, or to the
+      # disambiguator supplied by the citation caller.
+      class Fields
+        ELEMENT_SLOTS = %i[
+          creator title edition medium series production
+          date numeration component_part identifier location
+        ].freeze
+
+        def initialize(model, style:, i18n:, disambiguator: nil)
+          @model = model
+          @style = style
+          @i18n = i18n
+          @disambiguator = disambiguator.to_s
+        end
+
+        def to_h
+          table = {}
+          ELEMENT_SLOTS.each do |slot|
+            key = slot.to_s.delete("_").downcase
+            table[key] = element_field(slot)
+          end
+          table.merge(name_fields)
+        end
+
+        private
+
+        def element_field(slot)
+          element = Elements.build(slot, @model, style: @style, i18n: @i18n)
+          text = element.render.to_s
+          Template::Field[element.present? && !text.empty?, text]
+        end
+
+        def name_fields
+          creator = Elements.build(:creator, @model, style: @style, i18n: @i18n)
+          {
+            "surname" => Template::Field[creator.present?, creator.in_text],
+            "givennames" => Template::Field[!creator.principal_given.empty?,
+                                            creator.principal_given],
+            "disambiguator" => Template::Field[!@disambiguator.empty?,
+                                               @disambiguator],
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+lang: en
+labels:
+  edition: "ed"
+  series_no: "no."
+  report_no: "Report no."
+  available_from: "Available from:"
+  in: "In:"
+  and: "and"
+  oxford_comma: ","
+  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.rb

@@ -0,0 +1,66 @@
+# 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)
+          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
+          ]
+          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)
+              raise ArgumentError, "no i18n declarations for language #{code}"
+            end
+
+            from_yaml(File.read(path))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# 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 register(type, kind)
+            KINDS[type] = kind
+            kind
+          end
+
+          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,43 @@
+# 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",
+          "website" => "online",
+          "webresource" => "online",
+          "webpage" => "online",
+          "online" => "online",
+        }.freeze
+
+        DEFAULT_KIND = "report"
+
+        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,54 @@
+# 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
+        class Unrenderable < StandardError; end
+
+        DEFAULT_STYLE = "author-date"
+
+        class << self
+          def render(model, style: DEFAULT_STYLE, lang: "en", script: "Latn")
+            new(style: style, lang: lang, script: script).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: {})
+          @style = Style.load(style)
+          @i18n = I18n.load(lang).overlay!(@style.scheme.locale)
+          @i18n.overlay_hash!(labels) unless labels.empty?
+          @script = script
+        end
+
+        def render(model)
+          out = Template.new(@style.template_for(Kinds.kind_for(model.type))).evaluate(
+            Fields.new(model, style: @style, i18n: @i18n).to_h,
+          )
+          raise Unrenderable, "no renderable elements" if out.strip.empty?
+
+          out
+        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).to_h,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/relaton/render/iso690/style/locale.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    module Iso690
+      class Style
+        # LocalizedStrings: per-style overrides of the language pack's
+        # connective strings, keyed as in the CitationStyle model.
+        class Locale < Lutaml::Model::Serializable
+          attribute :conj, :string
+          attribute :others, :string
+          attribute :no_date, :string
+          attribute :no_author, :string
+          attribute :in_str, :string
+          attribute :at, :string
+          attribute :available_at, :string
+
+          key_value do
+            map "and", to: :conj
+            map "others", to: :others
+            map "noDate", to: :no_date
+            map "noAuthor", to: :no_author
+            map "in", to: :in_str
+            map "at", to: :at
+            map "availableAt", to: :available_at
+          end
+
+          LABEL_FOR = {
+            "conj" => "and", "others" => "others", "no_date" => "no_date",
+            "no_author" => "no_author", "in_str" => "in", "at" => "at",
+            "available_at" => "available_from",
+          }.freeze
+
+          def label_map
+            LABEL_FOR.filter_map do |attr, label|
+              value = public_send(attr)
+              [label, value] unless value.nil?
+            end.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/relaton/render/iso690/style/name_form.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    module Iso690
+      class Style
+        # How personal names are formed, as declared by the style's
+        # citation scheme (relaton-models NameFormRules).
+        class NameForm < Lutaml::Model::Serializable
+          attribute :initials, :boolean, default: -> { false }
+          attribute :given_name_first, :boolean, default: -> { false }
+
+          key_value do
+            map "initials", to: :initials
+            map "givenNameFirst", to: :given_name_first
+          end
+        end
+      end
+    end
+  end
+end

data/lib/relaton/render/iso690/style/scheme.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    module Iso690
+      class Style
+        # CitationScheme: the citation system, its name form and its
+        # localized strings (relaton-models CitationScheme).
+        class Scheme < Lutaml::Model::Serializable
+          attribute :system, :string, default: "name-date"
+          attribute :name_form, NameForm, default: -> { NameForm.new }
+          attribute :locale, Locale, default: -> { Locale.new }
+
+          key_value do
+            map "system", to: :system
+            map "nameForm", to: :name_form
+            map "locale", to: :locale
+          end
+        end
+      end
+    end
+  end
+end

data/lib/relaton/render/iso690/style/sort_rule.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    module Iso690
+      class Style
+        # SortRule: one ordering key of a bibliographic index sort
+        # (relaton-models SortRule).
+        class SortRule < Lutaml::Model::Serializable
+          attribute :attribute, :string
+          attribute :order, :string
+
+          key_value do
+            map "attribute", to: :attribute
+            map "order", to: :order
+          end
+
+          def descending?
+            order == "descending"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/relaton/render/iso690/style/template_map.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    module Iso690
+      class Style
+        # TemplateMap: citation and reference templates as data, plus the
+        # title emphasis markers and the first-creator name form. Slots
+        # name ISO 690 clause 7 data elements or name-form fields.
+        class TemplateMap < Lutaml::Model::Serializable
+          attribute :title_open, :string, default: "_"
+          attribute :title_close, :string, default: "_"
+          attribute :citation, :string, default: "{{surname}}, {{date}}"
+          attribute :reference, :string
+          attribute :name, :string, default: "{{surname}}, {{givenNames}}"
+
+          key_value do
+            map "titleOpen", to: :title_open
+            map "titleClose", to: :title_close
+            map "citation", to: :citation
+            map "reference", to: :reference
+            map "name", to: :name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/relaton/render/iso690/style/type_template.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    module Iso690
+      class Style
+        # TypeTemplate: the template variant for one bibliographic item
+        # type, selected by data lookup (relaton-models TypeTemplate).
+        class TypeTemplate < Lutaml::Model::Serializable
+          attribute :type, :string
+          attribute :template, :string
+
+          key_value do
+            map "type", to: :type
+            map "template", to: :template
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Relaton
+  module Render
+    module Iso690
+      # A citation style as an instance of the relaton-models CitationStyle
+      # model: the citation scheme (name form, localized strings), the
+      # citation and reference templates, and per-type template variants.
+      # All rendering knowledge is data; the engine holds no styles, no
+      # vocabularies, no localized strings.
+      class Style < Lutaml::Model::Serializable
+        autoload :NameForm, "relaton/render/iso690/style/name_form"
+        autoload :Locale, "relaton/render/iso690/style/locale"
+        autoload :Scheme, "relaton/render/iso690/style/scheme"
+        autoload :TemplateMap, "relaton/render/iso690/style/template_map"
+        autoload :SortRule, "relaton/render/iso690/style/sort_rule"
+        autoload :TypeTemplate, "relaton/render/iso690/style/type_template"
+
+        attribute :name, :string
+        attribute :scheme, Scheme, default: -> { Scheme.new }
+        attribute :templates, TemplateMap, default: -> { TemplateMap.new }
+        attribute :per_type, TypeTemplate, collection: true, default: []
+        attribute :sort_key, SortRule, collection: true, default: []
+
+        key_value do
+          map "name", to: :name
+          map "scheme", to: :scheme
+          map "templates", to: :templates
+          map "perType", to: :per_type
+          map "sortKey", to: :sort_key
+        end
+
+        # The index sort rules; creator then date when the style declares
+        # none (the name-and-date default).
+        def sort_keys
+          return sort_key unless sort_key.empty?
+
+          [SortRule.new(attribute: "creator"), SortRule.new(attribute: "date")]
+        end
+
+        # Per-type template selection is a data lookup; unmatched types
+        # fall back to the general reference template.
+        def template_for(type)
+          per_type.find { |t| t.type == type.to_s }&.template ||
+            templates.reference
+        end
+
+        # First-creator name form: the style's declared name template with
+        # the surname upcased, per the name-and-date convention.
+        def render_name(surname:, given:)
+          Template.new(templates.name).evaluate(
+            "surname" => Template::Field[!surname.empty?, surname.upcase],
+            "givennames" => Template::Field[!given.empty?, given],
+          )
+        end
+
+        class << self
+          def load(name_or_path)
+            path = style_path(name_or_path) or
+              raise ArgumentError, "unknown style #{name_or_path}"
+            from_yaml(File.read(path))
+          end
+
+          private
+
+          def style_path(name)
+            file = File.join(__dir__, "styles", "#{name}.yml")
+            return file if File.file?(file)
+
+            name if name.is_a?(String) && File.file?(name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/relaton/render/iso690/styles/author-date.yml

@@ -0,0 +1,28 @@
+# ISO 690 name-and-date citation style, an instance of the relaton-models
+# CitationStyle model. Templates place the ISO 690 clause 7 data elements
+# ({{creator}}, {{title}}, ...) in each resource kind's clause 8 order; an
+# absent element takes its trailing punctuation with it. A new style is a
+# YAML instance — the engine holds no styles.
+name: "ISO 690 (name and date)"
+scheme:
+  system: name-date
+  nameForm:
+    initials: false
+    givenNameFirst: false
+templates:
+  titleOpen: "_"
+  titleClose: "_"
+  citation: "{{surname}}, {{date}}{{disambiguator}}"
+  reference: "{{creator}}. {{title}}. {{medium}}. {{edition}}. {{series}}. {{production}}, {{date}}. {{identifier}}. {{location}}."
+  name: "{{surname}}, {{givenNames}}"
+perType:
+  - type: monograph
+    template: "{{creator}}. {{title}}. {{edition}}. {{series}}. {{production}}, {{date}}. {{identifier}}. {{location}}."
+  - type: report
+    template: "{{creator}}. {{title}}. {{numeration}}. {{edition}}. {{series}}. {{production}}, {{date}}. {{identifier}}. {{location}}."
+  - type: patent
+    template: "{{creator}}. {{title}}. {{identifier}}. {{date}}."
+  - type: continuing
+    template: "{{creator}}. {{title}}. {{componentPart}}. {{medium}}. {{edition}}. {{production}}, {{date}}. {{numeration}}. {{identifier}}. {{location}}."
+  - type: online
+    template: "{{creator}}. {{title}}. {{date}}. {{identifier}}. {{location}}."