ddex 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c76db225ee4e588bb9465ab9801b6ee5bbe6b4dd
+  data.tar.gz: c80d0d61497678b6973aa2f824cb7d56565ab91f
+SHA512:
+  metadata.gz: d3ca2feb13983f100d20677cd7de6953dca9e03548d9ff6fa37a8d70f45e36fda273ef1c77fd735cb40fe3a2354137d51941a95d093c53f9449d0512c1a414df
+  data.tar.gz: 56fa38d1de3bca0de8fe49a93eb5c38d68df83c5b3bf17b9e56d2b791eff094de3936c0125dea08e02153e3c486f516f224f3c9d89c7ae99170c73592d5e1348

data/README.rdoc

@@ -0,0 +1,170 @@
+= DDEX
+
+{<img src="https://secure.travis-ci.org/sshaw/ddex.svg"/>}[http://travis-ci.org/sshaw/ddex]
+
+{DDEX}[http://ddex.net] metadata serialization for Ruby
+
+=== Overview
+
+ require "ddex"
+
+ message = DDEX.read("path/to/metadata.xml")  # ERN
+ puts message.update_indicator
+ message.resource_list.sound_recordings.each do |sr|
+   title = sr.reference_title.title_text
+   puts title.value
+   puts title.language_and_script_code
+   puts sr.remastered?
+ end
+
+ puts "Supported!" if DDEX.supports?("ern/341")
+
+ message = DDEX.read(string)
+ message = DDEX.read(io)
+ p message.to_hash
+
+ include DDEX::ERN::V341   # v3.4.1
+ message = NewReleaseMessage.new(:resource_list => ResourceList.new)
+ record  = SoundRecording.new(:language_and_script_code => "en-US")
+ # ...
+ message.resource_list.sound_recordings = [record]
+
+ xml = DDEX.write(message)
+ File.open("bloat.xml", "w") { |io| io.puts(xml) }
+
+=== Installation
+
+Rubygems:
+
+  gem install ddex
+
+Bundler:
+
+  gem "ddex"
+
+=== Supported Versions
+
+Currently just ERN 3.3 - 3.7, DSR soon!
+
+=== How This Differs From the Spec
+
+Every DDEX version handled by this module is fully supported, but there are some things you'll need to know.
+
+==== Naming Conventions
+
+DDEX elements and attributes use the {CamelCase naming convention}[https://en.wikipedia.org/wiki/CamelCase], this module uses Ruby naming conversions:
+CamelCase for classes, and {snake_case}[https://en.wikipedia.org/wiki/Snake_case] for class attributes. For example, this DDEX XML:
+
+  <PartyName>
+    <FullName>sshaw</FullName>
+  </PartyName>
+
+Would be manipulated via:
+
+  party = PartyName.new(:full_name => "sshaw")
+  puts party.full_name
+  party.full_name = "gwozdzie"
+
+
+See also {Boolean elements and attributes}[rdoc-ref:README@Boolean+Elements+and+Attributes]
+
+==== Cardinally
+
+Elements that _can_ occur more than once will be placed in an <code>Array</code> and their parent classes' accessor methods will use the plural form of
+the element/attribute's name. For example:
+
+  <Release>
+    <!-- More data -->
+    <PLine>
+      <Year>1994</Year>
+      <PLineText>Track Copyright</PLineText>
+    </PLine>
+    <PLine>
+      <Year>2001</Year>
+      <PLineText>Another Track Copyright</PLineText>
+    </PLine>
+  </Release>
+
+Would be manipulated via:
+
+  release.p_lines.each { |line| puts line.p_line_text }
+  release.p_lines << PLine.new(:year => 1999)
+
+==== Boolean Elements and Attributes
+
+The following are applied to accessors derived from DDEX elements and attributes with an XML schema type of +boolean+:
+
+* <code>"Is"</code> is removed from the beginning of the name
+* The *reader* *method* is turned into a predicate accessor, i.e., has a <code>"?"</code> appended to it
+
+For example, <code>SoundRecording/IsArtistRelated</code>:
+
+  recording = SoundRecording.new(:artist_related => true)
+  p recording.artist_related?  # true
+  recording.artist_related = false
+
+==== Version Specific Changes
+
+These changes only affect the object model, the resulting XML will conform to the appropriate DDEX schema.
+
+===== ERN >= v3.6
+
+<code>PriceInformation/@PriceType</code> has been renamed to <code>PriceInformation#type</code> to avoid conflicting with the
+element of the same name (<code>PriceInformation/PriceType</code>).
+
+=== Specification Version Detection
+
+The specification version is determined by the <code>MessageSchemaVersionId</code>, which can be:
+
+1. Detected based on the root element's value i.e., <code>/node()/@MessageSchemaVersionId</code> (the root element varies by specification)
+2. Explicitly given to DDEX.read via the <code>:version</code> option
+
+By default the <code>MessageSchemaVersionId</code> is assumed to be in <code>SPEC/VERSION</code> format (any leading, trailing, or duplicate slashes will be stripped),
+as this seems to be the convention used by most instance docs -though the DDEX specifications
+{are not strict about this}[http://www.ddex.net/content/format-messageschemaversionid]. If you're dealing with <code>MessageSchemaVersionId</code>s
+that vary from this format, and explicitly setting the version is not practical, you can set the global default(s):
+
+  DDEX::ERN.config["V35"][:message_schema_version_id] = "ern tray_fever!"
+  DDEX::ERN.config["V351"][:message_schema_version_id] = "ern/35-punto-1"
+  # ...
+
+Note that the version key must match the version's module name.
+
+Feel free to {open an issue}[https://github.com/sshaw/ddex/issues] if you feel this arrangement is problematic or should
+be modified to accommodate something more than <code>SPEC/VERSION</code> out of the box.
+
+=== Validation
+
+Not yet!
+
+=== More Info
+
+* {Source code}[https://github.com/sshaw/ddex]
+* {Bugs}[https://github.com/sshaw/ddex/issues]
+* {jaxb2ruby}[https://github.com/sshaw/jaxb2ruby] (Generate Ruby objects from an XML schema)
+* {DDEX Schemas}[http://ddex.net/xml]
+
+=== TODO/Known Problems
+
+* <code>ROXML.from_xml</code> does not check the root element's name. Need to add something like:
+
+    raise "unknown element #{xml.name}" unless xml.name == tag_name
+
+* When an ROXML accessor expects an ROXML class, and one is not provided, <code>to_xml</code> will result in a <code>NoMethodError</code>:
+
+    # in SomeClass
+    xml_accessor :x, :as => AnotherClass
+
+    # Then
+    x = SomeClass.new(:x => "123") 
+    x.to_xml  # undefined method `to_xml' for "123":String
+
+  Raised here: https://github.com/Empact/roxml/blob/v2.5.1/lib/roxml/xml/references.rb#L262
+
+=== Author
+
+Skye Shaw  [skye.shaw {AT} gmail.com]
+
+=== License
+
+Copyright (c) 2013 Skye Shaw. Released under the {MIT License}[www.opensource.org/licenses/MIT].

data/lib/ddex.rb

@@ -0,0 +1,86 @@
+require "roxml"
+require "ddex/element"
+
+module DDEX
+  autoload :ERN, "ddex/ern"
+
+  XML_SCHEMA_INSTANCE_PREFIX = "xsi".freeze
+  XML_SCHEMA_INSTANCE_NS     = "http://www.w3.org/2001/XMLSchema-instance".freeze
+  XML_SCHEMA_INSTANCE_ATTR   = "#{XML_SCHEMA_INSTANCE_PREFIX}:schemaLocation".freeze
+
+  SPECS = %w[ERN]
+
+  class DDEXError < StandardError; end
+  class UnknownVersionError < DDEXError; end
+  class XMLLoadError < DDEXError; end
+
+  def self.supported_versions
+    SPECS.flat_map do |spec|
+      klass = const_get(spec)
+      klass.supported_versions.map { |v| "#{spec} #{v}" }
+    end
+  end
+
+  def self.supports?(name)
+    SPECS.any? { |spec| const_get(spec).supports?(name) }
+  end
+
+  ##
+  # Read DDEX metadata
+  #
+  # === Parameters
+  #
+  # [xml     (String|IO|path)] The XML to read
+  # [options (Hash)] Options to control reading
+  #
+  # === Options
+  #
+  # [:encoding] Parse +xml+ using the given encoding
+  # [:version]  Parse +xml+ as the given version, this must be a +MessageSchemaVersionId+ in +SPEC/VERSION+ format;
+  #		by default this will be taken from the +MessageSchemaVersionId+ attribute of the root element
+  # === Returns
+  #
+  # [DDEX::Element subclass] A root element, as defined by the DDEX spec of +xml+ or the +:version+ option
+  #
+  # === Errors
+  #
+  # [DDEX::XMLLoadError] Problem parsing the XML or a required element is missing
+  # [DDEX::UnknownVersionError] The given or detected spec version is not known or supported
+  # [ArgumentError] +options+ is not a +Hash+ or is not +nil+
+
+  def self.read(xml, options = nil)
+    # TODO: figure out what top level spec...
+    DDEX::ERN.read(xml, options)
+  end
+
+  ##
+  # Turn a DDEX object into an XML string. You can also turn the object into a +Hash+ via #to_hash.
+  #
+  # === Parameters
+  #
+  # [xml     (DDEX::Element subclass)] The object to create XML from
+  # [options (Hash)] Options to control writing
+  #
+  # === Options
+  #
+  # [:schema] Schema URI to use in the XSI schemaLocation attribute, defaults to <code>DDEX::NAME.config["VER"][:schema]</code>
+  #           where +NAME+ is the spec name and +VER+ is the version. This is only used if +xml+ is a the root node of a spec.
+  #
+  # === Returns
+  #
+  # [String] The XML
+  #
+  # === Errors
+  #
+  # [ArgumentError] +options+ is not a +Hash+ or is not +nil+, or +xml+ is not a subclass of <code>DDEX::Element</code>
+
+  def self.write(xml, options = nil)
+    DDEX::ERN.write(xml, options)
+  end
+
+  protected
+  def require_standard(name, version)
+    root = File.dirname(File.expand_path(__FILE__))
+    Dir["#{root}/ddex/#{name.downcase}/v#{ version.downcase.tr(".", "") }/*.rb"].each { |path| require path }
+  end
+end

data/lib/ddex/element.rb

@@ -0,0 +1,103 @@
+module DDEX
+  class Element
+    include ROXML
+
+    # Set parser for ROXML
+    XML_PARSER = "nokogiri".freeze
+
+    xml_convention :camelcase
+
+    # ROXML doesn't have complete namespace support.
+    # We use this to set a namespace on calls to to_xml().
+    class << self
+      def ns
+        @namespace
+      end
+
+      private
+      def setns(prefix, name)
+        @namespace = [prefix, name].compact
+      end
+    end
+
+    ##
+    # Create an new instance
+    #
+    # === Arguments
+    #
+    # [attributes (Hash)] Values to set on the instance's attributes, a nested +Hash+ <b>will not</b> result in instantiation of child objects.
+    #
+    # === Errors
+    #
+    # [ArgumentError] If +attributes+ is not a +Hash+ or is not +nil+
+
+    def initialize(attributes = nil)
+      attributes ||= {}
+      raise ArgumentError, "attributes must be a Hash" unless Hash === attributes
+
+      attributes.each do |name, value|
+        name   = name.to_s
+        method = "#{name}="
+        next unless attr = roxml_attributes[name] and respond_to?(method)
+
+        value = Array(value) if !attr.sought_type.instance_of?(Symbol) && attr.array? # If it's not a ROXML directive && ...
+        send(method, value)
+      end
+    end
+
+    ##
+    # Creates an XML representation of this instance and its descendants. Use DDEX.write instead, it's more flexable.
+    #
+
+    def to_xml(options = {})
+      doc = super
+      ns  = self.class.ns
+
+      if ns and ns.size == 2 # prefix and name
+        doc.add_namespace_definition(*ns)
+        doc.name = "#{ns.first}:#{doc.name}"
+      end
+
+      doc
+    end
+
+    ##
+    # Create a +Hash+ representation of this instance and its descendants
+    #
+
+    def to_hash
+      hash = {}
+      roxml_attributes.values.each do |attr|
+        value = send(attr.accessor)
+        value = if value.is_a?(Array)
+          value.map { |v| v.respond_to?(:to_hash) ? v.to_hash : v }
+        else
+          value.respond_to?(:to_hash) ? value.to_hash : value
+        end
+
+        hash[attr.attr_name.to_sym] = value unless value.nil?
+      end
+
+      hash
+    end
+
+    def eql?(other)
+      instance_of?(other.class) && roxml_attributes.values.all? { |attr| other.respond_to?(attr.accessor) && other.send(attr.accessor) == send(attr.accessor) }
+    end
+
+    def ==(other)
+      eql?(other)
+    end
+
+    # TODO: hash()
+
+    private
+    def roxml_attributes
+      @roxml_attributes ||= begin
+        attr = {}
+        self.class.roxml_attrs.each { |v| attr[v.attr_name] = v }
+        attr
+      end
+    end
+  end
+end

data/lib/ddex/ern.rb

@@ -0,0 +1,158 @@
+require "active_support/core_ext/module/attribute_accessors"
+require "nokogiri"
+
+module DDEX
+  module ERN
+    autoload :V33,  "ddex/ern/v33"
+    autoload :V34,  "ddex/ern/v34"
+    autoload :V341, "ddex/ern/v341"
+    autoload :V35,  "ddex/ern/v35"
+    autoload :V351, "ddex/ern/v351"
+    autoload :V36,  "ddex/ern/v36"
+    autoload :V37,  "ddex/ern/v37"
+
+    ROOT_ELEMENT = "NewReleaseMessage".freeze
+    VERSION_ATTR = "MessageSchemaVersionId".freeze
+
+    DEFAULT_CONFIG  = {
+      "V37" => {
+        :schema => "http://ddex.net/xml/ern/37/release-notification.xsd",
+        :version => "3.7",
+        :message_schema_version_id => "ern/37"
+      },
+
+      "V36" => {
+        :schema => "http://ddex.net/xml/ern/36/release-notification.xsd",
+        :version => "3.6",
+        :message_schema_version_id => "ern/36"
+      },
+
+      "V351" => {
+        :schema => "http://ddex.net/xml/ern/351/release-notification.xsd",
+        :version => "3.5.1",
+        :message_schema_version_id => "ern/351"
+      },
+
+      "V35" => {
+        :schema => "http://ddex.net/xml/ern/35/release-notification.xsd",
+        :version => "3.5",
+        :message_schema_version_id => "ern/35"
+      },
+
+      "V341" => {
+        :schema => "http://ddex.net/xml/ern/341/release-notification.xsd",
+        :version => "3.4.1",
+        :message_schema_version_id => "ern/341"
+      },
+
+      "V34" => {
+        :schema => "http://ddex.net/xml/ern/34/release-notification.xsd",
+        :version => "3.4",
+        :message_schema_version_id => "ern/34"
+      },
+
+      "V33" => {
+        :schema => "http://ddex.net/xml/2011/ern-main/33/ern-main.xsd",
+        :version => "3.3",
+        :message_schema_version_id => "2011/ern-main/33"
+      }
+    }.freeze
+
+    mattr_reader :config
+    @@config = DEFAULT_CONFIG
+
+    def self.supported_versions
+      config.values.map { |cfg| cfg[:version].dup }.sort
+    end
+
+    def self.supports?(version)
+      version = version.downcase.strip
+      config.any? { |name,cfg| name == version || cfg[:version] == version || cfg[:message_schema_version_id] == version }
+    end
+
+    # options[:validate] ???
+    def self.read(xml, options = nil)
+      options ||= {}
+      raise ArgumentError, "options must be a Hash" unless options.is_a?(Hash)
+
+      doc   = parse(xml, options)
+      ver   = options[:version] || doc.root[VERSION_ATTR]
+      klass = load_version(ver)
+
+      begin
+        klass.from_xml(doc)
+      rescue NoMethodError => e         # Yes, fo real... this is from ROXML
+        raise unless e.name == :root    # It's legit
+        raise XMLLoadError, "XML is not well-formed"
+      # This is a subclass of Exception(!) so we must name it
+      rescue ROXML::RequiredElementMissing => e
+        raise XMLLoadError, "missing required element: #{e}"
+      end
+    end
+
+    def self.write(object, options = nil)
+      raise ArgumentError, "not a DDEX object" unless object.is_a?(DDEX::Element)
+
+      options ||= {}
+      raise ArgumentError, "options must be a Hash" unless options.is_a?(Hash)
+
+      xmlopts = options.reject { |k, _| k == :schema }
+
+      node = object.to_xml
+      return node.to_xml(xmlopts) unless object.respond_to?(:message_schema_version_id) # Is it the root element?
+
+      schema = schema_location(object, options[:schema])
+      if schema
+        node.add_namespace_definition(XML_SCHEMA_INSTANCE_PREFIX, XML_SCHEMA_INSTANCE_NS)
+        node[XML_SCHEMA_INSTANCE_ATTR] = schema
+      end
+
+      doc = Nokogiri::XML::Document.new
+      doc.root = node
+      doc.to_xml(xmlopts)
+    end
+
+    private
+    def self.schema_location(object, schema)
+      # extract version from namespace e.g., DDEX::ERN::V36::NewReleaseMessage
+      ver = object.class.name.split("::")[-2]
+      return unless schema or config.include?(ver)
+
+      # Check if it's "NS schema"
+      if schema && schema.strip.include?(" ")
+        schema
+      else
+        sprintf "%s %s", object.class.ns[1], schema || config[ver][:schema]
+      end
+    end
+
+    def self.parse(xml, options)
+      xml = File.read(xml) if xml.is_a?(String) and xml !~ /\A\s*<[?\w]/
+      Nokogiri::XML(xml, nil, options[:encoding]) { |cfg| cfg.strict }
+    # ArgumentError means there was a problem with types, expected an int, got a str
+    rescue IOError, SystemCallError, ArgumentError => e
+      raise XMLLoadError, "cannot load XML: #{e}"
+    rescue Nokogiri::XML::SyntaxError => e
+      raise XMLLoadError, "XML parsing error: #{e}"
+    end
+
+    def self.raise_unknown_version(version)
+      message = "ERN version %s" % (version ? "'#{version}'" : "attribute missing")
+      raise UnknownVersionError, message
+    end
+
+    def self.load_version(version)
+      raise_unknown_version(version) if version.nil?
+
+      # Some normalization
+      v = version.strip.gsub(%r{//+}, "/").gsub(%r{\A/|/\Z}, "")
+      klass, _ = config.find { |name, cfg| cfg[:message_schema_version_id] == v }
+      raise_unknown_version(version) unless klass
+
+      # >= 2.0 allows for one call
+      DDEX::ERN.const_get(klass).const_get(ROOT_ELEMENT)
+    rescue LoadError, NameError => e
+      raise_unknown_version(version)
+    end
+  end
+end