pbcore 0.2.0

data/README.md

@@ -0,0 +1,37 @@
+# PBCore
+
+PBCore model for Ruby applications.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pbcore'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pbcore
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/pbcore.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "pbcore"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require "pry"
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/pbcore.rb

@@ -0,0 +1,28 @@
+require "pbcore/version"
+require "pbcore/errors"
+
+module PBCore
+  autoload :Element,                  'pbcore/element'
+  autoload :Attributes,               'pbcore/attributes'
+  autoload :DescriptionDocument,      'pbcore/description_document'
+  autoload :AssetType,                'pbcore/asset_type'
+  autoload :AssetDate,                'pbcore/asset_date'
+  autoload :Identifier,               'pbcore/identifier'
+  autoload :Title,                    'pbcore/title'
+  autoload :Subject,                  'pbcore/subject'
+  autoload :Description,              'pbcore/description'
+  autoload :Genre,                    'pbcore/genre'
+  autoload :Creator,                  'pbcore/creator'
+  autoload :Coverage,                 'pbcore/coverage'
+  autoload :Relation,                 'pbcore/relation'
+  autoload :AudienceLevel,            'pbcore/audience_level'
+  autoload :AudienceRating,           'pbcore/audience_rating'
+  autoload :Contributor,              'pbcore/contributor'
+  autoload :Publisher,                'pbcore/publisher'
+  autoload :RightsSummary,            'pbcore/rights_summary'
+  autoload :Annotation,               'pbcore/annotation'
+  autoload :Extension,                'pbcore/extension'
+  autoload :Instantiation,            'pbcore/instantiation'
+  autoload :InstantiationDocument,    'pbcore/instantiation_document'
+  autoload :Vocab,                    'pbcore/vocab'
+end

data/lib/pbcore/annotation.rb

@@ -0,0 +1,12 @@
+require 'pbcore/element'
+
+module PBCore
+  class Annotation < Element
+    element :pbcoreAnnotation, as: :value
+    attribute :annotationType, as: :type
+
+    build_xml do |xml|
+      xml.pbcoreAnnotation(value, xml_attributes.compact)
+    end
+  end
+end

data/lib/pbcore/asset_date.rb

@@ -0,0 +1,12 @@
+require 'pbcore/element'
+
+module PBCore
+  class AssetDate < Element
+    element :pbcoreAssetDate, as: :value
+    attribute :dateType, as: :type
+
+    build_xml do |xml|
+      xml.pbcoreAssetDate(value, xml_attributes.compact)
+    end
+  end
+end

data/lib/pbcore/asset_type.rb

@@ -0,0 +1,11 @@
+require 'pbcore/element'
+
+module PBCore
+  class AssetType < Element
+    element :pbcoreAssetType, as: :value
+
+    build_xml do |xml|
+      xml.pbcoreAssetType(value, xml_attributes.compact)
+    end
+  end
+end

data/lib/pbcore/attributes.rb

@@ -0,0 +1,6 @@
+module PBCore
+  module Attributes
+    autoload :Common,       'pbcore/attributes/common'
+    autoload :TimeInterval, 'pbcore/attributes/time_interval'
+  end
+end

data/lib/pbcore/attributes/common.rb

@@ -0,0 +1,13 @@
+module PBCore
+  module Attributes
+    module Common
+      def self.included(base)
+        PBCore.fail_if_base_is_not_pbcore_element(included_module: self, base: base)
+        base.attribute :source
+        base.attribute :ref
+        base.attribute :annotation
+        base.attribute :version
+      end
+    end
+  end
+end

data/lib/pbcore/attributes/time_interval.rb

@@ -0,0 +1,12 @@
+module PBCore
+  module Attributes
+    module TimeInterval
+      def self.included(base)
+        PBCore.fail_if_base_is_not_pbcore_element(included_module: self, base: base)
+        base.attribute :startTime, as: :start_time
+        base.attribute :endTime, as: :end_time
+        base.attribute :timeAnnotation, as: :time_annotation
+      end
+    end
+  end
+end

data/lib/pbcore/audience_level.rb

@@ -0,0 +1,11 @@
+require 'pbcore/element'
+
+module PBCore
+  class AudienceLevel < Element
+    element :pbcoreAudienceLevel, as: :value
+
+    build_xml do |xml|
+      xml.pbcoreAudienceLevel(value, xml_attributes.compact)
+    end
+  end
+end

data/lib/pbcore/audience_rating.rb

@@ -0,0 +1,11 @@
+require 'pbcore/element'
+
+module PBCore
+  class AudienceRating < Element
+    element :pbcoreAudienceRating, as: :value
+
+    build_xml do |xml|
+      xml.pbcoreAudienceRating(value, xml_attributes.compact)
+    end
+  end
+end

data/lib/pbcore/contributor.rb

@@ -0,0 +1,19 @@
+require 'pbcore/element'
+
+module PBCore
+  class Contributor < Element
+    autoload :Contributor,      'pbcore/contributor/contributor'
+    autoload :Role,             'pbcore/contributor/role'
+
+    element :pbcoreContributor, as: :value
+    element :contributor, as: :contributor, class: PBCore::Contributor::Contributor
+    element :contributorRole, as: :role, class: PBCore::Contributor::Role
+
+    build_xml do |xml|
+      xml.pbcoreContributor(xml_attributes.compact) do |xml|
+        contributor.build(xml) if contributor
+        role.build(xml) if role
+      end
+    end
+  end
+end

data/lib/pbcore/contributor/contributor.rb

@@ -0,0 +1,12 @@
+require 'pbcore/element'
+
+module PBCore
+  class Contributor::Contributor < Element
+    element :contributor, as: :value
+    attribute :affiliation, as: :affiliation
+
+    build_xml do |xml|
+      xml.contributor(value, xml_attributes.compact)
+    end
+  end
+end

data/lib/pbcore/contributor/role.rb

@@ -0,0 +1,12 @@
+require 'pbcore/element'
+
+module PBCore
+  class Contributor::Role < Element
+    element :contributorRole, as: :value
+    attribute :portrayal, as: :portrayal
+
+    build_xml do |xml|
+      xml.contributorRole(value, xml_attributes.compact)
+    end
+  end
+end

data/lib/pbcore/coverage.rb

@@ -0,0 +1,20 @@
+require 'pbcore/element'
+
+module PBCore
+  class Coverage < Element
+
+    autoload :Coverage,   'pbcore/coverage/coverage'
+    autoload :Type,       'pbcore/coverage/type'
+
+    element :pbcoreCoverage, as: :value
+    element :coverage, as: :coverage, class: PBCore::Coverage::Coverage
+    element :coverageType, as: :type, class: PBCore::Coverage::Type
+
+    build_xml do |xml|
+      xml.pbcoreCoverage(xml_attributes.compact) do |xml|
+        coverage.build(xml) if coverage
+        type.build(xml) if type
+      end
+    end
+  end
+end

data/lib/pbcore/coverage/coverage.rb

@@ -0,0 +1,11 @@
+require 'pbcore/element'
+
+module PBCore
+  class Coverage::Coverage < Element
+    element :coverage, as: :value
+
+    build_xml do |xml|
+      xml.coverage(value, xml_attributes.compact)
+    end
+  end
+end

data/lib/pbcore/coverage/type.rb

@@ -0,0 +1,11 @@
+require 'pbcore/element'
+
+module PBCore
+  class Coverage::Type < Element
+    element :coverageType, as: :value
+
+    build_xml do |xml|
+      xml.coverageType(value, xml_attributes.compact)
+    end
+  end
+end

data/lib/pbcore/creator.rb

@@ -0,0 +1,19 @@
+require 'pbcore/element'
+
+module PBCore
+  class Creator < Element
+    autoload :Creator,      'pbcore/creator/creator'
+    autoload :Role,         'pbcore/creator/role'
+
+    element :pbcoreCreator, as: :value
+    element :creator, as: :creator, class: PBCore::Creator::Creator
+    element :creatorRole, as: :role, class: PBCore::Creator::Role
+
+    build_xml do |xml|
+      xml.pbcoreCreator(xml_attributes.compact) do |xml|
+        creator.build(xml) if creator
+        role.build(xml) if role
+      end
+    end
+  end
+end

data/lib/pbcore/creator/creator.rb

@@ -0,0 +1,16 @@
+require 'pbcore/element'
+
+module PBCore
+  class Creator::Creator < Element
+    element :creator, as: :value
+    attribute :affiliation, as: :affiliation
+    attribute :affiliationSource, as: :affiliation_source
+    attribute :affiliationRef, as: :affiliation_ref
+    attribute :affiliationVersion, as: :affiliation_version
+    attribute :affiliationAnnotation, as: :affiliation_annotation
+
+    build_xml do |xml|
+      xml.creator(value, xml_attributes.compact)
+    end
+  end
+end

data/lib/pbcore/creator/role.rb

@@ -0,0 +1,11 @@
+require 'pbcore/element'
+
+module PBCore
+  class Creator::Role < Element
+    element :creatorRole, as: :value
+
+    build_xml do |xml|
+      xml.creatorRole(value, xml_attributes.compact)
+    end
+  end
+end

data/lib/pbcore/description.rb

@@ -0,0 +1,13 @@
+require 'pbcore/element'
+
+module PBCore
+  class Description < Element
+    element :pbcoreDescription, as: :value
+    attribute :descriptionType, as: :type
+    attribute :descriptionTypeRef, as: :type_ref
+
+    build_xml do |xml|
+      xml.pbcoreDescription(value, xml_attributes.compact)
+    end
+  end
+end

data/lib/pbcore/description_document.rb

@@ -0,0 +1,60 @@
+require 'pbcore/element'
+
+module PBCore
+  class DescriptionDocument < Element
+    elements :pbcoreIdentifier, as: :identifiers, class: PBCore::Identifier
+    elements :pbcoreTitle, as: :titles, class: PBCore::Title
+    elements :pbcoreDescription, as: :descriptions, class: PBCore::Description
+    elements :pbcoreAssetDate, as: :asset_dates, class: PBCore::AssetDate
+    elements :pbcoreAssetType, as: :asset_types, class: PBCore::AssetType
+    elements :pbcoreSubject, as: :subjects, class: PBCore::Subject
+    elements :pbcoreGenre, as: :genres, class: PBCore::Genre
+    elements :pbcoreRelation, as: :relations, class: PBCore::Relation
+    elements :pbcoreCoverage, as: :coverages, class: PBCore::Coverage
+    elements :pbcoreAudienceLevel, as: :audience_levels, class: PBCore::AudienceLevel
+    elements :pbcoreAudienceRating, as: :audience_ratings, class: PBCore::AudienceRating
+    elements :pbcoreCreator, as: :creators, class: PBCore::Creator
+    elements :pbcoreContributor, as: :contributors, class: PBCore::Contributor
+    elements :pbcorePublisher, as: :publishers, class: PBCore::Publisher
+    elements :pbcoreRightsSummary, as: :rights_summaries, class: PBCore::RightsSummary
+    elements :pbcoreAnnotation, as: :annotations, class: PBCore::Annotation
+    elements :pbcoreExtension, as: :extensions, class: PBCore::Extension
+    elements :pbcoreInstantiation, as: :instantiations, class: PBCore::Instantiation
+
+    build_xml do |xml|
+      xml.pbcoreDescriptionDocument(namespace_attributes) do |xml|
+        asset_types.each { |asset_type| asset_type.build(xml) }
+        asset_dates.each { |asset_date| asset_date.build(xml) }
+        identifiers.each { |identifier| identifier.build(xml) }
+        titles.each { |title| title.build(xml) }
+        subjects.each { |subject| subject.build(xml) }
+        descriptions.each { |description| description.build(xml) }
+        genres.each { |genre| genre.build(xml) }
+        relations.each { |relation| relation.build(xml) }
+        coverages.each { |coverage| coverage.build(xml) }
+        audience_levels.each { |audience_level| audience_level.build(xml) }
+        audience_ratings.each { |audience_rating| audience_rating.build(xml) }
+        creators.each { |creator| creator.build(xml) }
+        contributors.each { |contributor| contributor.build(xml) }
+        publishers.each { |publisher| publisher.build(xml) }
+        rights_summaries.each { |rights_summary| rights_summary.build(xml) }
+        instantiations.each { |instantiation| instantiation.build(xml) }
+        annotations.each { |annotation| annotation.build(xml) }
+        # TODO: no pbcore part?!
+        extensions.each { |extension| extension.build(xml) }
+      end
+    end
+
+    # NOTE: For some reason, these attributes will not parse with SAXMachine
+    # attributes.
+    # TODO: Is there a better way to set namespace attributes?
+    def namespace_attributes
+      {
+        # changed to www.pbcore because aapb doesnt like it without
+        'xmlns' => "http://www.pbcore.org/PBCore/PBCoreNamespace.html",
+        'xmlns:xsi' => "http://www.w3.org/2001/XMLSchema-instance",
+        'xsi:schemaLocation' => "http://www.pbcore.org/PBCore/PBCoreNamespace.html http://www.pbcore.org/xsd/pbcore-2.1.xsd"
+      }
+    end
+  end
+end

data/lib/pbcore/element.rb

@@ -0,0 +1,199 @@
+require 'sax-machine'
+
+module SAXMachine::SAXAbstractHandler
+  NO_BUFFER = ''
+end
+
+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.
+    value(:value, {}) do |val|
+      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|
+        # 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
+        # get the accessor name by which to get the value
+        accessor = element_config.instance_variable_get(:@as)
+
+        # fetch the value by calling the accessor
+        value = send(accessor)
+        # create the key, value pair that will go into the Hash[] construct.
+        key = key_by_xml_name ? name : accessor
+        [ key,  value ]
+      end
+
+      Hash[ key_value_pairs_array ]
+    end
+
+    # Shortcut for getting xml attributes.
+    def xml_attributes; attributes(key_by_xml_name: true); end
+
+    # Returns a hash of attrubutes as the should appear in the XML.
+    def attributes(key_by_xml_name: false)
+      xml_attrs = Hash[
+        self.class.sax_config.top_level_attributes.map do |attr|
+          accessor = attr.instance_variable_get(:@as)
+          key = key_by_xml_name ? attr.name : accessor
+          [ key, send(accessor) ]
+        end
+      ]
+      xml_attrs
+    end
+
+    # Executes the block defined with the class method `build_xml`. Uses a
+    # Nokogiri::XML::Builder instance (either passed in or instantiated) to
+    # build the XML, and then returns the builder instance.
+    def build(builder=nil)
+      raise ArgumentError, "#{self.class}#build expects a Nokogiri::XML::Builder class, but #{builder.class} was given" unless builder.nil? || builder.is_a?(Nokogiri::XML::Builder)
+      PBCore.fail_if_missing_build_xml_block(element_class: self.class)
+      builder ||= Nokogiri::XML::Builder.new
+      instance_exec builder, &self.class.build_block
+      builder
+    end
+
+    # Builds the xml using #build with a new instance of Nokogiri::XML::Builder
+    # and immediately calls to_xml on it.
+    def to_xml
+      build.to_xml
+    end
+
+    # Define the class interfaces for all PBCore elements.
+    class << self
+      attr_reader :build_block
+
+      # Class method to allow extended classes to declaratively the logic used
+      # to build XML using Nokogiri::XML::Builder.
+      def build_xml(&block)
+        raise ArgumentError, "#{self.class}.build_xml requires a block with one parameter" unless block_given? && block.arity == 1
+        @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
+      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
+      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
+        sax_config.top_level_elements.reject 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 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
+        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
+        end
+      end
+
+      def has_sax_machine_attribute?(name, opts={})
+        sax_config.top_level_attributes.any? do |attr_config|
+          opts.all? do |key, val|
+            val == attr_config.instance_variable_get("@#{key}".to_sym)
+          end
+        end
+      end
+
+      def has_sax_machine_value_element?
+        !sax_config.top_level_element_value.empty?
+      end
+
+      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|
+            key = :data_class if key == :class
+            val == element_config.instance_variable_get("@#{key}".to_sym)
+          end
+        end
+      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
+        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
+            # config option :as to a string when assigning it to the
+            # ConfigElement instance, so we need to convert opts[:as] param to
+            # string in order to compare them accurately.
+            val = val.to_s if key == :as
+            val == element_config.instance_variable_get(:"@#{key}")
+          end
+        end
+      end
+    end
+  end
+end