stash-wrapper 0.1.1

data/example.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+
+require 'stash/wrapper'
+
+include Stash::Wrapper
+
+identifier = Identifier.new(
+  type: IdentifierType::DOI,
+  value: '10.14749/1407399498'
+)
+
+version = Version.new(
+  number: 1,
+  date: Date.new(2013, 8, 18),
+  note: 'Sample wrapped Datacite document'
+)
+
+license = License::CC_BY
+
+embargo = Embargo.new(
+  type: EmbargoType::DOWNLOAD,
+  period: '1 year',
+  start_date: Date.new(2013, 8, 18),
+  end_date: Date.new(2014, 8, 18)
+)
+
+inventory = Inventory.new(
+  files: [
+    StashFile.new(
+      pathname: 'HSRC_MasterSampleII.dat', size_bytes: 12_345, mime_type: 'text/plain'
+    ),
+    StashFile.new(
+      pathname: 'HSRC_MasterSampleII.csv', size_bytes: 67_890, mime_type: 'text/csv'
+    ),
+    StashFile.new(
+      pathname: 'HSRC_MasterSampleII.sas7bdat', size_bytes: 123_456, mime_type: 'application/x-sas-data'
+    )
+  ])
+
+datacite_file = 'spec/data/wrapper/wrapper-2-payload.xml'
+datacite_root = REXML::Document.new(File.read(datacite_file)).root
+
+wrapper = StashWrapper.new(
+  identifier: identifier,
+  version: version,
+  license: license,
+  embargo: embargo,
+  inventory: inventory,
+  descriptive_elements: [datacite_root]
+)
+
+puts wrapper.write_xml

data/lib/stash/wrapper.rb

@@ -0,0 +1,6 @@
+module Stash
+  # Code relating to the {https://dash.cdlib.org/stash_wrapper/ Stash wrapper format}
+  module Wrapper
+    Dir.glob(File.expand_path('../wrapper/*.rb', __FILE__), &method(:require))
+  end
+end

data/lib/stash/wrapper/descriptive_node.rb

@@ -0,0 +1,38 @@
+require 'xml/mapping'
+
+module Stash
+  module Wrapper
+
+    # Node class for `<st:stash_descriptive>` elements.
+    class DescriptiveNode < XML::Mapping::SingleAttributeNode
+
+      # See `XML::Mapping::SingleAttributeNode#initialize`
+      def initialize(*args)
+        path, *args = super(*args)
+        @path = ::XML::XXPath.new(path)
+        args
+      end
+
+      # Extracts the children of this element as an array.
+      # @param xml [REXML::Element] this `<st:stash_descriptive>` element
+      # @return [Array<REXML::Element>] the child elements
+      def extract_attr_value(xml)
+        default_when_xpath_err { @path.first(xml).elements.to_a }
+      end
+
+      # Sets the array of elements representetd by this node
+      # as the children of the corresponding `<st:stash_descriptive>`
+      # element.
+      # @param xml [REXML::Element] this element
+      # @param value [Array<REXML::Element>] the child elements
+      def set_attr_value(xml, value)
+        parent = @path.first(xml, ensure_created: true)
+        value.each do |child|
+          parent.elements.add(child)
+        end
+      end
+
+    end
+    XML::Mapping.add_node_class DescriptiveNode
+  end
+end

data/lib/stash/wrapper/embargo.rb

@@ -0,0 +1,30 @@
+require 'xml/mapping_extensions'
+require_relative 'embargo_type'
+
+module Stash
+  module Wrapper
+
+    # Mapping class for `<st:embargo>`
+    class Embargo
+      include ::XML::Mapping
+
+      typesafe_enum_node :type, 'type', class: EmbargoType
+      text_node :period, 'period'
+      date_node :start_date, 'start', zulu: true
+      date_node :end_date, 'end', zulu: true
+
+      # Creates a new {Embargo} object
+      # @param type [EmbargoType] The embargo type
+      # @param period [String] The embargo period
+      # @param start_date [Date] The embargo start date
+      # @param end_date [Date] The embargo end date
+      def initialize(type:, period:, start_date:, end_date:)
+        self.type = type
+        self.period = period
+        self.start_date = start_date
+        self.end_date = end_date
+      end
+    end
+
+  end
+end

data/lib/stash/wrapper/embargo_type.rb

@@ -0,0 +1,10 @@
+require 'typesafe_enum'
+
+module Stash
+  module Wrapper
+    # Controlled vocabulary for {Embargo#type}
+    class EmbargoType < TypesafeEnum::Base
+      [:NONE, :DOWNLOAD, :DESCRIPTION].each { |t| new t }
+    end
+  end
+end

data/lib/stash/wrapper/identifier.rb

@@ -0,0 +1,21 @@
+require 'xml/mapping_extensions'
+require_relative 'identifier_type'
+
+module Stash
+  module Wrapper
+
+    # Mapping class for `<st:identifier>`
+    class Identifier
+      include ::XML::Mapping
+      typesafe_enum_node :type, '@type', class: IdentifierType, default_value: nil
+      text_node :value, '.', default_value: nil
+
+      # Creates a new {Identifier}
+      def initialize(type:, value:)
+        self.type = type
+        self.value = value
+      end
+    end
+
+  end
+end

data/lib/stash/wrapper/identifier_type.rb

@@ -0,0 +1,13 @@
+require 'typesafe_enum'
+
+module Stash
+  module Wrapper
+    # Controlled vocabulary for {Identifier#type}
+    class IdentifierType < TypesafeEnum::Base
+      new :ARK, 'ARK'
+      new :DOI, 'DOI'
+      new :HANDLE, 'Handle'
+      new :URL, 'URL'
+    end
+  end
+end

data/lib/stash/wrapper/inventory.rb

@@ -0,0 +1,22 @@
+require 'xml/mapping'
+require_relative 'stash_file'
+
+module Stash
+  module Wrapper
+
+    # Mapping class for `<st:inventory>`
+    class Inventory
+      include ::XML::Mapping
+
+      array_node :files, 'file', class: StashFile, default_value: []
+      numeric_node :num_files, '@num_files', default_value: 0
+
+      # creates a new {Inventory} object
+      # @param files [List<StashFile>] The inventory of files
+      def initialize(files:)
+        self.files = files
+        self.num_files = files.size
+      end
+    end
+  end
+end

data/lib/stash/wrapper/license.rb

@@ -0,0 +1,30 @@
+require 'xml/mapping'
+require 'xml/mapping_extensions'
+
+module Stash
+  module Wrapper
+    # Mapping class for `<st:license>`
+    class License
+      include ::XML::Mapping
+
+      text_node :name, 'name'
+      uri_node :uri, 'uri'
+
+      # Creates a new {License} object
+      # @param name [String] The license name
+      # @param uri [URI] The license URI
+      def initialize(name:, uri:)
+        self.name = name
+        self.uri = uri
+      end
+    end
+
+    class License
+      # Convenience instance for the [CC-BY](https://creativecommons.org/licenses/by/4.0/legalcode) license
+      CC_BY = License.new(
+        name: 'Creative Commons Attribution 4.0 International (CC-BY)',
+        uri: URI('https://creativecommons.org/licenses/by/4.0/legalcode')
+      )
+    end
+  end
+end

data/lib/stash/wrapper/module_info.rb

@@ -0,0 +1,13 @@
+module Stash
+  # Code relating to the {https://dash.cdlib.org/stash_wrapper/ Stash wrapper format}
+  module Wrapper
+    # The name of this gem
+    NAME = 'stash-wrapper'
+
+    # The version of this gem
+    VERSION = '0.1.1'
+
+    # The copyright notice for this gem
+    COPYRIGHT = 'Copyright (c) 2016 The Regents of the University of California'
+  end
+end

data/lib/stash/wrapper/size.rb

@@ -0,0 +1,23 @@
+require 'xml/mapping'
+require_relative 'size_unit'
+
+module Stash
+  module Wrapper
+
+    # Mapping for `<st:size>`
+    class Size
+      include ::XML::Mapping
+
+      numeric_node :size, '.'
+      typesafe_enum_node :unit, '@unit', class: SizeUnit, default: SizeUnit::BYTE
+
+      # Creates a new {Size}
+      # @param bytes [Integer] the size in bytes
+      def initialize(bytes:)
+        self.size = bytes
+        self.unit = SizeUnit::BYTE
+      end
+    end
+
+  end
+end

data/lib/stash/wrapper/size_unit.rb

@@ -0,0 +1,11 @@
+require 'typesafe_enum'
+
+module Stash
+  module Wrapper
+    # Controlled vocabulary for {Size#unit}, with the single
+    # value {#BYTE}.
+    class SizeUnit < TypesafeEnum::Base
+      new :BYTE, 'B'
+    end
+  end
+end

data/lib/stash/wrapper/stash_administrative.rb

@@ -0,0 +1,33 @@
+require 'xml/mapping'
+require_relative 'version'
+require_relative 'license'
+require_relative 'embargo'
+require_relative 'inventory'
+
+module Stash
+  module Wrapper
+    # Mapping for `<st:stash_administrative>`
+    class StashAdministrative
+      include ::XML::Mapping
+      object_node :version, 'version', class: Version
+      object_node :license, 'license', class: License
+      object_node :embargo, 'embargo', class: Embargo
+      object_node :inventory, 'inventory', class: Inventory
+
+      # Creates a new {StashAdministrative}
+      #
+      # @param version [Version] the version
+      # @param license [License] the license
+      # @param embargo [Embargo] the embargo. Note that per the schema,
+      #   an `<st:embargo>` element is required even if there is no embargo
+      #   on the dataset (in which case it should use {EmbargoType::NONE}).
+      # @param inventory [Inventory, nil] the (optional) file inventory
+      def initialize(version:, license:, embargo:, inventory: nil)
+        self.version = version
+        self.license = license
+        self.embargo = embargo
+        self.inventory = inventory
+      end
+    end
+  end
+end

data/lib/stash/wrapper/stash_file.rb

@@ -0,0 +1,57 @@
+require 'xml/mapping'
+require 'xml/mapping_extensions'
+
+module Stash
+  module Wrapper
+    # Mapping for `<st:file>`.
+    class StashFile
+      include ::XML::Mapping
+
+      root_element_name 'file'
+
+      text_node :pathname, 'pathname'
+      object_node :size, 'size'
+      mime_type_node :mime_type, 'mime_type'
+
+      # Creates a new {StashFile} object
+      #
+      # @param pathname [String] the pathname
+      # @param size_bytes [Integer] the size in bytes
+      # @param mime_type [MIME::Type, String] the MIME type, as either a
+      #   `MIME::Type` object or a string
+      def initialize(pathname:, size_bytes:, mime_type:)
+        self.pathname = pathname
+        self.size_bytes = size_bytes
+        self.mime_type = mime_type
+      end
+
+      # Sets the MIME type, converting from a string if necessary
+      # @param value [MIME::Type, String] the MIME type, as either a
+      #   `MIME::Type` object or a string
+      def mime_type=(value)
+        @mime_type = to_mime_type(value)
+      end
+
+      # Sets the size in bytes, expanding it to a {Size} object
+      # @param bytes [Integer] the size in bytes
+      def size_bytes=(bytes)
+        self.size = Size.new(bytes: bytes)
+      end
+
+      # Gets the size in bytes, extracting it from the {Size}
+      # @return [Integer] the size in bytes
+      def size_bytes
+        size.size
+      end
+
+      private
+
+      def to_mime_type(value)
+        return nil unless value
+        return value if value.is_a?(MIME::Type)
+        mt_string = value.to_s
+        (mt = MIME::Types[mt_string].first) ? mt : MIME::Type.new(mt_string)
+      end
+    end
+  end
+end

data/lib/stash/wrapper/stash_wrapper.rb

@@ -0,0 +1,130 @@
+require 'xml/mapping'
+
+require_relative 'descriptive_node'
+require_relative 'identifier'
+require_relative 'stash_administrative'
+
+module Stash
+  module Wrapper
+    # Mapping for the root `<st:stash_wrapper>` element
+    class StashWrapper
+      include ::XML::Mapping
+
+      # The `stash_wrapper` namespace
+      NAMESPACE = 'http://dash.cdlib.org/stash_wrapper/'
+
+      # The `st` prefix for the `stash_wrapper` namespace
+      NAMESPACE_PREFIX = 'st'
+
+      root_element_name 'stash_wrapper'
+
+      object_node :identifier, 'identifier', class: Identifier
+      object_node :stash_administrative, 'stash_administrative', class: StashAdministrative
+      descriptive_node :stash_descriptive, 'stash_descriptive'
+
+      # Creates a new {StashWrapper}. As a convenience, constructs an
+      # internal {StashAdministrative} directly from the supplied
+      # administrative elements.
+      #
+      # @param identifier [Identifier] the identifier
+      # @param version [Version] the version
+      # @param license [License] the license
+      # @param embargo [Embargo] the embargo. Note that per the schema,
+      #   an `<st:embargo>` element is required even if there is no embargo
+      #   on the dataset (in which case it should use {EmbargoType::NONE}).
+      # @param inventory [Inventory, nil] the (optional) file inventory
+      # @param descriptive_elements [Array<REXML::Element>] the encapsulated
+      #   XML metadata
+      def initialize(identifier:, version:, license:, embargo:, inventory: nil, descriptive_elements:) # rubocop:disable Metrics/ParameterLists
+        self.identifier = identifier
+        self.stash_administrative = StashAdministrative.new(
+          version: version,
+          license: license,
+          embargo: embargo,
+          inventory: inventory
+        )
+        self.stash_descriptive = descriptive_elements
+      end
+
+      def id_value
+        identifier.value
+      end
+
+      def version
+        stash_administrative.version
+      end
+
+      def version_number
+        version.version_number
+      end
+
+      def version_date
+        version.date
+      end
+
+      def license
+        stash_administrative.license
+      end
+
+      def license_name
+        license.name
+      end
+
+      def license_uri
+        license.uri
+      end
+
+      def embargo
+        stash_administrative.embargo
+      end
+
+      def embargo_type
+        embargo.type
+      end
+
+      def embargo_end_date
+        embargo.end_date
+      end
+
+      def inventory
+        stash_administrative.inventory
+      end
+
+      # Overrides `XML::Mapping#pre_save` to set the XML namespace and schema location.
+      def pre_save(options = { mapping: :_default })
+        xml = super(options)
+        xml.add_namespace(NAMESPACE)
+        xml.add_namespace('xsi', 'http://www.w3.org/2001/XMLSchema-instance')
+        xml.add_attribute('xsi:schemaLocation', 'http://dash.cdlib.org/stash_wrapper/ http://dash.cdlib.org/stash_wrapper/stash_wrapper.xsd')
+        xml
+      end
+
+      # Overrides `XML::Mapping#save_to_xml` to set the XML namespace prefix on all
+      # `stash_wrapper` elements. (The elements in `descriptive_elements` should retain
+      # their existing namespaces and prefixes, if any.)
+      def save_to_xml(options = { mapping: :_default })
+        elem = super(options)
+        set_prefix(prefix: NAMESPACE_PREFIX, elem: elem)
+        elem.add_namespace(nil) # clear the no-prefix namespace
+        elem.add_namespace(NAMESPACE_PREFIX, NAMESPACE)
+        elem
+      end
+
+      def self.parse_xml(xml_str)
+        xml = REXML::Document.new(xml_str).root
+        load_from_xml(xml)
+      end
+
+      private
+
+      def set_prefix(prefix:, elem:)
+        return unless elem.namespace == NAMESPACE
+        # name= with a prefixed name sets namespace by side effect and is the only way to actually output the prefix
+        elem.name = "#{prefix}:#{elem.name}"
+        elem.each_element { |e| set_prefix(prefix: prefix, elem: e) }
+      end
+
+    end
+
+  end
+end