relaton-render 0.4.2 → 3.0.0.pre.alpha.26

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

@@ -0,0 +1,148 @@
+# 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")
+            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: {}, 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.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Render
+    module Iso690
+      # The named-rule registry: presentation-of-models implementations
+      # the engine ships once, addressable from pack data as
+      # rules: { slot: rule_name }. Flavors migrate their ELEMENTS maps
+      # onto registered rules; nothing references a flavor class.
+      module Rules
+        REGISTRY = {}
+
+        class << self
+          def register(name, klass)
+            REGISTRY[name.to_s] = klass
+          end
+
+          # A pack's rule selections become the renderer's element map;
+          # caller-supplied elements win over the pack's selections
+          def resolve(rules, elements = {})
+            Array(rules).to_h { |slot, name| [slot.to_sym, fetch(name)] }
+              .merge(elements || {})
+          end
+
+          private
+
+          def fetch(name)
+            REGISTRY.fetch(name.to_s) do
+              raise ArgumentError, "unknown citation style rule #{name}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# 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
+          # Arbitrary label overrides (edition words, join punctuation,
+          # size units): merged over the language pack verbatim.
+          attribute :labels, :hash, default: -> { {} }
+          # Typographic punctuation overrides (production order and
+          # separator), declared as in the language packs
+          attribute :punct, :hash, default: -> { {} }
+
+          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
+            map "labels", to: :labels
+            map "punct", to: :punct
+          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
+            base = LABEL_FOR.filter_map do |attr, label|
+              value = public_send(attr)
+              [label, value] unless value.nil?
+            end.to_h
+            base.merge(labels || {})
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# 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 }
+          # Where an all-editor creator list's role marker sits relative
+          # to the name's terminating period: "glue" renders
+          # "NAME (eds.)." (the name-date default), "afterPeriod"
+          # renders "NAME. (eds.)" (ISO 690 clause-flavour).
+          attribute :role_placement, :string, default: "glue"
+          # A completename is rendered, not decomposed; styles that
+          # upcase inverted names may declare the completename treatment
+          attribute :completename_upcase, :boolean, default: -> { false }
+          # Every personal name takes the inverted form (surname first),
+          # not just the principal creator
+          attribute :inverted_all, :boolean, default: -> { false }
+          # "serial": the oxford comma appears at every gap of the
+          # creator list, including between two names
+          attribute :list_style, :string, default: ""
+          # Organization names take the inverted form's casing; small-cap
+          # styles keep the declared case
+          attribute :org_upcase, :boolean, default: -> { true }
+          # When no personal creator exists, the creator slot falls back
+          # to the publisher's abbreviation ("ISO: ISO 712, ...")
+          attribute :creator_fallback, :string
+          # A lone editor still carries the role marker ("(ed.)")
+          attribute :lone_editor_marked, :boolean, default: -> { false }
+          # Initials without their trailing periods ("Nixon RM")
+          attribute :initials_period, :boolean, default: -> { true }
+          # The inverted form's surname casing: the name-date convention
+          # upcases; small-cap styles keep the declared case
+          attribute :surname_upcase, :boolean, default: -> { true }
+          # Initials are a list; this separates them ("J. K." vs "J.K.")
+          attribute :initials_separator, :string, default: " "
+          # The first forename cites in full, the rest as initials
+          # ("Milena S."; document-history name forms)
+          attribute :subsequent_initials, :boolean, default: -> { false }
+          # The direct-order surname casing after the first creator:
+          # the name-date convention upcases
+          attribute :subsequent_surname_upcase, :boolean,
+                    default: -> { true }
+          # At this many creators the creator list truncates to the
+          # first etalDisplay names with "et al." (0 disables)
+          attribute :etal_count, :integer, default: 0
+          attribute :etal_display, :integer, default: 0
+          # The in-text cite truncates separately from the creator
+          # list: at this many creators it shows the first
+          # inTextEtalDisplay names with "et al." (0 disables; IEEE
+          # cites 3+ as "Aluffi et al." while listing 6 in the
+          # bibliography)
+          attribute :in_text_etal_count, :integer, default: 0
+          attribute :in_text_etal_display, :integer, default: 1
+          # Editor lists carry the role marker ("(Eds.)")
+          attribute :editors_marked, :boolean, default: -> { true }
+
+          key_value do
+            map "initials", to: :initials
+            map "givenNameFirst", to: :given_name_first
+            map "rolePlacement", to: :role_placement
+            map "completenameUpcase", to: :completename_upcase
+            map "invertedAll", to: :inverted_all
+            map "listStyle", to: :list_style
+            map "orgUpcase", to: :org_upcase
+            map "creatorFallback", to: :creator_fallback
+            map "loneEditorMarked", to: :lone_editor_marked
+            map "initialsPeriod", to: :initials_period
+            map "surnameUpcase", to: :surname_upcase
+            map "initialsSeparator", to: :initials_separator
+            map "subsequentInitials", to: :subsequent_initials
+            map "subsequentSurnameUpcase", to: :subsequent_surname_upcase
+            map "etalCount", to: :etal_count
+            map "etalDisplay", to: :etal_display
+            map "inTextEtalCount", to: :in_text_etal_count
+            map "inTextEtalDisplay", to: :in_text_etal_display
+            map "editorsMarked", to: :editors_marked
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# 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 }
+          attribute :home_docid_type, :string, collection: true
+          attribute :default_kind, :string, default: ""
+
+          # The renderings' short cite takes the reference form with the
+      # first-biblio marker (the 1.x citetemplate short), not the
+      # citation template
+      attribute :short_from_reference, :boolean, default: -> { false }
+
+      key_value do
+            map "system", to: :system
+            map "nameForm", to: :name_form
+            map "locale", to: :locale
+            map "homeDocidType", to: :home_docid_type
+            map "defaultKind", to: :default_kind
+            map "shortFromReference", to: :short_from_reference
+          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,40 @@
+# 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}}"
+          attribute :series, :string, default: ""
+          attribute :uri, :string, default: ""
+          attribute :creators, :string, default: ""
+          attribute :uri_short, :string, default: ""
+          # "first": cite only the first identifier (1.x
+          # authoritative_identifier|first styles)
+          attribute :identifier_mode, :string, default: "all"
+
+          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
+          map "series", to: :series
+          map "uri", to: :uri
+          map "creators", to: :creators
+          map "uriShort", to: :uri_short
+          map "identifierMode", to: :identifier_mode
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# 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
+          attribute :series, :string
+          attribute :title, :string
+          attribute :home, :boolean
+          attribute :fallbacks, :hash, default: -> { {} }
+          # The short-cite template for this kind; absent falls back to
+          # the reference template in short mode
+          attribute :short, :string
+          # Render the style's no_place label when the publisher has no
+          # place (the book-family templates of some flavors)
+          attribute :no_place, :boolean
+
+          key_value do
+            map "type", to: :type
+            map "template", to: :template
+            map "series", to: :series
+            map "title", to: :title
+            map "home", to: :home
+            map "fallbacks", to: :fallbacks
+            map "short", to: :short
+            map "noPlace", to: :no_place
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,222 @@
+# 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
+        # The citation-style family the pack belongs to (iso690 | lncs |
+        # chicago | ieee-sa | apa): selects the presentation-of-models
+        # conventions the templates address
+        attribute :family, :string, default: "iso690"
+        # A named pack this one deltas over; resolved at load with the
+        # documented merge semantics (#merge_delta)
+        attribute :extends, :string
+        # Engine capabilities the pack addresses; a resolver that lacks
+        # one fails loudly instead of mis-rendering
+        attribute :requires, :string, collection: true, default: []
+        # Pack-declared taxonomy: wire type -> kind (aliasing or
+        # fallthrough), consulted before the engine's Kinds table
+        attribute :types, :hash, default: -> { {} }
+        # Presentation-of-models selections: slot -> named engine rule
+        attribute :rules, :hash, default: -> { {} }
+        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 "family", to: :family
+          map "extends", to: :extends
+          map "requires", to: :requires
+          map "types", to: :types
+          map "rules", to: :rules
+          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
+
+        # The ISO 690 kind of an item: the vocabulary's mapping, or
+        # the style's declared kind for types the vocabulary does not
+        # map (a flavor whose untyped items are not reports)
+        def kind_for(type)
+          declared_type = types[type.to_s]
+          unless declared_type.to_s.empty?
+            return Kinds.mapped?(declared_type) ? Kinds.kind_for(declared_type) :
+              declared_type
+          end
+
+          return Kinds.kind_for(type) if Kinds.mapped?(type)
+
+          declared = scheme.default_kind.to_s
+          declared.empty? ? Kinds.kind_for(type) : declared
+        end
+
+        # Per-type template selection is a data lookup; unmatched types
+        # fall back to the general reference template. When a kind has
+        # home-flagged variants, the split is resolved by whether the item
+        # carries the scheme's home document identifier.
+        def template_for(type, home: nil)
+          candidates = per_type.select { |t| t.type == type.to_s }
+          if candidates.size > 1 && !home.nil?
+            candidates = candidates.select { |t| (t.home || false) == home }
+          end
+          candidates.first&.template || templates.reference
+        end
+
+        def type_template_for(type)
+          per_type.find { |t| t.type == type.to_s }
+        end
+
+        # The home split applies to the short cite as it does to the
+        # reference template (a home standard's short cite is not an
+        # external standard's)
+        def short_template_for(type, home: nil)
+          candidates = per_type.select { |t| t.type == type.to_s }
+          if candidates.size > 1 && !home.nil?
+            candidates = candidates.select { |t| (t.home || false) == home }
+          end
+          candidates.filter_map(&:short).first
+        end
+
+        # The absent-slot replacement text declared for a type, when any
+        def fallback_for(type, slot)
+          type_template_for(type)&.fallbacks&.[](slot.to_s)
+        end
+
+        def title_form_for(type)
+          per_type.lazy.select { |t| t.type == type.to_s }
+            .find { |t| t.title && !t.title.empty? }&.title
+        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:)
+          shown = scheme.name_form.surname_upcase ? surname.upcase : surname
+          Template.new(templates.name).evaluate(
+            "surname" => Template::Field[!shown.empty?, shown],
+            "givennames" => Template::Field[!given.empty?, given],
+          )
+        end
+
+        # The documented delta merge: perType entries merge per type
+        # key (a delta re-declaring `article` never drops the base's
+        # `monograph`); hash sections merge per key; scalars, templates
+        # and rule selections replace; sortKey and requires union.
+        # Deterministic and engine-portable.
+        def merge_delta(base)
+          merged_per_type = base.per_type.dup
+          per_type.each do |delta|
+            index = merged_per_type.find_index do |b|
+              b.type == delta.type && (b.home || false) == (delta.home || false)
+            end
+            index ? merged_per_type[index] = delta : merged_per_type << delta
+          end
+          self.per_type = merged_per_type
+          self.types = base.types.merge(types)
+          self.rules = base.rules.merge(rules)
+          merge_scheme(base)
+          merge_templates(base)
+          self.sort_key = (base.sort_key + sort_key).uniq
+          self.requires = (base.requires + requires).uniq
+          self
+        end
+
+        private
+
+        def merge_scheme(base)
+          fresh = NameForm.new
+          NameForm.attributes.each_key do |attr|
+            val = scheme.name_form.send(attr)
+            next unless val == fresh.send(attr)
+
+            base_val = base.scheme.name_form.send(attr)
+            scheme.name_form.send("#{attr}=", base_val) if
+              base_val != fresh.send(attr)
+          end
+
+          scheme.system = base.scheme.system if scheme.system.to_s.empty?
+          scheme.short_from_reference = base.scheme.short_from_reference unless
+            scheme.short_from_reference
+          scheme.home_docid_type = base.scheme.home_docid_type if
+            Array(scheme.home_docid_type).empty?
+          scheme.default_kind = base.scheme.default_kind if
+            scheme.default_kind.to_s.empty?
+
+          locale = scheme.locale
+          base_locale = base.scheme.locale
+          locale.conj ||= base_locale.conj
+          locale.others ||= base_locale.others
+          locale.no_date ||= base_locale.no_date
+          locale.no_author ||= base_locale.no_author
+          locale.in_str ||= base_locale.in_str
+          locale.at ||= base_locale.at
+          locale.available_at ||= base_locale.available_at
+          locale.labels.merge!(base_locale.label_map) { |_k, _b, d| d }
+          locale.punct = (base_locale.punct || {}).merge(locale.punct || {})
+        end
+
+        def merge_templates(base)
+          fresh = TemplateMap.new
+          TemplateMap.attributes.each_key do |attr|
+            val = templates.send(attr)
+            base_val = base.templates.send(attr)
+            next unless val == fresh.send(attr) && base_val != fresh.send(attr)
+
+            templates.send("#{attr}=", base_val)
+          end
+        end
+
+        class << self
+          def load(name_or_path, seen = [])
+            path = style_path(name_or_path) or
+              raise ArgumentError, "unknown style #{name_or_path}"
+            style = from_yaml(File.read(path))
+            return style if style.extends.to_s.empty?
+
+            style.extends.split(/\s+/).each do |base_name|
+              raise ArgumentError,
+                    "circular extends #{base_name}" if seen.include?(base_name)
+
+              style.merge_delta(load(base_name, seen + [base_name]))
+            end
+            style
+          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