pbcore 0.2.0 → 0.3.0

data/lib/pbcore.rb

@@ -2,7 +2,11 @@ require "pbcore/version"
 require "pbcore/errors"
 
 module PBCore
+
+  GEM_ROOT = File.dirname(File.dirname(__FILE__))
+
   autoload :Element,                  'pbcore/element'
+  autoload :ContentElement,           'pbcore/content_element'
   autoload :Attributes,               'pbcore/attributes'
   autoload :DescriptionDocument,      'pbcore/description_document'
   autoload :AssetType,                'pbcore/asset_type'
@@ -25,4 +29,17 @@ module PBCore
   autoload :Instantiation,            'pbcore/instantiation'
   autoload :InstantiationDocument,    'pbcore/instantiation_document'
   autoload :Vocab,                    'pbcore/vocab'
+
+  class << self
+    def xsd
+      File.read(File.join(GEM_ROOT, 'lib', 'pbcore-2.1.xsd'))
+    end
+
+    def validate(xml)
+      errors = Nokogiri::XML::Schema(xsd).validate(Nokogiri::XML(xml))
+      raise ValidationError, "#{errors.count} errors:\n#{errors.join("\n")}" unless errors.empty?
+    end
+  end
+
+  class ValidationError < StandardError; end
 end

data/lib/pbcore/annotation.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Annotation < Element
+  class Annotation < ContentElement
     element :pbcoreAnnotation, as: :value
     attribute :annotationType, as: :type
 

data/lib/pbcore/asset_date.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class AssetDate < Element
+  class AssetDate < ContentElement
     element :pbcoreAssetDate, as: :value
     attribute :dateType, as: :type
 

data/lib/pbcore/asset_type.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class AssetType < Element
+  class AssetType < ContentElement
     element :pbcoreAssetType, as: :value
 
     build_xml do |xml|

data/lib/pbcore/audience_level.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class AudienceLevel < Element
+  class AudienceLevel < ContentElement
     element :pbcoreAudienceLevel, as: :value
 
     build_xml do |xml|

data/lib/pbcore/audience_rating.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class AudienceRating < Element
+  class AudienceRating < ContentElement
     element :pbcoreAudienceRating, as: :value
 
     build_xml do |xml|

data/lib/pbcore/content_element.rb

@@ -0,0 +1,11 @@
+module PBCore
+  class ContentElement < Element
+    # Defind attributes common to all PBCore "content elements", which is a term
+    # we're using to refer to elements that contain text instead of subelements.
+    # In PBCore you can either contain text or subelements, but not both.
+    attribute :source
+    attribute :ref
+    attribute :annotation
+    attribute :version
+  end
+end

data/lib/pbcore/contributor/contributor.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Contributor::Contributor < Element
+  class Contributor::Contributor < ContentElement
     element :contributor, as: :value
     attribute :affiliation, as: :affiliation
 

data/lib/pbcore/contributor/role.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Contributor::Role < Element
+  class Contributor::Role < ContentElement
     element :contributorRole, as: :value
     attribute :portrayal, as: :portrayal
 

data/lib/pbcore/coverage/coverage.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Coverage::Coverage < Element
+  class Coverage::Coverage < ContentElement
     element :coverage, as: :value
 
     build_xml do |xml|

data/lib/pbcore/creator/creator.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Creator::Creator < Element
+  class Creator::Creator < ContentElement
     element :creator, as: :value
     attribute :affiliation, as: :affiliation
     attribute :affiliationSource, as: :affiliation_source

data/lib/pbcore/creator/role.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Creator::Role < Element
+  class Creator::Role < ContentElement
     element :creatorRole, as: :value
 
     build_xml do |xml|

data/lib/pbcore/description.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Description < Element
+  class Description < ContentElement
     element :pbcoreDescription, as: :value
     attribute :descriptionType, as: :type
     attribute :descriptionTypeRef, as: :type_ref

data/lib/pbcore/element.rb

@@ -8,7 +8,6 @@ module PBCore
   # TODO: decouple XML building behavior from schema-related declarations.
   class Element
     include SAXMachine
-    include PBCore::Attributes::Common
 
     # Defines which accessor is used to get the value within an element.
     # Here we defined it be simply :value.
@@ -16,15 +15,9 @@ module PBCore
       val == :no_buffer ? nil : val
     end
 
-    # Defind attributes common to all PBCore elements.
-    # attribute :source
-    # attribute :ref
-    # attribute :annotation
-    # attribute :version
-
     # Returns a hash of child element instances.
     def elements(key_by_xml_name: false)
-      key_value_pairs_array = self.class.element_config_all.map do |name, element_configs|
+      key_value_pairs_array = self.class.all_element_config.map do |name, element_configs|
         # SAXMachine allows you to declare multiple elements with the same name
         # but we don't do tha with PBCore, so just grab the first and only one.
         element_config = element_configs.first
@@ -84,43 +77,18 @@ module PBCore
         @build_block = block
       end
 
-      # Returns true if the element is configured to contain a single instance
-      # of a child element that matches the name and opts parameters.
-      def has_one?(name, opts={})
-        element_config_has_one.any? do |element_config|
-          opts.all? do |key, val|
-            # In SAXMachine::SaxConfig::ElementConfig, the :class config option
-            # maps to instance variable @data_class.
-            key = :data_class if key == :class
-            val == element_config.instance_variable_get(:"@#{key}")
-          end
-        end
-      end
-
-      # Returns true if the element is configured to contain many instances of
-      # a child element that matches the name and opts parameters.
-      def has_many?(name, opts={})
-        element_config_has_many.any? do |element_config|
-          opts.all? do |key, val|
-            val == element_config.instance_variable_get(:"@#{key}")
-          end
-        end
+      def attribute_config
+        sax_config.top_level_attributes
       end
 
       # Returns true if the element is configured to contain a value.
       def has_a_value?
-        !element_config_for_value.nil?
-      end
-
-      def attribute_config
-        sax_config.top_level_attributes
+        !sax_config.top_level_element_value.nil?
       end
 
       # Returns the SAXMachine::SaxConfig::ElementConfig instances that allow
       # for a single instance of another element.
-      # NOTE: We use the "has_one" and "has_many" terminoolgy for child elements
-      # because it seems to be the most readable option.
-      def element_config_has_one
+      def top_level_element_config
         sax_config.top_level_elements.reject do |_name, element_configs|
           element_configs.detect do |element_config|
             element_config.instance_variable_get(:@as) == :value
@@ -128,33 +96,18 @@ module PBCore
         end
       end
 
-      # Returns the SAXMachine::SaxConfig::ElementConfig instance for the
-      # element that represents the value (i.e. text that is one or more
-      # child elements). This is essentially the inverse of
-      # element_config_has_one.
-      def element_config_for_value
-        sax_config.top_level_elements.detect do |_name, element_configs|
-          element_configs.detect do |element_config|
-            element_config.instance_variable_get(:@as) == :value
-          end
-        end
-      end
-
       # Returns the SAXMachine::SaxConfig::ElementConfig that allow for
-      # multiple instances of other elements.
-      # NOTE: SAXMachine uses the term "collection" elements, but that's very
-      # confusing since PBCoreCollection is a thing, so we change it to the
-      # has_many terminology (and has_one for the singular element config for
-      # consistency).
-      def element_config_has_many
+      # multiple instances of other elements, i.e. "collection" elements which
+      # is not to be confused with <pbcoreCollection>.
+      def collection_element_config
         sax_config.collection_elements.reject do |element_config|
           element_config.instance_variable_get(:@as) == :value
         end
       end
 
-      def element_config_all
-        element_config_has_one.merge(element_config_has_many) do |name, config_has_one, config_has_many|
-          config_has_many.present? ? config_has_many : config_has_one
+      def all_element_config
+        top_level_element_config.merge(collection_element_config) do |name, top_level_element_cfg, coll_element_cfg|
+          coll_element_cfg.present? ? coll_element_cfg : top_level_element_cfg
         end
       end
 
@@ -173,6 +126,9 @@ module PBCore
       def has_sax_machine_top_level_element?(name, opts={})
         Array(sax_config.top_level_elements.fetch(name.to_s, nil)).any? do |element_config|
           opts.all? do |key, val|
+            # This is a quirk of SAXMachine: when you declare a top-level
+            # element with the .element class method, it takes your :class
+            # option and puts it into an instance var called @data_class.
             key = :data_class if key == :class
             val == element_config.instance_variable_get("@#{key}".to_sym)
           end
@@ -180,9 +136,9 @@ module PBCore
       end
 
       def has_sax_machine_collection_element?(name, opts={})
-        # NOTE: Accessing collection_element configs with squarey brackets has
-        # the unwanted side affect of creating an entry in the
-        # collection_elements, which we don't want. So we use #fetch here
+        # NOTE: Accessing #collection_elements with square brackets has the
+        # unwanted side affect of creating an entry in the collection_elements,
+        # which we don't want. So we use #fetch here
         Array(sax_config.collection_elements.fetch(name.to_s, nil)).any? do |element_config|
           opts.all? do |key, val|
             # This is a quirk of SAXMachine; for some reason it converts the

data/lib/pbcore/extension.rb

@@ -11,8 +11,17 @@ module PBCore
 
     build_xml do |xml|
       xml.pbcoreExtension(xml_attributes.compact) do |xml|
-        wrap.build(xml) if wrap
-        embedded.build(xml) if embedded
+        # <extensionWrap> and <extensionEmbedded> are mutually exclusive. Wrap
+        # takes precedence, so if you want to output <extensionEmbedded> make
+        # sure #wrap is set to nil.
+        # NOTE: Using #embedded will not produce round-trippable XML (i.e. XML
+        # that can be reparsed by the pbcore gem models.
+        # (See lib/pbcore/extension/embedded.rb)
+        if wrap
+          wrap.build(xml)
+        elsif embedded
+          embedded.build(xml)
+        end
       end
     end
   end

data/lib/pbcore/extension/embedded.rb

@@ -1,15 +1,22 @@
-# NOTE: This class doesn't actually work like you might expect it to.
-# The <extensionEmbedded> element is supposed to contain XML from a different
-# (non-PBCore) schema. However, currently the SAXMachine parser will proceed
-# to parse the embedded XML rather than capture it and provide an accessor to
-# it, which is what we want to happen.
+# NOTE: The <extensionEmbedded> element is supposed to contain XML from a
+# different (non-PBCore) schema. However, due to the declarative nature of
+# SAXMachine parsing, we need to know what we're parsing before we're parsing
+# it, so PBCore::Extension::Embedded cannot be used for parsing arbitrary
+# embedded XML. You can, however, still use the class to set some embedded
+# XML and output it with #to_xml. It just won't be re-parsable using this same
+# class. There might be a fix for this by overriding the .parse class method
+# but there's not enough demand for that work at this time. Until then, our
+# specs just do not include PBCore::Extension::Embedded in our test for
+# round-trippability.
 require 'pbcore/element'
 
 module PBCore
-  class Extension::Embedded < Element
+  class Extension::Embedded < ContentElement
     element :extensionEmbedded, as: :value
     build_xml do |xml|
-      xml.extensionEmbedded(value, xml_attributes.compact)
+      xml.extensionEmbedded('', xml_attributes.compact) do |xml|
+        xml << value
+      end
     end
   end
 end

data/lib/pbcore/factories.rb

@@ -1,6 +1,4 @@
 require 'factory_bot'
 
-GEM_ROOT = File.dirname(File.dirname(File.dirname(__FILE__)))
-
-require File.join(GEM_ROOT, 'spec', 'support', 'date_time_helpers')
-Dir.glob(File.join(GEM_ROOT, 'spec', 'factories', '**', '*.rb')).each { |file| require(file) }
+require File.join(PBCore::GEM_ROOT, 'spec', 'support', 'date_time_helpers.rb')
+Dir.glob(File.join(PBCore::GEM_ROOT, 'spec', 'factories', '**', '*.rb')).each { |file| require(file) }

data/lib/pbcore/genre.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Genre < Element
+  class Genre < ContentElement
     element :pbcoreGenre, as: :value
 
     build_xml do |xml|

data/lib/pbcore/identifier.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Identifier < Element
+  class Identifier < ContentElement
     element :pbcoreIdentifier, as: :value
 
     build_xml do |xml|

data/lib/pbcore/instantiation.rb

@@ -36,7 +36,7 @@ module PBCore
     element  :instantiationLocation, as: :location, class: PBCore::Instantiation::Location
     element  :instantiationMediaType, as: :media_type, class: PBCore::Instantiation::MediaType
     elements :instantiationGenerations, as: :generations, class: PBCore::Instantiation::Generations
-    elements :instantiationTimeStart, as: :time_starts, class: PBCore::Instantiation::TimeStart
+    element  :instantiationTimeStart, as: :time_start, class: PBCore::Instantiation::TimeStart
     element  :instantiationFileSize, as: :file_size, class: PBCore::Instantiation::FileSize
     element  :instantiationDuration, as: :duration, class: PBCore::Instantiation::Duration
     element  :instantiationDataRate, as: :data_rate, class: PBCore::Instantiation::DataRate
@@ -65,7 +65,7 @@ module PBCore
         media_type.build(xml) if media_type
         generations.each { |generations_element| generations_element.build(xml) }
         file_size.build(xml) if file_size
-        time_starts.each { |time_start| time_start.build(xml) }
+        time_start.build(xml) if time_start
         duration.build(xml) if duration
         data_rate.build(xml) if data_rate
         colors.build(xml) if colors

data/lib/pbcore/instantiation/alternative_modes.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Instantiation::AlternativeModes < Element
+  class Instantiation::AlternativeModes < ContentElement
     element :instantiationAlternativeModes, as: :value
 
     build_xml do |xml|

data/lib/pbcore/instantiation/annotation.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Instantiation::Annotation < Element
+  class Instantiation::Annotation < ContentElement
     element :instantiationAnnotation, as: :value
     attribute :annotationType, as: :type
 

data/lib/pbcore/instantiation/channel_configuration.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Instantiation::ChannelConfiguration < Element
+  class Instantiation::ChannelConfiguration < ContentElement
     element :instantiationChannelConfiguration, as: :value
 
     build_xml do |xml|

data/lib/pbcore/instantiation/colors.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Instantiation::Colors < Element
+  class Instantiation::Colors < ContentElement
     element :instantiationColors, as: :value
 
     build_xml do |xml|

data/lib/pbcore/instantiation/data_rate.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Instantiation::DataRate < Element
+  class Instantiation::DataRate < ContentElement
     element :instantiationDataRate, as: :value
 
     attribute :unitsOfMeasure, as: :units_of_measure

data/lib/pbcore/instantiation/date.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Instantiation::Date < Element
+  class Instantiation::Date < ContentElement
     element :instantiationDate, as: :value
 
     attribute :dateType, as: :type

data/lib/pbcore/instantiation/digital.rb

@@ -1,7 +1,7 @@
 require 'pbcore/element'
 
 module PBCore
-  class Instantiation::Digital < Element
+  class Instantiation::Digital < ContentElement
     element :instantiationDigital, as: :value
 
     build_xml do |xml|