datacite-mapping 0.1.0

data/lib/datacite/mapping/description.rb

@@ -0,0 +1,121 @@
+require 'xml/mapping_extensions'
+
+module Datacite
+  module Mapping
+
+    # Controlled vocabulary of description types.
+    class DescriptionType < TypesafeEnum::Base
+      # @!parse ABSTRACT = Abstract
+      new :ABSTRACT, 'Abstract'
+
+      # @!parse METHODS = Methods
+      new :METHODS, 'Methods'
+
+      # @!parse SERIES_INFORMATION = SeriesInformation
+      new :SERIES_INFORMATION, 'SeriesInformation'
+
+      # @!parse TABLE_OF_CONTENTS = TableOfContents
+      new :TABLE_OF_CONTENTS, 'TableOfContents'
+
+      # @!parse OTHER = Other
+      new :OTHER, 'Other'
+
+    end
+
+    # XML mapping class preserving `<br/>` tags in description values
+    class BreakPreservingValueNode < XML::Mapping::SingleAttributeNode
+      # Collapses a sequence of text nodes and `<br/>` tags into a single string value.
+      # Implements `SingleAttributeNode#xml_to_obj`.
+      # @param obj [Description] the object being created
+      # @param xml [REXML::Element] the XML being read
+      def xml_to_obj(obj, xml)
+        value_str = xml.children.map { |c| c.respond_to?(:value) ? c.value : c.to_s }.join
+        obj.value = value_str.strip
+      end
+
+      # Converts a string value to a sequence of text nodes and `<br/>` tags.
+      # Implements `SingleAttributeNode#obj_to_xml`.
+      # @param obj [Description] the object being serialized
+      # @param xml [REXML::Element] the XML being written
+      def obj_to_xml(obj, xml)
+        value_str = obj.value || ''
+        values = value_str.split(%r{<br[^/]?/>|<br>[^<]*</br>})
+        values.each_with_index do |v, i|
+          xml.add_text(v)
+          xml.add_element('br') unless i + 1 >= values.size
+        end
+      end
+    end
+    XML::Mapping.add_node_class BreakPreservingValueNode
+
+    # A additional information that does not fit in the other more specific {Resource}
+    # attributes.
+    #
+    # Note: In accordance with the DataCite spec, description text can be separated by
+    # HTML `<br/>` tags. The {Description} class will preserve these, but at the expense
+    # of converting escaped `<br/>` in text values to actual `<br/>` tags. For example,
+    # when reading the following tag:
+    #
+    #     <description xml:lang="en-us" descriptionType="Abstract">
+    #       Line 1<br/>Line 2 containing escaped &lt;br/&gt; tag<br/>Line 3
+    #     </description>
+    #
+    # the value will be returned as the string
+    #
+    #     "Line 1<br/>Line 2 containing escaped <br/> tag<br/>Line 3"
+    #
+    # in which it is impossible to distinguish the escaped an un-escaped `<br/>`s. The
+    # value would thus be written back to XML as:
+    #
+    #     <description xml:lang="en-us" descriptionType="Abstract">
+    #       Line 1<br/>Line 2 containing escaped <br/> tag<br/>Line 3
+    #     </description>
+    #
+    # Other escaped HTML or XML tags will still be escaped when written back, and other
+    # un-escaped HTML and XML tags are of course not allowed.
+    class Description
+      include XML::Mapping
+
+      # @!attribute [rw] language
+      #   @return [String] an IETF BCP 47, ISO 639-1 language code identifying the language.
+      #     It's unclear from the spec whether language is required; to play it safe, if it's missing, we default to 'en'.
+      text_node :language, '@xml:lang', default_value: nil
+
+      # @!attribute [rw] type
+      #   @return [DescriptionType] the description type.
+      typesafe_enum_node :type, '@descriptionType', class: DescriptionType
+
+      # @!attribute [rw] value
+      #   @return [String] the description itself. See {Description} for notes on special
+      #     handling of `<br/>` tags.
+      break_preserving_value_node :value, 'node()'
+
+      alias_method :_language, :language
+      private :_language
+
+      alias_method :_language=, :language=
+      private :_language=
+
+      # Initializes a new {Description}
+      # @param language [String] an IETF BCP 47, ISO 639-1 language code identifying the language.
+      #   It's unclear from the spec whether language is required; to play it safe, if it's missing, we default to 'en'.
+      # @param type [DescriptionType] the description type.
+      # @param value [String] the description itself. See {Description} for notes on special
+      #     handling of `<br/>` tags.
+      def initialize(language: 'en', type:, value:)
+        self.language = language
+        self.type = type
+        self.value = value
+      end
+
+      def language
+        _language || 'en'
+      end
+
+      def language=(value)
+        self._language = value.strip if value
+      end
+
+    end
+  end
+end

data/lib/datacite/mapping/geo_location.rb

@@ -0,0 +1,49 @@
+require 'xml/mapping_extensions'
+require_relative 'geo_location_point'
+require_relative 'geo_location_box'
+
+module Datacite
+  module Mapping
+
+    # A location at which the data was gathered or about which the data is focused, in the
+    # form of a latitude-longitude point, a latitude-longitude quadrangle, and/or a place name.
+    #
+    # *Note:* Due to a quirk of the DataCite spec, it is possible for a {GeoLocation} to be empty, with
+    # none of these present.
+    class GeoLocation
+      include XML::Mapping
+
+      root_element_name 'geoLocation'
+
+      # @!attribute [rw] point
+      #   @return [GeoLocationPoint, nil] the latitude and longitude at which the data was gathered or about which the data is focused.
+      geo_location_point_node :point, 'geoLocationPoint', default_value: nil
+
+      # @!attribute [rw] box
+      #   @return [GeoLocationBox, nil] the latitude-longitude quadrangle containing the area where the data was gathered or about which the data is focused.
+      geo_location_box_node :box, 'geoLocationBox', default_value: nil
+
+      # @!attribute [rw] place
+      #   @return [String, nil] the spatial region or named place where the data was gathered or about which the data is focused.
+      text_node :place, 'geoLocationPlace', default_value: nil
+
+      # Initializes a new {GeoLocation}
+      # @param point [GeoLocationPoint, nil] the latitude and longitude at which the data was gathered or about which the data is focused.
+      # @param box [GeoLocationBox, nil] the latitude-longitude quadrangle containing the area where the data was gathered or about which the data is focused.
+      # @param place [String, nil] the spatial region or named place where the data was gathered or about which the data is focused.
+      def initialize(point: nil, box: nil, place: nil)
+        self.point = point
+        self.box = box
+        self.place = place
+      end
+
+      alias_method :_place=, :place=
+      private :_place=
+
+      def place=(value)
+        self._place = value.respond_to?(:strip) ? value.strip : value
+      end
+
+    end
+  end
+end

data/lib/datacite/mapping/geo_location_box.rb

@@ -0,0 +1,137 @@
+require 'xml/mapping'
+
+module Datacite
+  module Mapping
+    # A latitude-longitude quadrangle containing the area where the data was gathered or about
+    # which the data is focused.
+    #
+    # @!attribute [rw] south_latitude
+    #   @return [Numeric] the latitude of the south edge of the box
+    # @!attribute [rw] west_longitude
+    #   @return [Numeric] the longitude of the west edge of the box
+    # @!attribute [rw] north_latitude
+    #   @return [Numeric] the latitude of the north edge of the box
+    # @!attribute [rw] east_longitude
+    #   @return [Numeric] the longitude of the east edge of the box
+    class GeoLocationBox
+      include Comparable
+
+      attr_reader :south_latitude
+      attr_reader :west_longitude
+      attr_reader :north_latitude
+      attr_reader :east_longitude
+
+      # Initializes a new {GeoLocationBox}. The arguments can be provided
+      # either as a named-parameter hash, or as a list of four coordinates
+      # in the form `lat, long, lat, long` (typically
+      # `south_latitude, west_longitude, north_latitude, east_longitude`
+      # but not necessarily; north/south and east/west will be flipped if
+      # need be). That is, the following forms are equivalent:
+      #
+      #     GeoLocationBox.new(
+      #       south_latitude: -33.45,
+      #       west_longitude: -122.33,
+      #       north_latitude: 47.61,
+      #       east_longitude: -70.67
+      #     )
+      #
+      #     GeoLocationBox.new(-33.45, -122.33, 47.61, -70.67)
+      #
+      # @param south_latitude [Numeric]
+      #   the latitude of the south edge of the box
+      # @param west_longitude [Numeric]
+      #   the longitude of the west edge of the box
+      # @param north_latitude [Numeric]
+      #   the latitude of the north edge of the box
+      # @param east_longitude [Numeric]
+      #   the longitude of the east edge of the box
+      def initialize(*args)
+        case args.length
+        when 1
+          init_from_hash(args[0])
+        when 4
+          init_from_array(args)
+        else
+          fail ArgumentError, "Can't construct GeoLocationBox from arguments: #{args}"
+        end
+      end
+
+      def south_latitude=(value)
+        fail ArgumentError, 'South latitude cannot be nil' unless value
+        fail ArgumentError, "#{value} is not a valid south latitude" unless value >= -90 && value <= 90
+        @south_latitude = value
+      end
+
+      def west_longitude=(value)
+        fail ArgumentError, 'West longitude cannot be nil' unless value
+        fail ArgumentError, "#{value} is not a valid west longitude" unless value >= -180 && value <= 180
+        @west_longitude = value
+      end
+
+      def north_latitude=(value)
+        fail ArgumentError, 'North latitude cannot be nil' unless value
+        fail ArgumentError, "#{value} is not a valid north latitude" unless value >= -90 && value <= 90
+        @north_latitude = value
+      end
+
+      def east_longitude=(value)
+        fail ArgumentError, 'East longitude cannot be nil' unless value
+        fail ArgumentError, "#{value} is not a valid east longitude" unless value >= -180 && value <= 180
+        @east_longitude = value
+      end
+
+      # Gets the box coordinates as a string.
+      # @return [String] the coordinates of the box as a sequence of four numbers, in the order S W N E.
+      def to_s
+        "#{south_latitude} #{west_longitude} #{north_latitude} #{east_longitude}"
+      end
+
+      # Sorts boxes from north to south and east to west, first by south edge, then west
+      # edge, then north edge, then east edge, and compares them for equality.
+      # @param other [GeoLocationBox] the box to compare
+      # @return [Fixnum, nil] the sort order (-1, 0, or 1), or nil if `other` is not a
+      #   {GeoLocationBox}
+      def <=>(other)
+        return nil unless other.class == self.class
+        [:south_latitude, :west_longitude, :north_latitude, :east_longitude].each do |c|
+          order = send(c) <=> other.send(c)
+          return order if order != 0
+        end
+        0
+      end
+
+      # Returns a hash code consistent with {GeoLocationBox#&lt;=&gt;}
+      # @return [Integer] the hash code
+      def hash
+        [south_latitude, west_longitude, north_latitude, east_longitude].hash
+      end
+
+      private
+
+      def init_from_hash(south_latitude:, west_longitude:, north_latitude:, east_longitude:)
+        self.south_latitude = south_latitude
+        self.west_longitude = west_longitude
+        self.north_latitude = north_latitude
+        self.east_longitude = east_longitude
+      end
+
+      def init_from_array(coordinates)
+        self.south_latitude, self.north_latitude = [coordinates[0], coordinates[2]].sort
+        self.west_longitude, self.east_longitude = [coordinates[1], coordinates[3]].sort
+      end
+    end
+
+    # XML mapping node for `<geoLocationBox/>`
+    class GeoLocationBoxNode < XML::MappingExtensions::NodeBase
+      # Converts a whitespace-separated list of coordinates to a {GeoLocationBox}.
+      # @param xml_text [String] the coordinates, in the order `lat long lat long`.
+      def to_value(xml_text)
+        stripped = xml_text.strip
+        coords = stripped.split(/\s+/).map(&:to_f)
+        GeoLocationBox.new(*coords)
+      end
+    end
+    XML::Mapping.add_node_class GeoLocationBoxNode
+
+  end
+end

data/lib/datacite/mapping/geo_location_point.rb

@@ -0,0 +1,102 @@
+require 'xml/mapping'
+
+module Datacite
+  module Mapping
+    # A latitude-longitude point at which the data was gathered or about
+    # which the data is focused.
+    #
+    # @!attribute [rw] latitude
+    #   @return [Numeric] the latitude
+    # @!attribute [rw] longitude
+    #   @return [Numeric] the longitude
+    class GeoLocationPoint
+      include Comparable
+
+      attr_reader :latitude
+      attr_reader :longitude
+
+      # Initializes a new {GeoLocationPoint}. The arguments can be provided
+      # either as a named-parameter hash, or as a pair of coordinates in the
+      # form `lat, long`. That is, the following forms are equivalent:
+      #
+      #     GeoLocationPoint.new(latitude: 47.61, longitude: -122.33)
+      #
+      #     GeoLocationPoint.new(47.61, -122.33)
+      #
+      # @param latitude [Numeric] the latitude
+      # @param longitude [Numeric] the longitude
+      def initialize(*args)
+        case args.length
+        when 1
+          init_from_hash(args[0])
+        when 2
+          init_from_array(args)
+        else
+          fail ArgumentError, "Can't construct GeoLocationPoint from arguments: #{args}"
+        end
+      end
+
+      def latitude=(value)
+        fail ArgumentError, 'Latitude cannot be nil' unless value
+        fail ArgumentError, "#{value} is not a valid latitude" unless value >= -90 && value <= 90
+        @latitude = value
+      end
+
+      def longitude=(value)
+        fail ArgumentError, 'Longitude cannot be nil' unless value
+        fail ArgumentError, "#{value} is not a valid longitude" unless value >= -180 && value <= 180
+        @longitude = value
+      end
+
+      # Gets the coordinates as a string.
+      # @return [String] the coordinates as a pair of numbers separated by a space, in the
+      #   order `lat` `long`.
+      def to_s
+        "#{latitude} #{longitude}"
+      end
+
+      # Sorts points from north to south and from east to west, and compares them for equality.
+      # @param other [GeoLocationPoint] the point to compare
+      # @return [Fixnum, nil] the sort order (-1, 0, or 1), or nil if `other` is not a
+      #   {GeoLocationPoint}
+      def <=>(other)
+        return nil unless other.class == self.class
+        [:latitude, :longitude].each do |c|
+          order = send(c) <=> other.send(c)
+          return order if order != 0
+        end
+        0
+      end
+
+      # Returns a hash code consistent with {GeoLocationPoint#&lt;=&gt;}
+      # @return [Integer] the hash code
+      def hash
+        [latitude, longitude].hash
+      end
+
+      private
+
+      def init_from_hash(latitude:, longitude:)
+        self.latitude = latitude
+        self.longitude = longitude
+      end
+
+      def init_from_array(args)
+        self.latitude, self.longitude = args
+      end
+    end
+
+    # XML mapping node for `<geoLocationPoint/>`
+    class GeoLocationPointNode < XML::MappingExtensions::NodeBase
+      # Converts a whitespace-separated pair of coordinates to a {GeoLocationPoint}.
+      # @param xml_text [String] the coordinates, in the order `lat` `long`.
+      def to_value(xml_text)
+        stripped = xml_text.strip
+        coords = stripped.split(/\s+/).map(&:to_f)
+        GeoLocationPoint.new(*coords)
+      end
+    end
+    XML::Mapping.add_node_class GeoLocationPointNode
+
+  end
+end

data/lib/datacite/mapping/identifier.rb

@@ -0,0 +1,45 @@
+require 'xml/mapping'
+
+module Datacite
+  module Mapping
+    # The persistent identifier that identifies the resource.
+    #
+    # @!attribute [r] identifier_type
+    #   @return [String] the identifier type (always 'DOI')
+    # @!attribute [rw] value
+    #   @return [String] the identifier value. Must be a valid DOI value (`10.`_registrant code_`/`_suffix_)
+    class Identifier
+      include XML::Mapping
+
+      text_node :identifier_type, '@identifierType'
+      text_node :value, 'text()'
+
+      # Initializes a new {Identifier}
+      # @param value [String]
+      #   the identifier value. Must be a valid DOI value (`10.`_registrant code_`/`_suffix_)
+      def initialize(value:)
+        self.identifier_type = 'DOI'
+        self.value = value
+      end
+
+      alias_method :_value=, :value=
+      private :_value=
+
+      alias_method :_identifier_type=, :identifier_type=
+      private :_identifier_type=
+
+      def value=(v)
+        fail ArgumentError, "Identifier value '#{v}' is not a valid DOI" unless v.match(%r{10\..+/.+})
+        self._value = v
+      end
+
+      # Sets the identifier type. Should only be called by the XML mapping engine.
+      # @param v [String]
+      #   the identifier type (always 'DOI')
+      def identifier_type=(v)
+        fail ArgumentError, "Identifier type '#{v}' must be 'DOI'" unless 'DOI' == v
+        self._identifier_type = v
+      end
+    end
+  end
+end