# stash-wrapper [![Build Status](https://travis-ci.org/CDLUC3/stash-wrapper.svg?branch=master)](https://travis-ci.org/CDLUC3/stash-wrapper) [![Code Climate](https://codeclimate.com/github/CDLUC3/stash-wrapper.svg)](https://codeclimate.com/github/CDLUC3/stash-wrapper) [![Inline docs](http://inch-ci.org/github/CDLUC3/stash-wrapper.svg)](http://inch-ci.org/github/CDLUC3/stash-wrapper) [![Gem Version](https://img.shields.io/gem/v/stash-wrapper.svg)](https://github.com/CDLUC3/stash-wrapper/releases) Gem for working with the [Stash](https://github.com/CDLUC3/stash) [XML wrapper format](https://dash.cdlib.org/stash_wrapper/stash_wrapper.xsd). The `StashWrapper` object graph mostly mirrors the `stash_wrapper` schema, though some simpler elements have been collapsed into object attributes. Also, some classes and attributes have slightly different names from the corresponding XML attributes in order to avoid colliding with Ruby keywords (e.g. `end` ⇒ `end_date`) or standard types (e.g. `file` ⇒ `StashFile`). | Schema element | Corresponding class or field | Attribute type | | -------------- | ------------------- | ---- | | `` | `StashWrapper` | | | `` | `Identifier` | | | `` | `StashAdministrative` | | | `` | `Version` | | | `` | `Version.version_number` | `Integer` | | `` | `Version.date` | `Date` | | | `` | `License` | | | `` | `License.name` | `String` | | `` | `License.uri` | `URI` | | `` | `Embargo` | | | `` | `Embargo.type` | `EmbargoType` | | `` | `Embargo.period` | `String` | | `` | `Embargo.start_date` | `Date` | | `` | `Embargo.end_date` | `Date` | | `` | `Inventory` | | | `` | `StashFile` | | | `` | `StashFile.pathname` | `String` | | `` | `Size` | | | `` | `StashFile.mime_type` | `MIME::Type` | | `` | `StashWrapper.descriptive_elements` | `Array` | Note that [TypesafeEnum](https://github.com/dmolesUC3/typesafe_enum) classes are provided for embargo type (`EmbargoType`), identifier type (`IdentifierType`), and size unit (`SizeUnit`). ## Usage The `Stash::Wrapper::StashWrapper` class represents a single Stash wrapper document. It accepts a payload of one or more XML metadata documents in the form of the `descriptive_elements` attribute, an array of `REXML::Element` objects. On calling `save_to_xml` on the `StashWrapper` instance, these elements will be embedded in the wrapper's `` element. ### Full example ```ruby require 'stash/wrapper' ST = Stash::Wrapper identifier = ST::Identifier.new( type: ST::IdentifierType::DOI, value: '10.14749/1407399498' ) version = ST::Version.new( number: 1, date: Date.new(2013, 8, 18), note: 'Sample wrapped Datacite document' ) license = ST::License::CC_BY embargo = ST::Embargo.new( type: ST::EmbargoType::DOWNLOAD, period: '1 year', start_date: Date.new(2013, 8, 18), end_date: Date.new(2014, 8, 18) ) inventory = ST::Inventory.new( files: [ ST::StashFile.new( pathname: 'HSRC_MasterSampleII.dat', size_bytes: 12_345, mime_type: 'text/plain' ), ST::StashFile.new( pathname: 'HSRC_MasterSampleII.csv', size_bytes: 67_890, mime_type: 'text/csv' ), ST::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 = ST::StashWrapper.new( identifier: identifier, version: version, license: license, embargo: embargo, inventory: inventory, descriptive_elements: [datacite_root] ) wrapper_xml = wrapper.save_to_xml formatter = REXML::Formatters::Pretty.new formatter.compact = true puts formatter.write(wrapper_xml, '') ``` ## Generating sample data The script `bin/gen_stash_wrapper_sample` will generate sample wrapper files with embedded datacite metadata and [lorem ipsum](https://en.wikipedia.org/wiki/Lorem_ipsum)-style placeholder content. With no arguments, it will generate one file and write it to standard output; with a numeric argument, it will generate that number of files and write them to the current working directory. When generating multiple files, the script pulls from a relatively small pool of randomly generated authors (1000), publishers (100), and resource types (20), so that files generated in the same session will share some metadata field values. The MIME types of the `` entries in a single session will also be pulled from a small subset (20) of real MIME types, and the file extensions should match, but the MIME types, being randomly selected, are likely to be nonsensical. ### Single file to standard output ``` % gen_stash_wrapper_sample 10.21585/def1000001 1 2014-03-16Z Mecum noctem illam superiorem; iam intellege Creative Commons Attribution 4.0 International (CC-BY) https://creativecommons.org/licenses/by/4.0/legalcode none none 2014-03-16Z 2014-03-16Z nocte.mng 2244 video/x-mng constrictam.htc 2228 text/x-component teneri.plt 55719 application/vnd.hp-HPGL oculis.uvg 8080 image/vnd.dece.graphic 10.21585/def1000001 Interficiere Statum Armis Speculabuntur Iste Relinqueres Opimius Ordinis Vivis Admirandum, dies Furorem Nostro Multis Mores Nocturnum Ahala Tam 2014 convenit domus neque ora paulo perniciosum poena res scientia tuorum te Pridem oportebat, in te conferri pestem, quam tu in nos omnes iam diu machinaris. an vero vir amplissumus, scipio, pontifex maximus, gracchum mediocriter labefactantem statum rei publicae privatus interfecit; catilinam orbem terrae caede atque incendiis vastare cupientem nos consules perferemus? nam illa nimis antiqua praetereo, quod servilius ahala maelium novis rebus studentem manu sua occidit. fuit, fuit ista quondam in hac re publica virtus, ut viri. ``` ### Multiple files ``` % cd /tmp % gen_stash_wrapper_sample 10 /tmp/stash_wrapper-01.xml /tmp/stash_wrapper-02.xml /tmp/stash_wrapper-03.xml /tmp/stash_wrapper-04.xml /tmp/stash_wrapper-05.xml /tmp/stash_wrapper-06.xml /tmp/stash_wrapper-07.xml /tmp/stash_wrapper-08.xml /tmp/stash_wrapper-09.xml /tmp/stash_wrapper-10.xml ```