fasttrack 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4dc5f004ecff917644512a6ed9c218ab813f301c
+  data.tar.gz: 20705b32a6e116f5582f18f03c5f8335c2939b16
+SHA512:
+  metadata.gz: 948a92e633033f52356023a57b7c711e7a29d1bc466197265624be23ba51448ebf1474eca92a6711ac5b9505efbce22a1b6f6014189943d8a57864ed4f3e2aad
+  data.tar.gz: 64f802661ea14141431cad5a4020111f8f888336cd0c86547a7f6e7707e84608dd0543375ee39ab327d6024f0d1235bdae963dc7bc3b6021565b770b725b0d1d

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in fasttrack.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Misty De Meo
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,51 @@
+# Fasttrack
+
+Fasttrack is a rubylike object-oriented interface around the [Exempi](http://libopenraw.freedesktop.org/wiki/Exempi) C library. It provides an easy way to read, write and modify embedded XMP metadata from arbitrary files.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'fasttrack'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install fasttrack
+
+## Usage
+
+Opening a file:
+
+```ruby
+file = Fasttrack::File.new 'path' # add the 'w' parameter if you want to write
+```
+
+Editing the file's XMP:
+
+```ruby
+file.xmp.set :tiff, 'Make', 'Samsung'
+# or, more prettily
+file.xmp['tiff:Make'] = 'Samsung'
+```
+
+Iterate over the properties in a file:
+
+```ruby
+props = file.xmp.map {|p| p[1]}
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+3-clause BSD, identical to the license used by Exempi and Adobe XMP Toolkit. For the license text, see LICENSE.

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*_test.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/fasttrack.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/fasttrack/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Misty De Meo"]
+  gem.email         = ["mistydemeo@gmail.com"]
+  gem.description   = <<-EOS
+                      Fasttrack is an easy-to-use Ruby wrapper for
+                      Exempi, a C library for managing XMP metadata.
+                      Fasttrack provides a dead-easy, object-oriented
+                      interface to Exempi's functions.
+                      EOS
+  gem.summary       = %q{Ruby sugar for Exempi}
+  gem.homepage      = "https://github.com/mistydemeo/fasttrack"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "fasttrack"
+  gem.require_paths = ["lib"]
+  gem.version       = Fasttrack::VERSION
+
+  gem.add_dependency 'exempi', '>= 0.1'
+
+  gem.add_development_dependency 'rake', '>= 0.9.2.2'
+  gem.add_development_dependency 'mocha', '>= 0.13.0'
+  gem.add_development_dependency 'nokogiri', '>= 1.5.5'
+end

data/lib/fasttrack.rb

@@ -0,0 +1,18 @@
+require 'fasttrack/exceptions'
+require 'fasttrack/file'
+require 'fasttrack/xmp'
+require 'fasttrack/version'
+
+require 'exempi/exceptions'
+
+module Fasttrack
+  # Checks for an Exempi error, and raises the appropriate exception.
+  # Should only be used when an error has been detected from the boolean
+  # output of one of Exempi's functions.
+  # @raise [Exempi::ExempiError]
+  def self.handle_exempi_failure
+    error_code = Exempi.xmp_get_error
+    message = Exempi.exception_for error_code
+    raise Exempi::ExempiError.new(error_code), "Exempi failed with the code #{message}"
+  end
+end

data/lib/fasttrack/exceptions.rb

@@ -0,0 +1,5 @@
+module Fasttrack
+  class FileFormatError < StandardError; end
+  class OpenError < StandardError; end
+  class WriteError < StandardError; end
+end

data/lib/fasttrack/file.rb

@@ -0,0 +1,167 @@
+# -*- coding: UTF-8 -*- 
+require 'fasttrack/exceptions'
+require 'fasttrack/xmp'
+
+require 'exempi'
+require 'ffi'
+require 'pathname'
+
+module Fasttrack
+  class File
+    # The Exempi C pointer for this object. You normally shouldn't need
+    # to access this, but it is exposed so that unwrapped Exempi
+    # functions can be called on Fasttrack-tracked objects.
+    # @return [FFI::Pointer]
+    attr_reader :file_ptr
+
+    # The Fasttrack::XMP object associated with this file. You can
+    # replace it with another Fasttrack::XMP object.
+    # @example Replace an object's XMP with the XMP from another file
+    #   file1.xmp = file2.xmp
+    #   file1.save!
+    # @example Create a new XMP document and save it into a file
+    #   newxmp = Fasttrack::XMP.new
+    #   newxmp['tiff:Make'] = 'Sony'
+    #   file.xmp = newxmp
+    #   file.save!
+    # @example Create a new XMP document manually, then add it to a File object
+    #   ptr = Exempi.xmp_new_empty
+    #   Exempi.xmp_set_property Fasttrack::NAMESPACES[:tiff],
+    #     'tiff:Make', 'Sony', nil
+    #   file.xmp = ptr
+    # @return [Fasttrack::XMP]
+    attr_reader :xmp
+
+    # @return [Pathname]
+    attr_reader :path
+
+    def self.finalize pointer
+      proc { Exempi.xmp_files_free pointer }
+    end
+
+    # Instantiates a new Fasttrack::File object, which is a
+    # representation of a file on disk and its associated XMP metadata.
+    # To create a new file on disk you should use Fasttrack::XMP#to_s
+    # instead.
+    # @param [String] path path to the file on disk; must exist
+    # @param [String] mode file mode; accepted values are "r"
+    #   (read-only; default), "w" and "rw" (read-write)
+    # @raise [Fasttrack::FileFormatError] if the file can't have XMP
+    #   metadata
+    def initialize path, mode="r"
+      @path = Pathname.new(path).expand_path
+      if not @path.exist?
+        raise Errno::ENOENT, "#{@path} does not exist"
+      end
+
+      @file_ptr = Exempi.xmp_files_new
+      @read_mode = mode
+      open @read_mode
+
+      ObjectSpace.define_finalizer(self, self.class.finalize(@file_ptr))
+    end
+
+    # Checks to see whether XMP can be written to the current file.
+    # If no XMP is specified, the file's associated XMP is used.
+    # 
+    # @param [FFI::Pointer, Fasttrack::XMP] xmp XMP to check; can be a
+    #   Fasttrack::XMP object or a pointer to a C XMP object
+    # @return [true,false]
+    # @raise [TypeError] if an object without an XMP pointer is passed
+    def can_put_xmp? xmp=@xmp
+      if xmp.is_a? Fasttrack::XMP
+        xmp = xmp.xmp_ptr
+      end
+
+      raise TypeError, "#{xmp} is not a pointer" unless xmp.is_a? FFI::Pointer
+
+      Exempi.xmp_files_can_put_xmp @file_ptr, xmp
+    end
+
+    # Replaces the file's currently associated XMP object. The new XMP
+    # will not be written to disk until #save! or #close! is called.
+    # @param [Fasttrack::XMP, FFI::Pointer] xmp XMP object to copy. Must
+    #   be a Fasttrack::XMP object or an XMP pointer.
+    # @return [Fasttrack::XMP, FFI::Pointer] the copied object.
+    # @raise [Fasttrack::WriteError] if the file can't be written to
+    def xmp= new_xmp
+      if new_xmp.is_a? FFI::Pointer
+        new_xmp = Fasttrack::XMP.new new_xmp
+      end
+      if not can_put_xmp? new_xmp
+        message = "Unable to write XMP"
+        message << "; file opened read-only" if @read_mode == "r"
+        raise Fasttrack::WriteError, message
+      end
+
+      @xmp = new_xmp.dup
+      Exempi.xmp_files_put_xmp @file_ptr, @xmp.xmp_ptr
+    end
+
+    # Save changes to a file.
+    # Exempi only saves changes when a file is closed; this method
+    # closes and then reopens the file so it can continue to be used.
+    # This always uses Exempi's "safe close", which writes into a
+    # temporary file and swap in case of unexpected termination.
+    # @return [Boolean] true if successful
+    # @raise [Fasttrack::WriteError] if the file is read-only or closed
+    def save!
+      if @read_mode == "r"
+        raise Fasttrack::WriteError, "file opened read-only"
+      end
+
+      raise Fasttrack::WriteError, "file is closed" unless @open
+      # Make sure we let Exempi know there's new XMP to write
+      Exempi.xmp_files_put_xmp @file_ptr, @xmp.xmp_ptr
+      close!
+      open @read_mode
+    end
+
+    # Closes the current file and frees its memory.
+    # While this will not save changes made to the current
+    # XMP object, it still has the potential to make changes to
+    # the file being closed.
+    # @return [Boolean] true if successful
+    # @raise [Fasttrack::WriteError] if the file is already closed
+    def close!
+      raise Fasttrack::WriteError, "file is already closed" unless @open
+
+      @open = !Exempi.xmp_files_close(@file_ptr, :XMP_CLOSE_SAFEUPDATE)
+      if @open # did not successfully close
+        Fasttrack.handle_exempi_failure
+      else
+        true
+      end
+    end
+
+    # Reopens a closed Fasttrack::File object.
+    #
+    # @param [String] mode file mode
+    # @raise [Exempi::ExempiError] if Exempi reports an error while
+    #   attempting to open the file
+    # @raise [Fasttrack::OpenError] if an opened file is reopened
+    def open mode=@read_mode
+      raise Fasttrack::OpenError, "file is already open" if @open
+
+      case mode
+      when 'r'
+        open_option = :XMP_OPEN_READ
+      when 'w', 'rw'
+        open_option = :XMP_OPEN_FORUPDATE
+      else
+        open_option = :XMP_OPEN_NOOPTION
+      end
+
+      @open = Exempi.xmp_files_open @file_ptr, @path.to_s, open_option
+
+      if not @open
+        Fasttrack.handle_exempi_failure
+      else
+        @xmp = Fasttrack::XMP.from_file_pointer @file_ptr
+      end
+
+      @open
+    end
+
+  end
+end

data/lib/fasttrack/namespaces.rb

@@ -0,0 +1,12 @@
+require 'exempi/namespaces'
+
+module Fasttrack
+  # Populated at runtime with the namespace values from
+  # Exempi::Namespaces
+  NAMESPACES = {}
+  Exempi::Namespaces.constants.each do |const|
+    name = const.to_s.match(/XMP_NS_(.+)/)[1].downcase.to_sym
+    uri = Exempi::Namespaces.const_get const
+    NAMESPACES[name] = uri
+  end
+end

data/lib/fasttrack/version.rb

@@ -0,0 +1,3 @@
+module Fasttrack
+  VERSION = "0.1"
+end

data/lib/fasttrack/xmp.rb

@@ -0,0 +1,362 @@
+# -*- coding: UTF-8 -*-
+require 'fasttrack/namespaces'
+
+require 'exempi'
+require 'ffi'
+
+module Fasttrack
+  class XMP
+    # The Exempi C pointer for this object. You normally shouldn't need
+    # to access this, but it is exposed so that unwrapped Exempi
+    # functions can be called on Fasttrack-tracked objects.
+    # @return [FFI::Pointer]
+    attr_accessor :xmp_ptr
+
+    include Enumerable
+
+    def self.finalize pointer
+      proc { Exempi.xmp_free pointer }
+    end
+
+    def self.finalize_iterator pointer
+      proc { Exempi.xmp_iterator_free pointer }
+    end
+
+    # Creates a new XMP object.
+    # If a pointer to an XMP chunk is provided, a copy of it will be used;
+    # otherwise, a new empty XMP chunk will be created.
+    #
+    # Note that if you create an XMP object from a pre-existing pointer,
+    # you'll need to remember to free the original pointer with
+    # xmp_free(). Garbage collection will only free the
+    # Fasttrack::XMP version for you.
+    # @param [FFI::Pointer, nil] xmp_ptr XMP pointer to use, or nil
+    def initialize xmp_ptr=nil
+      if xmp_ptr and xmp_ptr.is_a? FFI::Pointer
+        @xmp_ptr = Exempi.xmp_copy xmp_ptr
+      else
+        @xmp_ptr = Exempi.xmp_new_empty
+      end
+
+      @iterator = nil
+      @iterator_opts = nil
+
+      # capture the namespaces that exist at load time, with
+      # a count of the number of times each uri is present
+      ns_ary = map {|ns,_,_,_| ns}
+      @namespaces = ns_ary.uniq.each_with_object(Hash.new(0)) do |ns, hsh|
+        hsh[ns] = ns_ary.count(ns) - 1 # one empty item returned per ns
+      end
+
+      ObjectSpace.define_finalizer(self, self.class.finalize(@xmp_ptr))
+    end
+
+    # Creates a new XMP object based on the metadata in a file
+    # represented by an Exempi file pointer. The file must already have
+    # been opened using xmp_files_open()
+    # @param [FFI::Pointer] file_ptr an Exempi pointer
+    # @return [Fasttrack::XMP] a new XMP object
+    def self.from_file_pointer file_ptr
+      xmp_ptr = Exempi.xmp_files_get_new_xmp file_ptr
+      xmp = Fasttrack::XMP.new xmp_ptr
+      Exempi.xmp_free xmp_ptr
+
+      xmp
+    end
+
+    # Creates a new XMP object from an XML string.
+    # @param [String] xml a string containing valid XMP
+    # @return [Fasttrack::XMP] a new XMP object
+    def self.parse xml
+      ptr = Exempi.xmp_new xml, xml.bytesize
+      xmp = Fasttrack::XMP.new ptr
+      Exempi.xmp_free ptr
+
+      xmp
+    end
+
+    # This ensures that the clone is created with a new XMP pointer.
+    def initialize_copy orig
+      super
+      @xmp_ptr = Exempi.xmp_copy @xmp_ptr
+
+      # if we don't do this, the new clone's finalizer will reference
+      # the pointer from the original object - not the clone's
+      ObjectSpace.undefine_finalizer self
+      ObjectSpace.define_finalizer(self, self.class.finalize(@xmp_ptr))
+    end
+
+    # Return an object from the global namespace.
+    # @example Gets the value of the 'tiff:Make' property
+    #   xmp.get :tiff, 'tiff:Make' #=> 'Sony'
+    #   # you can also leave off the namespace prefix
+    #   xmp.get :tiff, 'Make' #=> 'Sony'
+    #   # You can use the namespace URI string too
+    #   xmp.get 'http://ns.adobe.com/tiff/1.0/', 'Make' #=> 'Sony'
+    # @param [String, Symbol] namespace namespace URI to use. If a
+    #   symbol is provided, Fasttrack will look up the URI from a set of
+    #   common recognized namespaces.
+    # @param [String] prop property to look up.
+    # @return [String, nil] the value of the requested property, or nil
+    #   if not found.
+    def get namespace, prop
+      if namespace.is_a? Symbol
+        namespace = namespace_for namespace
+      end
+
+      prop_str = Exempi.xmp_string_new
+      success = Exempi.xmp_get_property @xmp_ptr, namespace, prop, prop_str, nil
+      if success
+        result = Exempi.xmp_string_cstr prop_str
+
+        result
+      else
+        result = nil
+      end
+
+      Exempi.xmp_string_free prop_str
+
+      result
+    end
+
+    alias_method :get_property, :get
+
+    # Modifies an existing XMP property or creates a new property with
+    # the specified value.
+    # @example Sets the 'tiff:Make' property to 'Sony'
+    #   xmp.set :tiff, 'tiff:Make', 'Sony' #=> 'Sony'
+    # @param [String, Symbol] namespace namespace to use. If a symbol is
+    #   provided, Fasttrack will look up from a set of common recognized
+    #   namespaces.
+    # @param [String] prop property to set.
+    # @param [String] value value to set.
+    # @return [String] the new value
+    # @raise [Exempi::ExempiError] if Exempi reports that it failed
+    def set namespace, prop, value
+      if namespace.is_a? Symbol
+        namespace = namespace_for namespace
+      end
+
+      success = Exempi.xmp_set_property @xmp_ptr, namespace, prop, value, nil
+      if success
+        @namespaces[namespace] += 1
+        value
+      else
+        Fasttrack.handle_exempi_failure
+      end
+    end
+
+    alias_method :set_property, :set
+
+    # Fetches an XMP property given a string containing the namespace
+    # prefix and the property name, e.g. "tiff:Make".
+    # @example Returns the value of 'tiff:Make'
+    #   xmp['tiff:Make'] #=> 'Sony'
+    # @param [String] query query
+    # @return [String, nil] the property's value, or nil if not found
+    def [] query
+      if query =~ /.+:.+/
+        ns_prefix, property = query.scan(/(.+):(.+)/).flatten
+      end
+
+      ns_uri = namespace_for ns_prefix.downcase.to_sym
+
+      get_property ns_uri, property
+    end
+
+    # Sets an XMP property given a string containing the namespace
+    # prefix and the property name, e.g. "tiff:Make".
+    # @example Sets the value of 'tiff:Make' to 'Sony'
+    #   xmp['tiff:Make'] = 'Sony' #=> 'Sony'
+    # @param [String] property property
+    # @param [String] value value to set
+    # @return [String] the new value
+    def []= property, value
+      if property =~ /.+:.+/
+        ns_prefix, property = property.scan(/(.+):(.+)/).flatten
+      end
+
+      ns_uri = namespace_for ns_prefix.downcase.to_sym
+
+      set_property ns_uri, property, value
+    end
+
+    # Deletes a given XMP property. If the property exists returns the
+    # deleted property, otherwise returns nil.
+    # @param (see #get_property)
+    # @return [String, nil] the value of the deleted property, or nil if
+    #   not found.
+    def delete namespace, prop
+      if namespace.is_a? Symbol
+        namespace = namespace_for namespace
+      end
+
+      deleted_prop = get_property namespace, prop
+      Exempi.xmp_delete_property @xmp_ptr, namespace, prop
+      @namespaces[namespace] -= 1 unless deleted_prop.nil?
+
+      deleted_prop
+    end
+
+    alias_method :delete_property, :delete
+
+    # Returns a list of namespace URIs in use in the specified XMP data.
+    # @return [Array<String>] an array of URI strings
+    def namespaces
+      @namespaces.keys
+    end
+
+    # Serializes the XMP object to an XML string.
+    # @return [String]
+    def serialize
+      xmp_str = Exempi.xmp_string_new
+      Exempi.xmp_serialize @xmp_ptr, xmp_str, 0, 0
+      string = Exempi.xmp_string_cstr xmp_str
+      Exempi.xmp_string_free xmp_str
+
+      string
+    end
+
+    def == other_xmp
+      serialize == other_xmp.serialize
+    end
+
+    # @yieldparam (see #iterate_for)
+    def each &block
+      return to_enum unless block_given?
+
+      iterate_for do |returned|
+        block.call(returned)
+      end
+    end
+
+    # Iterates over all properties, with the iteration rules guided
+    # by the specified options. Options should be specified in an array.
+    # @param [Array<Symbol>] opts array of one or more options
+    # @option opts :properties Iterate the property tree of a TXMPMeta
+    #   object.
+    # @option opts :aliases Iterate the global namespace table.
+    # @option opts :just_children Just do the immediate children of the
+    #   root, default is subtree.
+    # @option opts :just_leaf_nodes Just do the leaf nodes, default is
+    #   all nodes in the subtree.
+    # @option opts :just_leaf_name Return just the leaf part of the
+    #   path, default is the full path.
+    # @option opts :include_aliases Include aliases, default is just
+    #   actual properties.
+    # @option opts :omit_qualifiers Omit all qualifiers.
+    # @yieldparam (see #iterate_for)
+    # @return [Enumerator] if no block is given
+    def each_with_options opts, &block
+      return enum_for(:each_with_options, opts) unless block_given?
+
+      options = opts.map {|o| ("XMP_ITER_"+o.to_s.delete("_")).to_sym}
+      # filter out invalid options
+      options.keep_if {|o| Exempi::XMP_ITER_OPTIONS.find o}
+
+      iterate_for({:options => options}) do |returned|
+        block.call(returned)
+      end
+    end
+
+    # Iterates over all properties in a specified namespace.
+    # The namespace parameter can be the URI of the namespace to use,
+    # or a symbol representing the namespace prefix, e.g. :exif.
+    # The recognized namespace prefixes are based on a set of common
+    # namespace prefixes (generated at runtime in Fasttrack::NAMESPACES)
+    # as well as the local namespaces currently in use.
+    # @param [String, Symbol] ns namespace to iterate over
+    # @param [Array<Symbol>] opts a set of options to restrict the
+    #   iteration; see #each_with_options for supported options
+    # @yieldparam (see #iterate_for)
+    # @return [Enumerator] if no block is given
+    def each_in_namespace ns, opts=[], &block
+      return enum_for(:each_in_namespace, ns) unless block_given?
+
+      opts = {:namespace => ns}
+      iterate_for(opts) do |returned|
+        block.call(returned)
+      end
+    end
+
+    def rewind
+      @iterator = new_iterator
+    end
+
+    private
+
+    # Attempts to find the namespace URI given a symbol representation.
+    # @param [Symbol]
+    # @return [String, nil]
+    def namespace_for sym
+      Fasttrack::NAMESPACES[sym]
+    end
+
+    # Creates a new iterator based on the options specified in the
+    # @iterator_opts ivar, or an options hash if specified.
+    # The options hash can specify the following:
+    # :namespace => Limits the iteration to a specific namespace URI
+    # :options => Options for the iteration; must be an array composed
+    #   of one or more symbols specified in the Exempi::XmpIterOptions 
+    #   enum.
+    # @param [Hash] params hash containing the options for the new
+    #   iterator.
+    # @return [FFI::Pointer] pointer to the new iterator
+    def new_iterator params=@iterator_opts
+      ns   = params[:namespace]
+      # property support is currently disabled
+      prop = nil
+      opts = params[:options]
+      iterator = Exempi.xmp_iterator_new @xmp_ptr, ns, prop, opts
+      ObjectSpace.define_finalizer(iterator, self.class.finalize_iterator(iterator))
+
+      iterator
+    end
+
+    # This method is the plumbing which is used by the various
+    # Enumerable mixin methods.
+    # @param (see #new_iterator)
+    # @yieldparam [String] uri the uri for the property
+    # @yieldparam [String] name the property's name
+    # @yieldparam [String] value the property's value
+    # @yieldparam [Hash] options additional metadata about the property
+    def iterate_for opts={}
+      # Select the namespace; lookup symbol if appropriate, otherwise
+      # use string or nil
+      if opts[:namespace].is_a? Symbol
+        ns = namespace_for opts[:namespace]
+      else
+        ns = opts[:namespace]
+      end
+
+      # record iterator options; these are necessary to call subsequent
+      # iterator functions
+      @iterator_opts = {
+        :namespace     => ns,
+        # note that :property is currently unimplemented in Fasttrack
+        :property      => opts[:property],
+        :options       => opts[:options] || []
+      }
+
+      @iterator = new_iterator
+
+      returned_ns         = Exempi.xmp_string_new
+      returned_prop_path  = Exempi.xmp_string_new
+      returned_prop_value = Exempi.xmp_string_new
+      returned_prop_opts  = FFI::MemoryPointer.new :uint32
+
+      # keep iterating until xmp_iterator_next() returns false, which
+      # indicates it has finished traversing all the properties
+      while Exempi.xmp_iterator_next(@iterator, returned_ns, returned_prop_path, returned_prop_value, nil)
+        ary = [returned_ns, returned_prop_path, returned_prop_value].map do |xmp_str|
+          Exempi.xmp_string_cstr xmp_str
+        end
+
+        ary << Exempi.parse_bitmask(returned_prop_opts.read_uint32,
+          Exempi::XMP_PROPS_BITS, true)
+
+        yield ary
+      end
+    end
+  end
+end

data/test/data/avchd.xmp

@@ -0,0 +1,25 @@
+<?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?>
+<x:xmpmeta xmlns:x='adobe:ns:meta/' x:xmptk='Image::ExifTool 9.00'>
+<rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'>
+
+ <rdf:Description rdf:about=''
+  xmlns:exif='http://ns.adobe.com/exif/1.0/'>
+  <exif:DateTimeOriginal>2012-03-17T11:45:16-04:00</exif:DateTimeOriginal>
+  <exif:ExposureProgram>1</exif:ExposureProgram>
+  <exif:ExposureTime>1/30</exif:ExposureTime>
+  <exif:FNumber>5/1</exif:FNumber>
+  <exif:GPSMapDatum>WGS-84</exif:GPSMapDatum>
+  <exif:GPSStatus>V</exif:GPSStatus>
+  <exif:GPSVersionID>2.2.0.0</exif:GPSVersionID>
+ </rdf:Description>
+
+ <rdf:Description rdf:about=''
+  xmlns:tiff='http://ns.adobe.com/tiff/1.0/'>
+  <tiff:ImageLength>1080</tiff:ImageLength>
+  <tiff:ImageWidth>1920</tiff:ImageWidth>
+  <tiff:Make>Sony</tiff:Make>
+  <tiff:Model>NEX-FS100UK</tiff:Model>
+ </rdf:Description>
+</rdf:RDF>
+</x:xmpmeta>
+<?xpacket end='w'?>

data/test/fasttrack_test.rb

@@ -0,0 +1,11 @@
+require 'minitest/autorun'
+require 'fasttrack'
+
+describe Fasttrack do
+  it "should be able to handle Exempi errors" do
+    lambda do
+      Exempi.xmp_files_open_new "invalid_file", nil
+      Fasttrack.handle_exempi_failure
+    end.must_raise Exempi::ExempiError
+  end
+end

data/test/file_test.rb

@@ -0,0 +1,129 @@
+require 'fasttrack'
+
+require 'mocha/setup'
+require 'minitest/autorun'
+require 'fileutils'
+require 'tmpdir'
+
+describe Fasttrack::File do
+  before do
+    @test_data  = File.expand_path File.join(__FILE__,"..","data","avchd.xmp")
+    @test_image = File.expand_path File.join(__FILE__,"..","data","image.jpg")
+
+    @tmpdir = Dir.mktmpdir
+    Dir.chdir @tmpdir
+  end
+
+  it "should be able to create a new file object" do
+    Fasttrack::File.new(@test_data).must_be_kind_of Fasttrack::File
+  end
+
+  it "should raise when created with a file that doesn't exist" do
+    lambda do
+      Fasttrack::File.new "no_file_here"
+    end.must_raise Errno::ENOENT
+  end
+
+  it "should be able to report whether XMP can be written to a file" do
+    # If the file is opened read-only the answer should be false
+    file = Fasttrack::File.new @test_data, "r"
+    refute file.can_put_xmp?
+
+    # also test when file is opened for writing
+    file = Fasttrack::File.new @test_image, "w"
+    assert file.can_put_xmp?
+  end
+
+  it "should be able to save changes to a file" do
+    file1 = Fasttrack::File.new @test_data
+    FileUtils.copy File.expand_path(@test_image), "temp.jpg"
+    file2 = Fasttrack::File.new "temp.jpg", "w"
+    file2.xmp = file1.xmp
+    assert file2.save!
+    assert file2.close!
+  end
+
+  it "should be able to reopen a closed file" do
+    FileUtils.copy File.expand_path(@test_image), "temp.jpg"
+    file1 = Fasttrack::File.new "temp.jpg", "w"
+    file1.close!
+    file2 = Fasttrack::File.new @test_data
+    file1.open
+    file1.xmp = file2.xmp
+    assert file1.save!
+  end
+
+  it "should raise when saving changes to a closed file" do
+    lambda do
+      file1 = Fasttrack::File.new @test_data
+      file1.close!
+      file2 = Fasttrack::File.new @test_image
+      file1.xmp = file2.xmp      
+    end.must_raise Fasttrack::WriteError
+  end
+
+  it "should raise when reopening an open file" do
+    lambda do
+      file1 = Fasttrack::File.new @test_data
+      file1.open
+    end.must_raise Fasttrack::OpenError
+  end
+
+  it "should be able to copy XMP file to file" do
+    file1 = Fasttrack::File.new @test_data
+    FileUtils.copy File.expand_path(@test_image), "temp.jpg"
+    file2 = Fasttrack::File.new "temp.jpg", "w"
+
+    file2_orig = file2.xmp
+    file2.xmp = file1.xmp
+    file2.save!
+    file2.xmp.wont_be_same_as file2_orig
+  end
+
+  it "should be able to copy manually-created XMP into a file" do
+    FileUtils.copy File.expand_path(@test_image), "temp.jpg"
+    file = Fasttrack::File.new "temp.jpg", "w"
+
+    new_xmp = Exempi.xmp_new_empty
+    Exempi.xmp_set_property new_xmp, Fasttrack::NAMESPACES[:tiff],
+      'tiff:Make', 'Sony', nil
+
+    old_xmp = file.xmp
+    file.xmp = new_xmp
+    file.save!
+    file.xmp.wont_be_same_as old_xmp
+  end
+  
+  it "should raise when trying to write xmp into a read-only file" do
+    file1 = Fasttrack::File.new @test_data
+    file2 = Fasttrack::File.new @test_image
+
+    lambda {file2.xmp = file1.xmp}.must_raise Fasttrack::WriteError
+  end
+
+  it "should raise when trying to save changes into a read-only file" do
+    file = Fasttrack::File.new @test_data, 'r'
+    lambda {file.save!}.must_raise Fasttrack::WriteError
+  end
+
+  it "should raise when trying to copy non-XMP data into a file" do
+    FileUtils.copy File.expand_path(@test_image), "temp.jpg"
+    file = Fasttrack::File.new "temp.jpg", "w"
+
+    lambda {file.xmp = 'xmp'}.must_raise TypeError
+  end
+
+  it "should raise if Exempi fails to close a file" do
+    Exempi.stubs(:xmp_files_close).returns(false)
+    lambda {Fasttrack::File.new(@test_data).close!}.must_raise Exempi::ExempiError
+  end
+
+  it "should raise if Exempi fails to open a file" do
+    Exempi.stubs(:xmp_files_open).returns(false)
+    lambda {Fasttrack::File.new(@test_data)}.must_raise Exempi::ExempiError
+  end
+
+  after do
+    FileUtils.remove_entry_secure @tmpdir
+  end
+end

data/test/xmp_test.rb

@@ -0,0 +1,172 @@
+require 'fasttrack'
+
+require 'mocha/setup'
+require 'minitest/autorun'
+require 'nokogiri'
+
+describe Fasttrack::XMP do
+  before do
+    @test_data = File.join(__FILE__,"..","data","avchd.xmp")
+  end
+
+  it "should be able to create an empty XMP packet" do
+    xmp = Fasttrack::XMP.new
+    xmp.namespaces.must_be_empty
+  end
+
+  it "should return the correct namespaces" do
+    file = Fasttrack::File.new @test_data
+    file.xmp.namespaces.must_equal [Fasttrack::NAMESPACES[:exif],
+      Fasttrack::NAMESPACES[:tiff]]
+  end
+
+  it "should be able to fetch properties" do
+    file = Fasttrack::File.new @test_data
+    file.xmp['tiff:Make'].must_equal 'Sony'
+    file.xmp.get(:tiff, 'tiff:Make').must_equal 'Sony'
+    file.xmp.get(:tiff, 'Make').must_equal 'Sony'
+    # Test looking up the namespaces from the table
+    file.xmp.get(Fasttrack::NAMESPACES[:tiff],
+      'Make').must_equal 'Sony'
+    # Test using the literal URI string 
+    file.xmp.get('http://ns.adobe.com/tiff/1.0/',
+      'Make').must_equal 'Sony'
+  end
+
+  it "should be able to set properties" do
+    file = Fasttrack::File.new @test_data
+    file.xmp['tiff:Make'] = 'Samsung'
+    file.xmp['tiff:Make'].must_equal 'Samsung'
+
+    file.xmp.set :tiff, 'tiff:Make', 'Canon'
+    file.xmp['tiff:Make'].must_equal 'Canon'
+
+    file.xmp.set :tiff, 'Make', 'Olympus'
+    file.xmp['tiff:Make'].must_equal 'Olympus'
+
+    file.xmp.set Fasttrack::NAMESPACES[:tiff],
+      'Make', 'Panasonic'
+    file.xmp['tiff:Make'].must_equal 'Panasonic'
+
+    file.xmp.set 'http://ns.adobe.com/tiff/1.0/', 'Make', 'Pentax'
+    file.xmp['tiff:Make'].must_equal 'Pentax'
+  end
+
+  it "should be able to delete properties" do
+    file = Fasttrack::File.new @test_data
+    file.xmp.delete(:tiff, 'tiff:Make').must_equal 'Sony'
+    file.xmp['tiff:Make'].must_be_nil
+  end
+
+  it "should return nil when deleting a property which doesn't exist" do
+    xmp = Fasttrack::XMP.new
+    xmp.delete(:exif, 'foo').must_be_nil
+  end
+
+  it "should not decrement the namespace count when deleting a nonextant property" do
+    file = Fasttrack::File.new @test_data
+    file.xmp.instance_variable_get(:@namespaces)["http://ns.adobe.com/exif/1.0/"].must_equal 7
+
+    file.xmp.delete(:exif, 'foo')
+    file.xmp.instance_variable_get(:@namespaces)["http://ns.adobe.com/exif/1.0/"].must_equal 7
+  end
+
+  it "should be able to iterate over properties" do
+    file = Fasttrack::File.new @test_data
+    file.xmp.each.must_be_kind_of Enumerator
+    ary = file.xmp.each.to_a
+    ary.first.must_be_kind_of Array
+    ary.first.wont_be_empty
+    # yeah, the first entry has empty properties
+    # look at the hash later
+    ary.first[0..-2].must_equal ['http://ns.adobe.com/exif/1.0/', '', '']
+
+    # let's look at something with properties instead
+    ary[1].must_include 'http://ns.adobe.com/exif/1.0/'
+    ary[1].must_include 'exif:DateTimeOriginal'
+    ary[1].must_include '2012-03-17T11:45:16-04:00'
+
+    ary = file.xmp.map(&:last)
+    ary.first.must_be_kind_of Hash
+    ary.first.must_include :has_type
+  end
+
+  it "should be able to restrict iterations via namespace" do
+    file = Fasttrack::File.new @test_data
+    file.xmp.each_in_namespace(:exif).count.must_equal 8
+  end
+
+  it "should be able to rewind iterations" do
+    file = Fasttrack::File.new @test_data
+    enum = file.xmp.each
+    enum.next
+    enum.next
+    ary = enum.next
+    enum.rewind
+    enum.next.wont_equal ary
+  end
+
+  it "should correctly track namespace usage" do
+    file = Fasttrack::File.new @test_data
+    file.xmp.namespaces.must_be_kind_of Array
+    file.xmp.namespaces.count.must_equal 2
+    ns = file.xmp.instance_variable_get :@namespaces
+    ns.must_be_kind_of Hash
+    ns['http://ns.adobe.com/exif/1.0/'].must_equal 7
+
+    # is it properly decremented when we delete one of those properties?
+    date = file.xmp.delete :exif, 'exif:DateTimeOriginal'
+    ns['http://ns.adobe.com/exif/1.0/'].must_equal 6
+
+    # how about incremented if we add one?
+    file.xmp['exif:DateTimeOriginal'] = date
+    ns['http://ns.adobe.com/exif/1.0/'].must_equal 7
+
+    # is the hash udpated if we add a totally new namespace?
+    file.xmp['pdf:Foo'] = 'bar'
+    file.xmp.namespaces.must_include 'http://ns.adobe.com/pdf/1.3/'
+  end
+
+  it "should create copies with unique pointers" do
+    file = Fasttrack::File.new @test_data
+    xmp = file.xmp
+    xmp2 = xmp.dup
+    xmp.xmp_ptr.wont_equal xmp2.xmp_ptr
+  end
+
+  it "should be able to create XMP objects from XML strings" do
+    xml_string = File.read File.expand_path(@test_data)
+    xmp = Fasttrack::XMP.parse xml_string
+    xmp.must_be_kind_of Fasttrack::XMP
+    xmp['tiff:Make'].must_equal 'Sony'
+
+    xmp_from_file = Fasttrack::File.new(@test_data).xmp
+    xmp_from_file.must_equal xmp
+  end
+
+  it "should be able to serialize XMP to a string" do
+    xmp = Fasttrack::XMP.new
+    xmp['tiff:Make'] = 'Sony'
+    xml = Nokogiri::XML.parse xmp.serialize
+    xml.xpath("/x:xmpmeta/rdf:RDF/rdf:Description/tiff:Make",
+      'rdf' => 'http://www.w3.org/1999/02/22-rdf-syntax-ns#',
+      'tiff' => 'http://ns.adobe.com/tiff/1.0/',
+      'x' => 'adobe:ns:meta/').text.must_equal 'Sony'
+  end
+
+  it "should be able to create XMP objects from a file pointer" do
+    file = Exempi.xmp_files_new
+    Exempi.xmp_files_open file, File.expand_path(@test_data), :XMP_OPEN_READ
+
+    xmp = Fasttrack::XMP.from_file_pointer file
+    xmp['tiff:Make'].must_equal 'Sony'
+
+    Exempi.xmp_files_free file
+  end
+
+  it "should raise if Exempi fails to set properties" do
+    Exempi.stubs(:xmp_set_property).returns(false)
+
+    lambda {Fasttrack::XMP.new.set(:exif, 'Make', 'Foo')}.must_raise Exempi::ExempiError
+  end
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: fasttrack
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Misty De Meo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-12-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: exempi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.2.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.2.2
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.5
+description: |2
+                        Fasttrack is an easy-to-use Ruby wrapper for
+                        Exempi, a C library for managing XMP metadata.
+                        Fasttrack provides a dead-easy, object-oriented
+                        interface to Exempi's functions.
+email:
+- mistydemeo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- fasttrack.gemspec
+- lib/fasttrack.rb
+- lib/fasttrack/exceptions.rb
+- lib/fasttrack/file.rb
+- lib/fasttrack/namespaces.rb
+- lib/fasttrack/version.rb
+- lib/fasttrack/xmp.rb
+- test/data/avchd.xmp
+- test/data/image.jpg
+- test/fasttrack_test.rb
+- test/file_test.rb
+- test/xmp_test.rb
+homepage: https://github.com/mistydemeo/fasttrack
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Ruby sugar for Exempi
+test_files:
+- test/data/avchd.xmp
+- test/data/image.jpg
+- test/fasttrack_test.rb
+- test/file_test.rb
+- test/xmp_test.rb
+has_rdoc: