pairtree 0.0.0 → 0.1.0

data/.gitignore

@@ -0,0 +1,44 @@
+# rcov generated
+coverage
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+
+# jeweler generated
+pkg
+
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
+#
+# * Create a file at ~/.gitignore
+# * Include files you want ignored
+# * Run: git config --global core.excludesfile ~/.gitignore
+#
+# After doing this, these files will be ignored in all your git projects,
+# saving you from having to 'pollute' every project you touch with them
+#
+# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
+#
+# For MacOS:
+#
+#.DS_Store
+#
+# For TextMate
+#*.tmproj
+#tmtags
+#
+# For emacs:
+#*~
+#\#*
+#.\#*
+#
+# For vim:
+#*.swp
+#
+Gemfile.lock

data/Gemfile

@@ -1,13 +1,4 @@
 source "http://rubygems.org"
-# Add dependencies required to use your gem here.
-# Example:
-#   gem "activesupport", ">= 2.3.5"
 
-# Add dependencies to develop your gem here.
-# Include everything needed to run rake, tests, features, etc.
-group :development do
-  gem "shoulda", ">= 0"
-  gem "bundler", "~> 1.0.0"
-  gem "jeweler", "~> 1.5.1"
-  gem "rcov", ">= 0"
-end
+gemspec
+gem 'rcov', :platform => :mri_18

data/LICENSE.txt

@@ -1,20 +1,12 @@
-Copyright (c) 2010 Chris Beer
-
-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.
+###########################################################################
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

data/README.textile

@@ -0,0 +1,37 @@
+h1. pairtree
+
+Ruby implementation of the "Pairtree":https://confluence.ucop.edu/display/Curation/PairTree microservice specification from the California Digital Library
+
+h2. Usage
+
+<pre><code>
+  # Initiate a tree
+  pairtree = Pairtree.at('./data', :prefix => 'pfx:', :create => true)
+  
+  # Create a ppath
+  obj = pairtree.mk('pfx:abc123def')
+  
+  # Access an existing ppath
+  obj = pairtree['pfx:abc123def']
+  obj = pairtree.get('pfx:abc123def')
+  
+  # ppaths are Dir instances with some File and Dir class methods mixed in
+  obj.read('content.xml')
+  => "<content/>"
+  obj.open('my_file.txt','w') { |io| io.write("Write text to file") }
+  obj.entries
+  => ["content.xml","my_file.txt"]
+  obj['*.xml']
+  => ["content.xml"]
+  obj.each { |file| ... }
+  obj.unlink('my_file.txt')
+  
+  # Delete a ppath and all its contents
+  pairtree.purge!('pfx:abc123def')
+</code></pre>
+  
+h2. Copyright
+
+Copyright (c) 2010 Chris Beer. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -1,52 +1,27 @@
-require 'rubygems'
-require 'bundler'
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-require 'rake'
+Dir.glob('lib/tasks/*.rake').each { |r| import r }
 
-require 'jeweler'
-Jeweler::Tasks.new do |gem|
-  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
-  gem.name = "pairtree"
-  gem.homepage = "http://github.com/cbeer/pairtree"
-  gem.license = "MIT"
-  gem.summary = %Q{Ruby Pairtree implementation}
-  gem.email = "chris@cbeer.info"
-  gem.authors = ["Chris Beer"]
-  # Include your dependencies below. Runtime dependencies are required when using your gem,
-  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
-  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
-  #  gem.add_development_dependency 'rspec', '> 1.2.3'
-end
-Jeweler::RubygemsDotOrgTasks.new
-
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-end
+require 'bundler/gem_tasks'
+require 'rake'
+require 'rspec/core/rake_task'
 
+begin
+  if RUBY_VERSION < "1.9"
 require 'rcov/rcovtask'
-Rcov::RcovTask.new do |test|
-  test.libs << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
+desc "Generate code coverage"
+RSpec::Core::RakeTask.new(:rcov) do |t|
+  t.pattern = "./spec/**/*_spec.rb" # don't need this, it's default.
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec', '--exclude', 'gems']
+end
+  end
+rescue
 end
 
-task :default => :test
-
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+RSpec::Core::RakeTask.new(:spec)
 
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "pairtree #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+task :clean do
+  puts 'Cleaning old coverage.data'
+  FileUtils.rm('coverage.data') if(File.exists? 'coverage.data')
 end
+
+task :default => [:rcov, :doc]

data/lib/pairtree.rb

@@ -2,6 +2,77 @@ require 'pairtree/identifier'
 require 'pairtree/path'
 require 'pairtree/obj'
 require 'pairtree/root'
-require 'pairtree/client'
+
+require 'fileutils'
+
 module Pairtree
+  class IdentifierError < Exception; end
+  class PathError < Exception; end
+  class VersionMismatch < Exception; end
+
+  SPEC_VERSION = 0.1
+  
+  ##
+  # Instantiate a pairtree at a given path location
+  # @param [String] path The path in which the pairtree resides
+  # @param [Hash] args Pairtree options
+  # @option args [String] :prefix (nil) the identifier prefix used throughout the pairtree
+  # @option args [String] :version (Pairtree::SPEC_VERSION) the version of the pairtree spec that this tree conforms to
+  # @option args [Boolean] :create (false) if true, create the pairtree and its directory structure if it doesn't already exist
+  def self.at path, args = {}
+    args = { :prefix => nil, :version => nil, :create => false }.merge(args)
+    args[:version] ||= SPEC_VERSION
+    args[:version] = args[:version].to_f
+    
+    root_path = File.join(path, 'pairtree_root')
+    prefix_file = File.join(path, 'pairtree_prefix')
+    version_file = File.join(path, pairtree_version_filename(args[:version]))
+    existing_version_file = Dir[File.join(path, "pairtree_version*")].sort.last
+    
+    if args.delete(:create)
+      if File.exists?(path) and not File.directory?(path)
+        raise PathError, "#{path} exists, but is not a valid pairtree root"
+      end
+      FileUtils.mkdir_p(root_path)
+
+      unless File.exists? prefix_file
+        File.open(prefix_file, 'w') { |f| f.write(args[:prefix].to_s) }
+      end
+      
+      if existing_version_file
+        if existing_version_file != version_file
+          stored_version = existing_version_file.scan(/([0-9]+)_([0-9]+)/).flatten.join('.').to_f
+          raise VersionMismatch, "Version #{args[:version]} specified, but #{stored_version} found."
+        end
+      else
+        args[:version] ||= SPEC_VERSION
+        version_file = File.join(path, pairtree_version_filename(args[:version]))
+        File.open(version_file, 'w') { |f| f.write %{This directory conforms to Pairtree Version #{args[:version]}. Updated spec: http://www.cdlib.org/inside/diglib/pairtree/pairtreespec.html} }
+        existing_version_file = version_file
+      end
+    else
+      unless File.directory? root_path
+        raise PathError, "#{path} does not point to an existing pairtree"
+      end
+    end
+
+    stored_prefix = File.read(prefix_file)
+    unless args[:prefix].nil? or args[:prefix].to_s == stored_prefix
+      raise IdentifierError, "Specified prefix #{args[:prefix].inspect} does not match stored prefix #{stored_prefix.inspect}"
+    end
+    args[:prefix] = stored_prefix
+
+    stored_version = existing_version_file.scan(/([0-9]+)_([0-9]+)/).flatten.join('.').to_f
+    args[:version] ||= stored_version
+    unless args[:version] == stored_version
+      raise VersionMismatch, "Version #{args[:version]} specified, but #{stored_version} found."
+    end
+        
+    Pairtree::Root.new(File.join(path, 'pairtree_root'), args)
+  end
+
+  private
+  def self.pairtree_version_filename(version)
+    "pairtree_version#{version.to_s.gsub(/\./,'_')}"
+  end
 end

data/lib/pairtree/identifier.rb

@@ -2,18 +2,31 @@ module Pairtree
   class Identifier
     ENCODE_REGEX = Regexp.compile("[\"*+,<=>?\\\\^|]|[^\x21-\x7e]", nil, 'u')
     DECODE_REGEX = Regexp.compile("\\^(..)", nil, 'u')
+
+    ##
+    # Encode special characters within an identifier
+    # @param [String] id The identifier
     def self.encode id
       id.gsub(ENCODE_REGEX) { |c| char2hex(c) }.tr('/:.', '=+,')
     end
 
+    ##
+    # Decode special characters within an identifier
+    # @param [String] id The identifier
     def self.decode id
       id.tr('=+,', '/:.').gsub(DECODE_REGEX) { |h| hex2char(h) } 
     end
 
+    ##
+    # Convert a character to its pairtree hexidecimal representation
+    # @param [Char] c The character to convert
     def self.char2hex c
       c.unpack('H*')[0].scan(/../).map { |x| "^#{x}"}
     end
 
+    ##
+    # Convert a pairtree hexidecimal string to its character representation
+    # @param [String] h The hexidecimal string to convert
     def self.hex2char h
        '' << h.delete('^').hex
     end

data/lib/pairtree/obj.rb

@@ -1,5 +1,52 @@
 module Pairtree  
   class Obj < ::Dir
+    
+    FILE_METHODS = [:atime, :open, :read, :file?, :directory?, :exist?, :exists?, :file?, :ftype, :lstat, 
+      :mtime, :readable?, :size, :stat, :truncate, :writable?, :zero?]
+    FILE_METHODS.each do |file_method|
+      define_method file_method do |fname,*args,&block|
+        File.send(file_method, File.join(self.path, fname), *args, &block)
+      end
+    end
 
+    def delete *args
+      File.delete(*(prepend_filenames(args)))
+    end
+    alias_method :unlink, :delete
+
+    def link *args
+      File.link(*(prepend_filenames(args)))
+    end
+
+    def rename *args
+      File.rename(*(prepend_filenames(args)))
+    end
+    
+    def utime atime, mtime, *args
+      File.utime(atime, mtime, *(prepend_filenames(args)))
+    end
+    
+    def entries
+      super - ['.','..']
+    end
+    
+    def each &block
+      super { |entry| yield(entry) unless entry =~ /^\.{1,2}$/ }
+    end
+    
+    def glob(string, flags = 0)
+      result = Dir.glob(File.join(self.path, string), flags) - ['.','..']
+      result.collect { |f| f.sub(%r{^#{self.path}/},'') }
+    end
+    
+    def [](string)
+      glob(string, 0)
+    end
+    
+    private
+    def prepend_filenames(files)
+      files.collect { |fname| File.join(self.path, fname) }
+    end
+    
   end
 end

data/lib/pairtree/path.rb

@@ -1,11 +1,50 @@
 module Pairtree
   class Path
+    @@leaf_proc = lambda { |id| id }
+    
+    def self.set_leaf value = nil, &block
+      if value.nil?
+        @@leaf_proc = block
+      else
+        if value.is_a?(Proc)
+          @@leaf_proc = value
+        else
+          @@leaf_proc = lambda { |id| value }
+        end
+      end
+    end
+    
+    def self.leaf id
+      if @@leaf_proc
+        Pairtree::Identifier.encode(@@leaf_proc.call(id))
+      else
+        ''
+      end
+    end
+    
     def self.id_to_path id
-      File.join(Pairtree::Identifier.encode(id).scan(/..?/))
+      path = File.join(Pairtree::Identifier.encode(id).scan(/..?/),self.leaf(id))
+      path.sub(%r{#{File::SEPARATOR}+$},'')
     end
 
     def self.path_to_id ppath
-      Pairtree::Identifier.decode(ppath.split(File::SEPARATOR).join)
+      parts = ppath.split(File::SEPARATOR)
+      parts.pop if @@leaf_proc and parts.last.length > Root::SHORTY_LENGTH
+      Pairtree::Identifier.decode(parts.join)
+    end
+    
+    def self.remove! path
+      FileUtils.remove_dir(path, true)
+      parts = path.split(File::SEPARATOR)
+      parts.pop
+      while parts.length > 0 and parts.last != 'pairtree_root'
+        begin
+          FileUtils.rmdir(parts.join(File::SEPARATOR))
+          parts.pop
+        rescue SystemCallError
+          break
+        end
+      end
     end
   end
 end

data/lib/pairtree/root.rb

@@ -1,10 +1,15 @@
-require 'find'
 require 'fileutils'
 module Pairtree
   class Root
     SHORTY_LENGTH = 2
 
-    attr_reader :root
+    attr_reader :root, :prefix
+    
+    ##
+    # @param [String] root The pairtree_root directory within the pairtree home
+    # @param [Hash] args Pairtree options
+    # @option args [String] :prefix (nil) the identifier prefix used throughout the pairtree
+    # @option args [String] :version (Pairtree::SPEC_VERSION) the version of the pairtree spec that this tree conforms to
     def initialize root, args = {}
       @root = root
       
@@ -14,44 +19,85 @@ module Pairtree
       @options = args
     end
 
+    ##
+    # Get a list of valid existing identifiers within the pairtree
+    # @return [Array]
     def list          
       objects = []
-      return [] unless pairtree_root? @root
+      return [] unless File.directory? @root
 
       Dir.chdir(@root) do
-      Find.find(*Dir.entries('.').reject { |x| x =~ /^\./ }) do |path|
-        if File.directory? path
-          Find.prune if File.basename(path).length > @shorty_length
-	  objects << path if Dir.entries(path).any? { |f| f.length > @shorty_length or File.file? File.join(path, f) }
-	  next
+        possibles = Dir['**/?'] + Dir['**/??']
+        possibles.each { |path|
+          contents = Dir.entries(path).reject { |x| x =~ /^\./ }
+          objects << path unless contents.all? { |f| f.length <= @shorty_length and File.directory?(File.join(path, f)) }
+        }
       end
-	end
-      end
-
       objects.map { |x| @prefix + Pairtree::Path.path_to_id(x) }
     end
 
-    def mk id
-      id.sub! @prefix, ''
-      path = File.join(@root, Pairtree::Path.id_to_path(id))
-      FileUtils.mkdir_p path
-      Pairtree::Obj.new path
+    ##
+    # Get the path containing the pairtree_root
+    # @return [String]
+    def path
+      File.dirname(root)
+    end
+    
+    ##
+    # Get the full path for a given identifier (whether it exists or not)
+    # @param [String] id The full, prefixed identifier
+    # @return [String]
+    def path_for id
+      unless id.start_with? @prefix
+        raise IdentifierError, "Identifier must start with #{@prefix}"
+      end
+      path_id = id[@prefix.length..-1]
+      File.join(@root, Pairtree::Path.id_to_path(path_id))
     end
 
+    ##
+    # Determine if a given identifier exists within the pairtree
+    # @param [String] id The full, prefixed identifier
+    # @return [Boolean]
+    def exists? id
+      File.directory?(path_for(id))
+    end
+    
+    ##
+    # Get an existing ppath
+    # @param [String] id The full, prefixed identifier
+    # @return [Pairtree::Obj] The object encapsulating the identifier's ppath
     def get id
-      id.sub! @prefix, ''
-      path = File.join(@root, Pairtree::Path.id_to_path(id))
-      Pairtree::Obj.new path if File.directory? path
+      Pairtree::Obj.new path_for(id)
     end
-
-    private
-
-    def pairtree_root
-      Dir.new @root
+    alias_method :[], :get
+    
+    ##
+    # Create a new ppath
+    # @param [String] id The full, prefixed identifier
+    # @return [Pairtree::Obj] The object encapsulating the newly created ppath
+    def mk id
+      FileUtils.mkdir_p path_for(id)
+      get(id)
+    end
+    
+    ##
+    # Delete a ppath
+    # @param [String] id The full, prefixed identifier
+    # @return [Boolean]
+    def purge! id
+      if exists?(id)
+        Pairtree::Path.remove!(path_for(id))
+      end
+      not exists?(id)
     end
 
-    def pairtree_root? path = @root
-      File.directory? path
+    ##
+    # Get the version of the pairtree spec that this pairtree conforms to
+    # @return [String]
+    def pairtree_version
+      @options[:version]
     end
+    
   end
 end