marc_xml_extractor.rb

require 'csv'

module DS
  module Extractor
    module MarcXmlExtractor
      module ClassMethods

        ############################################################
        # NAMES
        ############################################################

        ##
        # Extract names from record using tags and relators. Tags understood are +100+,
        # +700+, and +710+. The +relators+ are used to require datafields based on the
        # contents of a subfield code +e+ containing the specified value, like 'scribe':
        #
        #     contains(./subfield[@code ='e'], 'scribe')
        #
        # @see #build_name_query for details on query construction
        #
        # @param [Nokogiri::XML:Node] record a +<marc:record>+ node
        # @param [Array<String>] tags the MARC field tag[s]
        # @param [Array<String>] relators for +700$e+, +710$e+, a value[s] like 'former owner'
        # @return [String] pipe-separated list of names
        def extract_names_as_recorded record, tags: [], relators: []
          xpath = build_name_query tags: tags, relators: relators
          return '' if xpath.empty? # don't process nonsensical requests
          record.xpath(xpath).map { |datafield| DS::Util.clean_string extract_name_portion datafield }
        end

        ##
        # Extract names from record using tags and relators. Authors are extracted
        # from datafields 100, 110, 111, 700, 701, and 711.
        #
        # All 1xx are extracted, no relator is assumed and all 1xx are assumed to
        # be authors.
        #
        # 700, 710, and 711 are extracted when subfield 7xx$e contains 'author'.
        #
        # @see #build_name_query for details on query construction
        #
        # @param [Nokogiri::XML:Node] record a +<marc:record>+ node
        # @return [Array<String>] list of names
        def extract_authors_as_recorded record
          authors = []
          authors += extract_names_as_recorded record, tags: [100, 110, 111]
          authors += extract_names_as_recorded record, tags: [700, 710, 711], relators: %w{author}
          authors
        end

        # Extract the alternate graphical representation of the name or return +[]+.
        #
        # See MARC specification for 880 fields:
        #
        # * https://www.loc.gov/marc/bibliographic/bd880.html
        #
        # @param [Nokogiri::XML:Node] record a +<marc:record>+ node
        # @return [Array<String>] list of names or +[]+
        def extract_authors_as_recorded_agr record
          authors = []
          authors += extract_names_as_recorded_agr record, tags: [100, 110, 111]
          authors += extract_names_as_recorded_agr record, tags: [700, 710, 711], relators: %w{author}
          authors
        end

        # Extract scribes from the given record.
        #
        # @param record [Nokogiri::XML:Node] the record to extract scribes from
        # @return [Array<DS::Extractor::Name>] the extracted scribes
        def extract_scribes record
          extract_names(
            record, tags: [700, 710, 711], relators: ['scribe']
          )
        end

        # Extract scribes as recorded from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract scribes from
        # @return [Array<String>] the extracted scribes as recorded
        def extract_scribes_as_recorded record
          extract_scribes(record).map &:as_recorded
        end

        # Extract scribes as recorded with vernacular form from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract scribes from
        # @return [Array<String>] the extracted scribes as recorded
        def extract_scribes_as_recorded_agr record
          extract_scribes(record).map &:vernacular
        end

        # Extracts artists from the given record using the specified type and role.
        #
        # @param [Nokogiri::XML:Node] record the record to extract artists from
        # @return [Array<DS::Extractor::Name>] an array of extracted artists
        def extract_artists record
          extract_names(
            record, tags: [700, 710, 711],
            relators:     ['artist', 'illuminator']
          )
        end

        # Extracts artists as recorded from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract artists from
        # @return [Array<String>] the extracted artists as recorded
        def extract_artists_as_recorded record
          extract_artists(record).map &:as_recorded
        end

        # Extracts artists as recorded with vernacular form from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract artists from
        # @return [Array<String>] the extracted artists as recorded with vernacular form
        def extract_artists_as_recorded_agr record
          extract_artists(record).map &:vernacular
        end

        # Extract former owners from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract former owners from
        # @return [Array<DS::Extractor::Name>] the extracted former owners
        def extract_former_owners record
          extract_names(
            record, tags: [700, 710, 711], relators: ['former owner']
          )
        end

        # Extracts former owners as recorded from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract former owners from
        # @return [Array<String>] the extracted former owners as recorded
        def extract_former_owners_as_recorded record
          extract_former_owners(record).map &:as_recorded
        end

        # Extracts former owners as recorded with vernacular form from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract former owners from
        # @return [Array<String>] the extracted former owners as recorded with vernacular form
        def extract_former_owners_as_recorded_agr record
          extract_former_owners(record).map &:vernacular
        end

        # Extracts scribes as recorded with vernacular form from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract scribes from
        # @return [Array<String>] the extracted scribes as recorded with vernacular form
        def extract_scribes_as_recorded_agr record
          extract_scribes(record).map &:vernacular
        end

        # Extracts artists from the given record using the specified type and role.
        #
        # @param [Nokogiri::XML:Node] record the record to extract artists from
        # @return [Array<DS::Extractor::Name>] an array of extracted artists
        def extract_artists record
          extract_names(
            record, tags: [700, 710, 711],
            relators:     ['artist', 'illuminator']
          )
        end

        # Extracts authors from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract authors from
        # @return [Array<String>] an array of extracted authors
        def extract_authors record
          extract_names(record, tags: [100, 110, 111]) +
            extract_names(record, tags: [700, 710, 711], relators: %w{author})
        end

        def extract_associated_agents record
          []
        end

        ##
        # For the given record, extract the names as an array of arrays, including
        # the concatenated name string (subfields, a, b, c, d) and, if present,
        # the alternate graphical representation (AGR) and authority number (or
        # URI).
        #
        # Each returned sub array will have three values: name, name AGR, URI.
        #
        # @param [Nokogiri::XML:Node] record a +<marc:record>+ node
        # @param [Array<String>] tags the MARC field tag[s]
        # @param [Array<String>] relators for +700$e+, +710$e+, a value[s] like 'former owner'
        # @return [Array<Array<String>>]
        def extract_recon_names record, tags: [], relators: []
          extract_names(record, tags: tags, relators: relators).map &:to_a
        end

        # Extract names from the MARC XML record based on specified tags and relators.
        #
        # @param [Nokogiri::XML:Node] record the record to extract names from
        # @param [Array<String>] tags the MARC field tag[s]
        # @param [Array<String>] relators for +700$e+, +710$e+, values like 'former owner'
        # @return [Array<DS::Extractor::Name>] an array of extracted names
        def extract_names record, tags: [], relators: []
          xpath = build_name_query tags: tags, relators: relators
          return [] if xpath.empty? # don't process nonsensical requests

          record.xpath(xpath).map { |datafield|

            as_recorded = extract_name_portion datafield
            role        = extract_role datafield, relators: relators
            role        = 'author' if role.blank?
            vernacular  = extract_pn_agr datafield
            ref         = extract_authority_number datafield

            DS::Extractor::Name.new(
              as_recorded: as_recorded, role: role,
              vernacular:  vernacular, ref: ref
            )
          }
        end

        ##
        # Extract the alternate graphical representation of the name or return +''+.
        #
        # See MARC specification for 880 fields:
        #
        # * https://www.loc.gov/marc/bibliographic/bd880.html
        #
        # @see #build_name_query for details on query construction
        #
        # @param [Nokogiri::XML:Node] record a +<marc:record>+ node
        # @param [Array<String>] tags the MARC field code[s]
        # @param [Array<String>] relators for +700$e+, +710$e+, a value[s] like 'former owner'
        def extract_names_as_recorded_agr record, tags: [], relators: []
          xpath = build_name_query tags: tags, relators: relators
          return '' if xpath.empty? # don't process nonsensical requests

          record.xpath(xpath).map { |datafield|
            extract_pn_agr datafield
          }
        end

        ##
        # Build names query tags and relators. Tags understood are +100+, +700+,
        # and +710+. The +relators+ are used to require datafields based on the contents
        # of a subfield code +e+ containing the specified value, like 'scribe':
        #
        #     contains(./subfield[@code ='e'], 'scribe')
        #
        # For relators see section <strong>$e - Relator term<strong>, here:
        #
        #   https://www.loc.gov/marc/bibliographic/bdx00.html
        #
        # To require the subfield not have a relator, pass +:none+ as the relator value.
        #
        #     build_name_query tags: ['100'], relators: :none
        #
        # This will add the following to the query.
        #
        #     not(./subfield[@code = 'e'])
        #
        # Note: In U. Penn manuscript catalog records, 700 and 710 fields that *do*
        # *not* have a subfield code +e+ are associated authors.
        #
        # @param [Array<String>] tags the MARC field code[s]
        # @param [Array<String>] relators for +700$e+, +710$e+, a value[s] like 'former owner'
        # @return [String] the data field query string
        def build_name_query tags: [], relators: []
          return '' if tags.empty? # don't process nonsensical requests
          # make sure the tags are all strings
          _tags        = [tags].flatten.map &:to_s
          tag_query    = _tags.map { |t| "@tag = #{t}" }.join " or "
          query_string = "(#{tag_query})"

          _relators = [relators].flatten.map { |r| r.to_s.strip.downcase == 'none' ? :none : r }
          return "datafield[#{query_string}]" if _relators.empty?

          if _relators.include? :none
            query_string += " and not(./subfield[@code = 'e'])"
            return "datafield[#{query_string}]"
          end

          relator_string = relators.map { |r| "contains(./subfield[@code ='e'], '#{r}')" }.join " or "
          query_string   += (relator_string.empty? ? '' : " and (#{relator_string})")
          "datafield[#{query_string}]"
        end

        ###
        # Extract the the PN from datafield, pulling subfields $a, $b, $c, $d.
        #
        # @param [Nokogiri::XML::Node] datafield the +marc:datafield+ node with the name
        # @return [String]
        def extract_name_portion datafield
          codes = %w{ a b c d }
          value = collect_subfields datafield, codes: codes
          DS::Util.clean_string value, terminator: ''
        end

        ###
        # Extract the role value, subfield +$e+, from the given datafield.
        #
        # @param [Nokogiri::XML::Node] datafield the +marc:datafield+ node with the name
        # @return [String]
        def extract_role datafield, relators:
          relators_list = *relators
          return '' if relators_list.empty? or relators_list.include? :none
          # if there's no $e, stop processing
          return '' if datafield.xpath('subfield[@code = "e"]/text()').text.empty?

          df_roles    = datafield.xpath('subfield[@code = "e"]/text()').map(&:text)
          rel_pattern = /(#{relators_list.join('|')})/
          role        = df_roles.find { |role| role =~ rel_pattern }
          DS::Util.clean_string role, terminator: ''
        end

        #########################################################################
        # Miscellaneous authority values
        #########################################################################

        ###
        # Extract the language codes from controlfield 008 and datafield 041$a.
        #
        # @param [Nokogiri::XML::Node] record the marc:record node
        # @return [String]
        def extract_langs record
          # Language is in 008 at characters 35-37 (0-based indexing)
          (langs ||= []) << record.xpath("substring(controlfield[@tag='008']/text(), 36, 3)")
          # 041 is present if there's more than one language
          langs += record.xpath("datafield[@tag=041]/subfield[@code='a']").map(&:text)
          # if there are 041 values, the lang from 008 is repeated; remove the duplicate
          langs.select(&:present?).uniq
        end

        ##
        # Extract the language as record; default to the 546$a field; otheriwse
        # return the code values from controlfield 008 and 041$a.
        #
        # @param [Nokogiri::XML::Node] record the marc:record node
        # @return [String]
        def extract_languages_as_recorded record
          extract_languages(record).map &:as_recorded
        end

        def extract_languages record
          xpath = "datafield[@tag=546]/subfield[@code='a']"
          langs = record.xpath(xpath).map { |val|
            DS::Util.clean_string val.text, terminator: ''
          }.select(&:present?).map { |as_recorded|
            DS::Extractor::Language.new as_recorded: as_recorded
          }
          return langs if langs.present?

          extract_langs(record).map { |as_recorded|
            DS::Extractor::Language.new as_recorded: as_recorded
          }
        end

        #########################################################################
        # Genres and subjects
        #########################################################################
        ##
        # Extract genre and form terms from MARC datafield 655 values, where the
        # 655$2 value can be specified; e.g., +rbprov+, +aat+, +lcgft+.
        #
        # Set +sub2+ to +:all+ to extract all 655 terms
        #
        # @param [Nokogiri::XML::Node] record the MARC record
        # @param [Boolean] uniq whether to return only unique terms; default: +true+
        # @return [Array<String>] array of genre terms
        def extract_genres_as_recorded record, uniq: true
          terms = extract_genres(record, sub_sep: '--', vocab: :all).map(&:as_recorded)

          uniq ? terms.uniq : terms
        end

        ##
        # Return an array of strings of formatted subjects (600, 610, 611, 630,
        # 647, 648, 650, and 651). Subjects values are separated by '--':
        #
        #     <datafield ind1="1" ind2="0" tag="600">
        #       <subfield code="a">Cicero, Marcus Tullius</subfield>
        #       <subfield code="x">Spurious and doubtful works.</subfield>
        #     </datafield>
        #
        #     # => "Cicero, Marcus Tullius--Spurious and doubtful works"
        #
        # Subfields with codes 'b', 'c', 'd', 'p', 'q', and 't' are appended to
        # the preceding subfield:
        #
        #    <datafield ind1=" " ind2="7" tag="647">
        #      <subfield code="a">Conspiracy of Catiline</subfield>
        #      <subfield code="c">(Rome :</subfield>
        #      <subfield code="d">65-62 B.C.)</subfield>
        #      <subfield code="2">fast</subfield>
        #      <subfield code="0">(OCoLC)fst01352536</subfield>
        #    </datafield>
        #
        #    # => "Conspiracy of Catiline (Rome : 65-62 B.C.)"
        #
        #  @param [Nokogiri::XML::Node] record the MARC record
        # @return [Array<DS::Extractor::Subject>] an array of formatted subjects strings
        def extract_subject_by_tags record, tags: []
          tag_list = *tags
          raise "No tags given for subject extraction: #{tags.inspect}" if tag_list.empty?
          sep       = '--'
          tag_query = tag_list.map { |tag| "@tag=#{tag}" }.join " or "
          record.xpath("datafield[#{tag_query}]").map { |datafield|
            values = Hash.new { |hash, k| hash[k] = [] }
            vocab  = datafield.xpath('./@ind2').text
            datafield.xpath("subfield").map { |subfield|
              subfield_text = DS::Util.clean_string subfield.text
              subfield_code = subfield.xpath('./@code').text
              case subfield_code
              when 'e', 'w'
                # don't include these formatted in subject
              when 'b', 'c', 'd', 'p', 'q', 't'
                # append these to the preceding value
                # we assume that there is a preceding value
                values[:terms][-1] += " #{subfield_text}"
                values[:codes][-1] += ";#{subfield_code}"
              when %r{\A[[:alpha:]]\z}
                # any other codes: a, g, v, x, y, z
                values[:terms] << subfield_text
                values[:codes] << subfield_code
              when '2'
                vocab = subfield.text
              when '0'
                values[:urls] << subfield_text
              end
            }
            terms = DS::Util.clean_string values[:terms].join(sep), terminator: ''
            urls  = DS::Util.clean_string values[:urls].join(sep), terminator: ''
            codes = DS::Util.clean_string values[:codes].join(sep), terminator: ''
            DS::Extractor::Subject.new(
              as_recorded:          terms,
              subfield_codes:       codes,
              source_authority_uri: urls,
              vocab:                vocab
            )
          }

        end

        # Extracts named subjects as recorded from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract named subjects from
        # @return [Array<String>] the extracted named subjects as recorded
        def extract_named_subjects_as_recorded record
          extract_named_subjects(record).map &:as_recorded
        end


        # Extract named subjects from the MARC XML record based on specified tags.
        #
        # @param [Nokogiri::XML:Node] record the record to extract named subjects from
        # @return [Array<DS::Extractor::Subject>] an array of extracted named subjects
        def extract_named_subjects record
          extract_subject_by_tags record, tags: [600, 610, 611, 630, 647]
        end

        # Extracts subjects as recorded from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract subjects from
        # @return [Array<String>] the extracted subjects as recorded
        def extract_subjects_as_recorded record
          extract_subjects(record).map &:as_recorded
        end

        # Extracts subjects from the given record based on specified tags.
        #
        # @param [Nokogiri::XML:Node] record the record to extract subjects from
        # @return [Array<DS::Extractor::Subject>] an array of extracted subjects
        def extract_subjects record
          extract_subject_by_tags record, tags: [648, 650, 651]
        end

        # Extracts all subjects from the given record, including named subjects and subjects.
        #
        # @param [Nokogiri::XML:Node] record the record to extract all subjects from
        # @return [Array<DS::Extractor::Subject>] the extracted all subjects
        def extract_all_subjects record
          extract_named_subjects(record) + extract_subjects(record)
        end

        # Extracts all subjects as recorded from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract all subjects from
        # @return [Array<String>] the extracted all subjects as recorded
        def extract_all_subjects_as_recorded record
          extract_all_subjects(record).map &:as_recorded
        end


        ##
        # Extract genre terms for reconciliation CSV output.
        #
        # Returns a two-dimensional array, each row is a place; and each row has
        # three columns: term, vocab, and authority number.
        #
        # @param [Nokogiri::XML:Node] record a +<MARC_RECORD>+ node
        # @return [Array<Array>] an array of arrays of values
        def extract_recon_genres record, sub_sep: '--'
          extract_genres(record, sub_sep: sub_sep).map(&:to_a)
        end

        # Extracts genres from the given MARC XML record.
        #
        # @param [Nokogiri::XML:Node] record the MARC XML record to extract genres from
        # @param [String] sub_sep (default: '--') the separator for joining subfields
        # @param [Symbol, String] vocab (default: :all) the vocab type to extract
        # @return [Array<DS::Extractor::Genre>] an array of extracted genres
        def extract_genres record, sub_sep: '--', vocab: :all
          xpath = %q{datafield[@tag = 655]}
          record.xpath(xpath).filter_map { |datafield|
            as_recorded          = collect_subfields datafield, codes: 'abcvzyx'.split(//), sub_sep: sub_sep
            as_recorded          = DS::Util.clean_string as_recorded, terminator: ''
            term_vocab           = extract_vocabulary datafield
            source_authority_uri = extract_authority_number datafield

            next unless as_recorded.present?
            next unless vocab == :all || vocab == term_vocab

            DS::Extractor::Genre.new(
              as_recorded: as_recorded, vocab: term_vocab,
              source_authority_uri: source_authority_uri
            )
          }
        end

        # Extracts the genre vocabulary from the given MARC XML record.
        #
        # @param [Nokogiri::XML::Node] record the MARC XML record to extract genre vocabulary from
        # @return [Array<Symbol>] an array of extracted genre vocabularies
        def extract_genre_vocabulary record
          extract_genres(record).map(&:vocab)
        end

        # Extracts reconstructed subjects from the given record.
        #
        # @param [Nokogiri::XML::Node] record the record to extract reconstructed subjects from
        # @return [Array] the extracted reconstructed subjects
        def extract_recon_subjects record
          extract_all_subjects(record).map &:to_a
        end

        #########################################################################
        # Place of production
        #########################################################################

        ##
        # Look for a place as recorded. Look first at 264$a, then 260$a; return ''
        # when no value is found
        # @param [Nokogiri::XML::Node] record the MARC record
        # @return [Array<String>] the place name or []
        def extract_production_places_as_recorded record
          xpath = "datafield[@tag=260 or @tag=264]/subfield[@code='a']/text()"
          record.xpath(xpath).map { |pn|
            DS::Util.clean_string pn.text, terminator: '' unless pn.to_s.strip.empty?
          }
        end

        ##
        # Extract the places of production MARC +260$a+ for reconciliation CSV
        # output.
        #
        # Returns a two-dimensional array, each row is a place; and each row has
        # one column: place name; for example:
        #
        #     [["Austria"],
        #      ["Germany"],
        #      ["France (?)"]]
        #
        # @param [Nokogiri::XML:Node] record a +<marc:record>+ node
        # @return [Array<Array>] an array of arrays of values
        def extract_recon_places record
          extract_places(record).map &:to_a
        end

        def extract_places record
          xpath = "datafield[@tag=260 or @tag=264]/subfield[@code='a']/text()"
          record.xpath(xpath).map { |pn|
            next if pn.to_s.blank?
            as_recorded = DS::Util.clean_string(pn.text, terminator: '')
            DS::Extractor::Place.new as_recorded: as_recorded
          }
        end

        #########################################################################
        # Date of production
        #########################################################################

        ###
        # Extract the encoded date from controlfield 008.
        #
        # Follows
        #
        # - https://www.loc.gov/marc/bibliographic/bd046.html
        # - https://www.loc.gov/marc/bibliographic/bd046.html
        #
        # Returns an array containing a pair of dates or a single date,
        # or an empty array.
        #
        # The following date types have appeared in MARC records
        # contributed to DS as of 2024-02-27 and are handled here:
        #
        # b - No dates given; B.C. date involved
        #   - 'b        '
        #   - date is taken from 046$b, and if present $d or $e
        #   - See: https://www.loc.gov/marc/bibliographic/bd046.html
        #
        #
        # e - Detailed date
        #   - 'e11200520', 'e139403 x', 'e164509 t', 'e167707 y',
        #     'e187505 s'
        #   - the first date part is returned a single year
        #
        # i - Inclusive dates of collection
        #   - 'i07500800', 'i08000830', 'i1000    '
        #   - the first and -- if present -- second date part are
        #     returned as two years
        #
        # k - Range of years of bulk of collection
        #   - 'k15121716'
        #   - the first and second date parts are returned as two years
        #
        # m - Multiple dates
        #   - 'm0618193u', 'm07390741', 'm10751200', 'm16uu1637',
        #     'm17uu1900'
        #   - the first and second date parts are returned as two years
        #   - see note below on replacement of u's
        #
        # n - Dates unknown
        #   - 'nuuuuuuuu'
        #   - no date returned
        #
        # p - Date of distribution/release/issue and
        #     production/recording session when different
        #   - 'p1400    '
        #   - the first and -- if present -- second date part are
        #     returned as two years
        #
        # q - Questionable date
        # q - 'q01000299', 'q0979    ', 'q09910992', 'q10001099',
        #     'q1300    ', 'q13uu14uu', 'q13uu1693', 'q14011425',
        #     'q1425uuuu', 'q1450    ', 'q1460    ', 'q14uu14uu',
        #     'quuuu1597'
        #   - the first and -- if present -- second date part are
        #     returned as two years
        #   - if the second date part is 'uuuu', the first date part is
        #     returned as year; ; ‘q1425uuuu’ => 1425
        #   - if the first date part is 'uuuu', the second date part is
        #     returned as year; ‘quuuu1597’ => 1597
        #   - for partial date parts with u's, see the note below
        #
        # r - Reprint/reissue date and original date
        #   - 'r11751199'
        #   - the first date part is returned a single year
        #
        # s - Single known date/probable date
        # s - 's1171    ', 's1171 xx ', 's1192 ua ', 's1250||||',
        #     's1286 iq ', 's1315 sy ', 's1366 is ', 's1436 gw ',
        #     's1450 it ', 's1470 ly ', 's1470 tu ', 's1470 uuu',
        #     's1497 enk', 's1595 sp ', 's19uu    '
        #   - the first date part is returned a single year
        #   - see note below on replacement of u's
        #
        # | - No attempt to code
        #   - '|12501300'
        #   - this appears to be miscoding
        #   - nevertheless, '|' coded records will follow the default
        #     rule: date part one is returned a single year
        #
        # The following cases, so far unrepresented in contributor data,
        # will follow the default rule: date part one will be returned
        # as a single year.
        #
        # c - Continuing resource currently published
        # d - Continuing resource ceased publication
        # t - Publication date and copyright date
        # u - Continuing resource status unknown
        #
        # Note on the replacement of u's in partial year dates
        #
        #  - Where u's appear in the first date they are replace by 0;
        #    thus, 'q13uu1693'  => '1300, 1693'
        #  - Where u's appear in the second date they are replace by 9;
        #    thus, 'q14uu14uu'  => '1400, 1499'
        #
        # For MARC partial dates see Date 1 and Date 2 documentation
        # here
        #
        #  https://www.loc.gov/marc/bibliographic/bd008a.html
        #
        # @param [Nokogiri::XML::Node] record the +marc:record+ node
        # @return [Array]
        def extract_date_range record, range_sep:
          # 008 controlfield; e.g.,
          #
          #     "220518q14001500xx            000 0     d"
          ctrl_008 = record.at_xpath("controlfield[@tag='008']")
          return [] unless ctrl_008 # return if no 008
          # get positions 7-15: q14001500
          date_str = ctrl_008.text[6, 9]
          code     = date_str[0] # 'm'
          part1    = extract_date_part date_str, 1, 4 # '0618'
          part1.gsub! /u/, '0' if part1.present?
          part2 = extract_date_part date_str, 5, 8 # '193u'
          part2.gsub! /u/, '9' if part2.present?

          range = compile_dates(record, code, part1, part2).filter_map { |y|
            # filter out blank dates and '9999'
            y if y.present? && y != '9999'
          }

          return [] if range.blank?
          [range.join(range_sep)]
        end

        # Compiles dates based on the provided code and parts. This
        # methods determines the date based on the date code from the
        # MARC 008 field; the code in position 6 of the MARC 008 field.
        #
        # See https://www.loc.gov/marc/bibliographic/bd008.html
        #
        # @param [Nokogiri::XML::Node] record the +marc:record+ node
        # @param [String] code the marc 008 date code
        def compile_dates record, code, part1, part2
          case code
          when 'i', 'k', 'm', 'p', 'q', '|'
            [part1, part2]
          when 'n'
            []
          when 'b'
            handle_bce_date record
          else
            [part1]
          end
        end

        # Compiles BCE dates based on the provided record. It extracts
        # BCE dates from specific subfields in the MARC XML record.
        #
        # The method stops and returns an empty array +[]+ if the
        # record lacks a 240$b (BCE date 1). It then looks for a 245$d
        # (BCE date 2) or 245$e (CE date 2). An array containing the
        # single 240$b value as a negative value or a range of two
        # dates.
        #
        # See: https://www.loc.gov/marc/bibliographic/bd046.html
        #
        # @param [Nokogiri::XML::Node] record the MARC XML record
        # @return [Array<String>] an array of BCE dates in string format
        def handle_bce_date record
          # "datafield[@tag=260]/subfield[@code='c' or @code='d']/text()")
          bce_date1 = record.at_xpath('datafield[@tag=046]/subfield[@code="b"]/text()').to_s
          # stop if there's no BCE date 1
          return [] if bce_date1.blank?

          xpath     = 'datafield[@tag=046]/subfield[@code="d"]/text()'
          bce_date2 = record.at_xpath(xpath).to_s

          return ["-#{bce_date1}", "-#{bce_date2}"] if bce_date2.present?

          xpath    = 'datafield[@tag=046]/subfield[@code="e"]/text()'
          ce_date2 = bce_date2 = record.at_xpath(xpath).to_s
          return ["-#{bce_date1}", ce_date2] if ce_date2.present?

          ["-#{bce_date1}"]
        end

        # Extracts a part of the date string from a MARC 008
        # controlfield, using the indices ndx1 and ndx2.
        #
        # Ensures that the extracted part starts with a digit and
        # matches a sequence of digits and/or 'u'.
        #
        # @param [String] datestring the input datestring
        # @param [Integer] ndx1 the starting index for extraction
        # @param [Integer] ndx2 the length of the substring to extract
        # @return [String] the extracted part of the datestring
        def extract_date_part datestring, ndx1, ndx2
          part = datestring[ndx1, ndx2]

          # part must start with a digit and match a seq of digits and/or u
          return unless part =~ /^\d[\du]+/

          part.sub! /^0+/, '' if part =~ /^0+[1-9]/
          part
        end

        ##
        # Look for a date as recorded. Look first at 260$c, then 260$d, then
        # 245$f, finally use the encoded date from 008
        def extract_production_date_as_recorded record
          # Note that MARC does not specify a subfield '260$d':
          #
          # https://www.loc.gov/marc/bibliographic/bd260.html
          #
          # However Cornell use $d to continue 260$c
          dar = record.xpath("datafield[@tag=260]/subfield[@code='c' or @code='d']/text()").map do |t|
            DS::Util.clean_string t.text.strip
          end.join ' '
          return [dar.strip] unless dar.strip.empty?

          dar = record.xpath("datafield[@tag=264]/subfield[@code='c']/text()").map do |t|
            DS::Util.clean_string t.text.strip
          end.join ' '
          return [dar.strip] unless dar.strip.empty?

          # 245 is the title field but can have a date in $f
          #
          # see: https://www.loc.gov/marc/bibliographic/bd245.html
          #
          # Cornell uses 245$f in records that also lack 260 or 264; see
          # '4600 Bd. Ms. 176':
          #
          # https://catalog.library.cornell.edu/catalog/6382455/librarian_view
          #
          #   <datafield ind1="0" ind2="0" tag="245">
          #     <subfield code="a">Shah-nameh,</subfield>
          #     <subfield code="f">1600s.</subfield>
          #   </datafield>
          #
          dar = record.xpath("datafield[@tag=245]/subfield[@code='f']").text
          return [DS::Util.clean_string(dar)] unless dar.strip.empty?

          encoded_date = extract_date_range record, range_sep: '-'
          [encoded_date.join('_').strip]
        end

        #########################################################################
        # Titles
        #########################################################################

        # Extracts reconstructed titles from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract reconstructed titles from
        # @return [Array<String>] the extracted reconstructed titles
        def extract_recon_titles record
          extract_titles(record).to_a
        end

        # Extracts titles from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract titles from
        # @return [Array<DS::Extractor::Title>] an array of extracted titles
        def extract_titles record
          tar      = title_as_recorded record
          tar_agr  = DS::Util.clean_string DS::Extractor::MarcXmlExtractor.title_as_recorded_agr(record, 245), terminator: ''
          utar     = DS::Util.clean_string DS::Extractor::MarcXmlExtractor.uniform_titles_as_recorded(record), terminator: ''
          utar_agr = DS::Util.clean_string DS::Extractor::MarcXmlExtractor.uniform_title_as_recorded_agr(record), terminator: ''

          [DS::Extractor::Title.new(
            as_recorded:              tar,
            vernacular:               tar_agr,
            uniform_title:            utar,
            uniform_title_vernacular: utar_agr
          )]
        end

        # Extracts titles as recorded with vernacular form from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract titles from
        # @return [Array<String>] the extracted titles as recorded with vernacular form
        def extract_titles_as_recorded_agr record
          extract_titles(record).map &:vernacular
        end

        # Extracts the title as recorded from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract the title from
        # @return [String] the extracted title as recorded
        def title_as_recorded record
          xpath = "datafield[@tag=245]/subfield[@code='a' or @code='b']"
          record.xpath(xpath).map { |title|
            DS::Util.clean_string(title.text, terminator: '')
          }.join '; '
        end

        # Extracts the title as recorded with vernacular form from the given record.
        #
        # @param [Nokogiri::XML::Node] record the record to extract the title from
        # @param [Integer] tag the tag to use for extraction
        # @return [String] the extracted title as recorded with vernacular form
        def title_as_recorded_agr record, tag
          linkage = record.xpath("datafield[@tag=#{tag}]/subfield[@code='6']").text
          return '' if linkage.empty?
          index = linkage.split('-').last
          xpath = "datafield[@tag='880' and contains(./subfield[@code='6'], '#{tag}-#{index}')]/subfield[@code='a']"
          DS::Util.clean_string record.xpath(xpath).text.delete '[]'
        end

        # Extracts titles as recorded from the given record.
        #
        # @param record [Nokogiri::XML:Node] the record to extract titles from
        # @return [Array<String>] the extracted titles as recorded
        def extract_titles_as_recorded record
          extract_titles(record).map &:as_recorded
        end

        # Extracts uniform titles as recorded from the given record.
        #
        # @param [Nokogiri::XML::Node] record the record to extract uniform titles from
        # @return [String] the extracted uniform titles as recorded joined by '|'
        def uniform_titles_as_recorded record
          title_240 = record.xpath("datafield[@tag=240]/subfield[@code='a']").text
          title_130 = record.xpath("datafield[@tag=130]/subfield[@code='a']").text
          [title_240, title_130].reject(&:empty?).map { |title|
            DS::Util.clean_string title, terminator: ''
          }.join '|'
        end

        # Extracts uniform titles as recorded from the given record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract uniform titles from
        # @return [Array<String>] the extracted uniform titles as recorded
        def extract_uniform_titles_as_recorded record
          extract_titles(record).map &:uniform_title
        end


        # Extracts uniform titles as recorded with vernacular form from the given MARC XML record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract uniform titles from
        # @return [Array<String>] the extracted uniform titles as recorded with vernacular form
        def extract_uniform_titles_as_recorded_agr record
          extract_titles(record).map &:uniform_title_vernacular
        end

        # Extracts uniform titles as recorded and aggregates them from the given MARC XML record.
        #
        # @param [Nokogiri::XML::Node] record the MARC XML record to extract uniform titles from
        # @return [String] the aggregated uniform titles as recorded
        def uniform_title_as_recorded_agr record
          tag240 = title_as_recorded_agr record, 240
          tag130 = title_as_recorded_agr record, 130
          [tag240, tag130].reject(&:empty?).map { |title|
            DS::Util.clean_string title
          }.join '|'
        end

        #########################################################################
        # Physical description
        #########################################################################

        # Extracts the physical description from the given MARC XML record.
        #
        # @param [Nokogiri::XML:Node] record the record to extract the physical description from
        # @return [String] the extracted physical description
        def extract_physical_description record
          extract_extent(record)
        end

        # Extracts the material as recorded from the given MARC XML record.
        #
        # @param [Nokogiri::XML::Node] record the MARC XML record to extract material from
        # @return [String] the extracted material as recorded
        def extract_material_as_recorded record
          extract_materials(record).map(&:as_recorded).first.to_s
        end

        # Extracts materials from the given MARC XML record.
        #
        # @param [Nokogiri::XML::Node] record the MARC XML record to extract materials from
        # @return [Array<DS::Extractor::Material>] an array of extracted materials
        def extract_materials record
          DS::Extractor::MarcXmlExtractor.collect_datafields(
            record, tags: 300, codes: 'b'
          ).filter_map { |material|
            next unless material.present?
            DS::Extractor::Material.new as_recorded: material
          }
        end

        # Extracts the extent from the given MARC XML record.
        #
        # @param [Nokogiri::XML::Node] record the MARC XML record to extract extent from
        # @return [Array<String>] an array of extracted extents
        def extract_extent record
          subfield_xpath = "subfield[@code = 'a' or @code = 'b' or @code = 'c']"
          record.xpath("datafield[@tag=300]").map { |datafield|
            datafield.xpath(subfield_xpath).filter_map { |s|
              s.text unless s.text.empty?
            }.join ' '
          }.filter_map { |ext|
            "Extent: #{DS::Util.clean_string ext}" unless ext.strip.empty?
          }
        end

        #########################################################################
        # Notes
        #########################################################################
        ##
        # Extract notes from +record+.
        #
        # Extract values from `500$a` fields that do not begin with AMREMM
        # tags for specific values like 'Binding:'. Specifically, this method
        # ignores fields beginning with:
        #
        #    Pagination|Foliation|Layout|Colophon|Collation|Script|Decoration|\
        #         Binding|Origin|Watermarks|Watermark|Signatures|Shelfmark
        #
        # @param [Nokogiri::XML:Node] record a +<MARC_RECORD>+ node
        # @return [Array<String>] an array of note strings