hydra-file_characterization 0.2.0 → 0.2.1

data/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# How to Contribute
+
+We want your help to make Project Hydra great.
+There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
+
+## Hydra Project Intellectual Property Licensing and Ownership
+
+All code contributors must have an Individual Contributor License Agreement (iCLA) on file with the Hydra Project Steering Group.
+If the contributor works for an institution, the institution must have a Corporate Contributor License Agreement (cCLA) on file.
+
+https://wiki.duraspace.org/display/hydra/Hydra+Project+Intellectual+Property+Licensing+and+Ownership
+
+You should also add yourself to the `CONTRIBUTORS.md` file in the root of the project.
+
+## Contribution Tasks
+
+* Reporting Issues
+* Making Changes
+* Submitting Changes
+* Merging Changes
+
+### Reporting Issues
+
+* Make sure you have a [GitHub account](https://github.com/signup/free)
+* Submit a [Github issue](./issues) by:
+  * Clearly describing the issue
+    * Provide a descriptive summary
+    * Explain the expected behavior
+    * Explain the actual behavior
+    * Provide steps to reproduce the actual behavior
+
+### Making Changes
+
+* Fork the repository on GitHub
+* Create a topic branch from where you want to base your work.
+  * This is usually the master branch.
+  * To quickly create a topic branch based on master; `git branch fix/master/my_contribution master`
+  * Then checkout the new branch with `git checkout fix/master/my_contribution`.
+  * Please avoid working directly on the `master` branch.
+  * You may find the [hub suite of commands](https://github.com/defunkt/hub) helpful
+* Make commits of logical units.
+  * Your commit should include a high level description of your work in HISTORY.textile 
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure your commit messages are [well formed](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
+* If you created an issue, you can close it by including "Closes #issue" in your commit message. See [Github's blog post for more details](https://github.com/blog/1386-closing-issues-via-commit-messages)
+
+```
+    Present tense short summary (50 characters or less)
+
+    More detailed description, if necessary. It should be wrapped to 72
+    characters. Try to be as descriptive as you can, even if you think that
+    the commit content is obvious, it may not be obvious to others. You
+    should add such description also if it's already present in bug tracker,
+    it should not be necessary to visit a webpage to check the history.
+
+    Include Closes #<issue-number> when relavent.
+
+    Description can have multiple paragraphs and you can use code examples
+    inside, just indent it with 4 spaces:
+
+        class PostsController
+          def index
+            respond_with Post.limit(10)
+          end
+        end
+
+    You can also add bullet points:
+
+    - you can use dashes or asterisks
+
+    - also, try to indent next line of a point for readability, if it's too
+      long to fit in 72 characters
+```
+
+* Make sure you have added the necessary tests for your changes.
+* Run _all_ the tests to assure nothing else was accidentally broken.
+* When you are ready to submit a pull request
+
+### Submitting Changes
+
+[Detailed Walkthrough of One Pull Request per Commit](http://ndlib.github.io/practices/one-commit-per-pull-request/)
+
+* Read the article ["Using Pull Requests"](https://help.github.com/articles/using-pull-requests) on GitHub.
+* Make sure your branch is up to date with its parent branch (i.e. master)
+  * `git checkout master`
+  * `git pull --rebase`
+  * `git checkout <your-branch>`
+  * `git rebase master`
+  * It is likely a good idea to run your tests again.
+* Squash the commits for your branch into one commit
+  * `git rebase --interactive HEAD~<number-of-commits>` ([See Github help](https://help.github.com/articles/interactive-rebase))
+  * To determine the number of commits on your branch: `git log master..<your-branch> --oneline | wc -l`
+  * Squashing your branch's changes into one commit is "good form" and helps the person merging your request to see everything that is going on.
+* Push your changes to a topic branch in your fork of the repository.
+* Submit a pull request from your fork to the project.
+
+### Merging Changes
+
+* It is considered "poor from" to merge your own request.
+* Please take the time to review the changes and get a sense of what is being changed. Things to consider:
+  * Does the commit message explain what is going on?
+  * Does the code changes have tests? _Not all changes need new tests, some changes are refactorings_
+  * Does the commit contain more than it should? Are two separate concerns being addressed in one commit?
+  * Did the Travis tests complete successfully?
+* If you are uncertain, bring other contributors into the conversation by creating a comment that includes their @username.
+* If you like the pull request, but want others to chime in, create a +1 comment and tag a user.
+
+# Additional Resources
+
+* [General GitHub documentation](http://help.github.com/)
+* [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
+* [Pro Git](http://git-scm.com/book) is both a free and excellent book about Git.
+* [A Git Config for Contributing](http://ndlib.github.io/practices/my-typical-per-project-git-config/)

data/README.md

@@ -10,16 +10,30 @@ To provide a wrapper for file characterization
 
 If you are using Rails add the following to an initializer (./config/initializers/hydra-file_characterization_config.rb):
 
-    Hydra::FileCharacterization.configure do |config|
-      config.tool_path(:fits, '/path/to/fits')
-    end
+```ruby
+Hydra::FileCharacterization.configure do |config|
+  config.tool_path(:fits, '/path/to/fits')
+end
+```
 
-To use the characterizer:
+You can call a single characterizer…
+```ruby
+xml_string = Hydra::FileCharacterization.characterize(contents_of_a_file, 'file.rb', :fits)
+```
 
-    characterization_xml = Hydra.characterize(file.read, file.basename, :fits)
+…for this particular call, you can specify custom fits path.
 
-    # This does not work at this point
-    fits_xml, ffprobe_xml  = Hydra.characterize(file.read, file.basename, :fits, :ffprobe)
+```ruby
+xml_string = Hydra::FileCharacterization.characterize(contents_of_a_file, 'file.rb', :fits) do |config|
+  config[:fits] = './really/custom/path/to/fits'
+end
+```
+
+You can also call multiple characterizers at the same time.
+
+```ruby
+fits_xml, ffprobe_xml = Hydra::FileCharacterization.characterize(contents_of_a_file, 'file.rb', :fits, :ffprobe)
+```
 
 * Why `file.read`? To highlight that we want a string. In the case of ActiveFedora, we have a StringIO instead of a file.
 * Why `file.basename`? In the case of Fits, the characterization takes cues from the extension name.
@@ -27,20 +41,3 @@ To use the characterizer:
 ## Registering New Characterizers
 
 This is possible by adding a characterizer to the `Hydra::FileCharacterization::Characterizers`' namespace.
-
-## To Consider
-
-How others are using the extract_metadata method
-- https://github.com/curationexperts/bawstun/blob/ff8142ac043604c11a6f57b03629284bfd3043ea/app/models/generic_file.rb#L173
-
-## Todo Steps
-
-- ~~Given a filename, characterize the file and return a raw XML stream~~
-- ~~Provide method for converting a StringIO and original file name to a temp file with comparable, then running the characterizer against the tempfile~~
-- ~~Provide a configuration option for the fits path; This would be the default for the characterizer~~
-- Update existing Sufia implementation
-  - Deprecrate Hydra::Derivatives direct method call
-  - Instead call the characterizer with the content
-- Allow characterization services to be chained together
-  - ~~This would involve renaming the Characterizer to something else (i.e. Characterizers::Fits)~~
-- Provide an ActiveFedora Datastream that maps the raw XML stream to a datastructure

data/lib/hydra/file_characterization.rb

@@ -9,28 +9,9 @@ module Hydra
 
   module_function
 
-  #
-  # Run all of the specified tools against the given content and filename.
-  #
-  # @param [String] content - The contents of the original file
-  # @param [String] filename - The original file's filename; Some
-  #   characterization tools take hints from the file names
-  # @param [Array] tool_names - A list of tool names available on the system
-  #
-  # @return [String, Array<String>] -
-  #    String - When a single tool_name is given, returns the raw XML as a
-  #      string
-  #    Array<String> - When multiple tool_names are given, returns an equal
-  #      length Array of XML strings
-  def characterize(content, filename, *tool_names)
-    tool_outputs = []
-    tool_names = Array(tool_names).flatten.compact
-    FileCharacterization::ToTempFile.open(content, filename) do |f|
-      tool_names.each do |tool_name|
-        tool_outputs << FileCharacterization.characterize_with(tool_name, f.path)
-      end
-    end
-    tool_names.size == 1 ? tool_outputs.first : tool_outputs
+  # A convenience method
+  def characterize(*args, &block)
+    FileCharacterization.characterize(*args, &block)
   end
 
   module FileCharacterization
@@ -39,6 +20,49 @@ module Hydra
       attr_accessor :configuration
     end
 
+    #
+    # Run all of the specified tools against the given content and filename.
+    #
+    # @example
+    #   xml_string = Hydra::FileCharacterization.characterize(contents_of_a_file, 'file.rb', :fits)
+    #
+    # @example
+    #   xml_string = Hydra::FileCharacterization.characterize(contents_of_a_file, 'file.rb', :fits) do |config|
+    #     config[:fits] = './really/custom/path/to/fits'
+    #   end
+    #
+    # @example
+    #   fits_xml, ffprobe_xml = Hydra::FileCharacterization.characterize(contents_of_a_file, 'file.rb', :fits, :ffprobe)
+    #
+    # @param [String] content - The contents of the original file
+    # @param [String] filename - The original file's filename; Some
+    #   characterization tools take hints from the file names
+    # @param [Hash/Array] tool_names - A list of tool names available on the system
+    #   if you provide a Hash
+    #
+    # @return [String, Array<String>] -
+    #    String - When a single tool_name is given, returns the raw XML as a
+    #      string
+    #    Array<String> - When multiple tool_names are given, returns an equal
+    #      length Array of XML strings
+    #
+    # @yieldparam [Hash] For any of the specified tool_names, if you add a
+    #    key to the yieldparam with a value, that value will be used as the path
+    #
+    # @see Hydra::FileCharacterization.configure
+    def self.characterize(content, filename, *tool_names)
+      tool_outputs = []
+      tool_names = Array(tool_names).flatten.compact
+      custom_paths = {}
+      yield(custom_paths) if block_given?
+      FileCharacterization::ToTempFile.open(content, filename) do |f|
+        tool_names.each do |tool_name|
+          tool_outputs << FileCharacterization.characterize_with(tool_name, f.path, custom_paths[tool_name])
+        end
+      end
+      tool_names.size == 1 ? tool_outputs.first : tool_outputs
+    end
+
     def self.configure
       self.configuration ||= Configuration.new
       yield(configuration)
@@ -51,4 +75,4 @@ module Hydra
     end
 
   end
-end
+end

data/lib/hydra/file_characterization/characterizer.rb

@@ -9,8 +9,9 @@ module Hydra::FileCharacterization
     class_attribute :tool_path
 
     attr_reader :filename
-    def initialize(filename)
+    def initialize(filename, tool_path = nil)
       @filename = filename
+      @tool_path = tool_path
     end
 
     def call
@@ -31,14 +32,14 @@ module Hydra::FileCharacterization
       end
     end
 
+    def tool_path
+      @tool_path || self.class.tool_path || (raise Hydra::FileCharacterization::UnspecifiedToolPathError.new(self.class))
+    end
+
     protected
 
     def command
       raise NotImplementedError, "Method #command should be overriden in child classes"
     end
-
-    def tool_path
-      self.class.tool_path || (raise Hydra::FileCharacterization::UnspecifiedToolPathError.new(self.class))
-    end
   end
 end

data/lib/hydra/file_characterization/characterizers.rb

@@ -16,8 +16,8 @@ module Hydra::FileCharacterization
     tool_name.to_s.gsub(/(?:^|_)([a-z])/) { $1.upcase }
   end
 
-  def characterize_with(tool_name, file_path)
-    tool_obj = characterizer(tool_name).new(file_path)
+  def characterize_with(tool_name, *args)
+    tool_obj = characterizer(tool_name).new(*args)
     tool_obj.call
   end
 

data/lib/hydra/file_characterization/version.rb

@@ -1,5 +1,5 @@
 module Hydra
   module FileCharacterization
-    VERSION = "0.2.0"
+    VERSION = "0.2.1"
   end
 end

data/spec/lib/hydra/file_characterization/characterizer_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+require 'hydra/file_characterization/characterizer'
+
+module Hydra::FileCharacterization
+  describe Characterizer do
+    let(:filename) { __FILE__ }
+    let(:instance_tool_path) { nil }
+    let(:class_tool_path) { nil }
+
+    subject { Hydra::FileCharacterization::Characterizer.new(filename, instance_tool_path) }
+    around(:each) do |example|
+      Hydra::FileCharacterization::Characterizer.tool_path = class_tool_path
+      example.run
+      Hydra::FileCharacterization::Characterizer.tool_path = nil
+    end
+
+    context 'with custom instance tool_path' do
+      let(:instance_tool_path) { '/arbitrary/path' }
+      let(:class_tool_path) { '/a_different/path' }
+
+      its(:tool_path) { should eq instance_tool_path}
+    end
+
+    context 'with custom class tool_path' do
+      let(:instance_tool_path) { nil }
+      let(:class_tool_path) { '/a_different/path' }
+
+      its(:tool_path) { should eq class_tool_path}
+    end
+
+    context 'without a specified tool_path' do
+      it 'should raise Hydra::FileCharacterization::UnspecifiedToolPathError' do
+        expect {
+          subject.tool_path
+        }.to raise_error(Hydra::FileCharacterization::UnspecifiedToolPathError)
+      end
+    end
+  end
+end

data/spec/lib/hydra/file_characterization_spec.rb

@@ -4,43 +4,60 @@ require 'hydra/file_characterization/characterizer'
 
 module Hydra
 
-  describe '.characterize' do
-    let(:content) { "class Test; end\n" }
-    let(:filename) { 'test.rb' }
-    subject { Hydra.characterize(content, filename, tool_names) }
+  describe FileCharacterization do
 
-    describe 'for fits' do
-      let(:tool_names) { :fits }
-      it { should match(/#{'<identity format="Plain text" mimetype="text/plain"'}/) }
-    end
+    describe '.characterize' do
+      let(:content) { "class Test; end\n" }
+      let(:filename) { 'test.rb' }
+      subject { Hydra::FileCharacterization.characterize(content, filename, tool_names) }
 
-    describe 'for a bogus tool' do
-      let(:tool_names) { :cookie_monster }
-      it {
-        expect {
-          subject
-        }.to raise_error(Hydra::FileCharacterization::ToolNotFoundError)
-      }
-    end
+      describe 'for fits' do
+        let(:tool_names) { [:fits] }
+        it { should match(/#{'<identity format="Plain text" mimetype="text/plain"'}/) }
+      end
 
-    describe 'for a mix of bogus and valid tools' do
-      let(:tool_names) { [:fits, :cookie_monster] }
-      it {
-        expect {
-          subject
-        }.to raise_error(Hydra::FileCharacterization::ToolNotFoundError)
-      }
-    end
+      describe 'with configured path' do
+        it {
+          response = Hydra::FileCharacterization.characterize(content, filename, :fits) do |config|
+            config[:fits] = `which fits || which fits.sh`.strip
+          end
+          expect(response).to match(/#{'<identity format="Plain text" mimetype="text/plain"'}/)
+        }
+      end
 
-    describe 'for no tools' do
-      let(:tool_names) { nil }
-      it { should eq [] }
-    end
+      describe 'with multiple runs' do
+        it {
+          response_1, response_2, response_3 = Hydra::FileCharacterization.characterize(content, filename, :fits, :fits)
+          expect(response_1).to match(/#{'<identity format="Plain text" mimetype="text/plain"'}/)
+          expect(response_2).to match(/#{'<identity format="Plain text" mimetype="text/plain"'}/)
+          expect(response_3).to be_nil
+        }
+      end
 
-  end
+      describe 'for a bogus tool' do
+        let(:tool_names) { [:cookie_monster] }
+        it {
+          expect {
+            subject
+          }.to raise_error(Hydra::FileCharacterization::ToolNotFoundError)
+        }
+      end
 
-  describe FileCharacterization do
+      describe 'for a mix of bogus and valid tools' do
+        let(:tool_names) { [:fits, :cookie_monster] }
+        it {
+          expect {
+            subject
+          }.to raise_error(Hydra::FileCharacterization::ToolNotFoundError)
+        }
+      end
+
+      describe 'for no tools' do
+        let(:tool_names) { nil }
+        it { should eq [] }
+      end
 
+    end
     describe '.configure' do
       let(:content) { "class Test; end\n" }
       let(:filename) { 'test.rb' }
@@ -56,10 +73,10 @@ module Hydra
         end
 
         expect {
-          Hydra.characterize(content, filename, :fits)
+          Hydra::FileCharacterization.characterize(content, filename, :fits)
         }.to raise_error(Hydra::FileCharacterization::UnspecifiedToolPathError)
       end
     end
 
   end
-end
+end

metadata

@@ -1,7 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: hydra-file_characterization
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
+  prerelease: 
 platform: ruby
 authors:
 - James Treacy
@@ -11,62 +12,70 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-19 00:00:00.000000000 Z
+date: 2013-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: guard
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: guard-rspec
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: To provide a wrapper for file characterization
@@ -81,6 +90,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .rspec
+- CONTRIBUTING.md
 - Gemfile
 - Guardfile
 - LICENSE
@@ -102,6 +112,7 @@ files:
 - spec/fixtures/brendan_behan.jpeg.fits.xml
 - spec/fixtures/brendan_broken.dxxd
 - spec/fixtures/brendan_broken.dxxd.fits.xml
+- spec/lib/hydra/file_characterization/characterizer_spec.rb
 - spec/lib/hydra/file_characterization/characterizers/ffprobe_spec.rb
 - spec/lib/hydra/file_characterization/characterizers/fits_spec.rb
 - spec/lib/hydra/file_characterization/characterizers_spec.rb
@@ -111,26 +122,27 @@ files:
 homepage: https://github.com/projecthydra/hydra-file_characterization
 licenses:
 - APACHE2
-metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 1.8.25
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: To provide a wrapper for file characterization
 test_files:
 - spec/fixtures/archive.zip
@@ -139,9 +151,11 @@ test_files:
 - spec/fixtures/brendan_behan.jpeg.fits.xml
 - spec/fixtures/brendan_broken.dxxd
 - spec/fixtures/brendan_broken.dxxd.fits.xml
+- spec/lib/hydra/file_characterization/characterizer_spec.rb
 - spec/lib/hydra/file_characterization/characterizers/ffprobe_spec.rb
 - spec/lib/hydra/file_characterization/characterizers/fits_spec.rb
 - spec/lib/hydra/file_characterization/characterizers_spec.rb
 - spec/lib/hydra/file_characterization/to_temp_file_spec.rb
 - spec/lib/hydra/file_characterization_spec.rb
 - spec/spec_helper.rb
+has_rdoc: 

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA1:
-  metadata.gz: 6aa0e27917882868e5356621f163eda7e6ab56a6
-  data.tar.gz: d3114a797679bcd25bc29f19ae31f70659828016
-SHA512:
-  metadata.gz: 88e44705e2cb908b5732a3f220e90a2544b909834bbe3f96b07ea82c142b31cffaebd38d068493ad84cb0887fe6eec76aeff11e9fd874c116a24fa9295729e3c
-  data.tar.gz: 6932b2860c71bfb3171f0a952021fe0935121b880ea7fcd3aff5b4c5dd47e551143773f154be0e852f5b637f1f22e3a3a1d1949eaea392b38984793017eb7bb2