orchard 0.1

data/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2010, Regents of the University of California
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+     * Redistributions of source code must retain the above copyright
+       notice, this list of conditions and the following disclaimer.
+     * Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+     * Neither the name of the University of California nor the names of
+       its contributors may be used to endorse or promote products derived
+       from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OF THE UNIVERSITY
+OF CALIFORNIA BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,21 @@
+Orchard is a Ruby library for working with Pairtrees, a filesystem hierarchy 
+mapping identifiers to object directories.
+
+More information can be found at:
+
+  Pairtrees for Object Storage
+  https://confluence.ucop.edu/display/Curation/PairTree
+
+==== Usage Examples
+
+  Pairtree.encode('ark:/13030/xt12t3')
+  # => ark+=13030=xt12t3
+
+  Pairtree.decode('ark+=13030=xt12t3')
+  # => ark:/13030/xt12t3
+
+  Pairtree.id_to_ppath('ark:/13030/xt12t3')
+  # => ar/k+/=1/30/30/=x/t1/2t/3
+
+  Pairtree.ppath_to_id('ar/k+/=1/30/30/=x/t1/2t/3')
+  # => ark:/13030/xt12t3

data/lib/orchard.rb

@@ -0,0 +1,29 @@
+require 'orchard/pairtree'
+require 'orchard/version'
+
+# Orchard is a Ruby library for working with Pairtrees, a filesystem hierarchy 
+# mapping identifiers to object directories.
+#
+# More information can be found at:
+#
+#   Pairtrees for Object Storage
+#   https://confluence.ucop.edu/display/Curation/PairTree
+# 
+# ==== Usage Examples
+#
+#   Pairtree.encode('ark:/13030/xt12t3')
+#   # => ark+=13030=xt12t3
+#
+#   Pairtree.decode('ark+=13030=xt12t3')
+#   # => ark:/13030/xt12t3
+#
+#   Pairtree.id_to_ppath('ark:/13030/xt12t3')
+#   # => ar/k+/=1/30/30/=x/t1/2t/3
+#
+#   Pairtree.ppath_to_id('ar/k+/=1/30/30/=x/t1/2t/3')
+#   # => ark:/13030/xt12t3
+
+module Orchard
+  class InvalidPPathError < StandardError
+  end
+end

data/lib/orchard/pairtree.rb

@@ -0,0 +1,175 @@
+module Orchard
+  # Provides a set of methods for working with Pairtree paths.
+  class Pairtree
+    MAX_SHORTY = 2
+    ENCODE_REGEX = /[\"*+,<=>?\\^|]|[^\x21-\x7e]/u
+    DECODE_REGEX = /\^(..)|(.)/u
+    PPATH_REGEX = /^(?:pairtree_root\/)?((?>[^:\/\.|.]{2}\/)*[^:\/\.|.]{1,2})(?:\/?$)/
+    CHAR_ENCODE_CONV = {'/'=>'=',':'=>'+','.'=>','}
+    CHAR_DECODE_CONV = {'='=>'/','+'=>':',','=>'.'}
+    
+    # Encodes a given +id+ <em>(String)</em> according to the "identifier string 
+    # cleaning" in the pairtree 0.1 specification. 
+    #
+    #   encode(id)
+    #
+    # ==== Examples
+    #
+    #   Pairtree.encode('ark:/13030/xt12t3')
+    #   # => ark+=13030=xt12t3
+    #
+    #   Pairtree.encode('http://n2t.info/urn:nbn:se:kb:repos-1')
+    #   # => http+==n2t,info=urn+nbn+se+kb+repos-1
+    #
+    #   Pairtree.encode('what-the-*@?#!^!?')
+    #   # => what-the-^2a@^3f#!^5e!^3f
+    #
+    # ==== Explanation (From Pairtree 0.1 Specification)
+    #
+    #   Identifier string cleaning
+    #
+    #   Prior to splitting into character pairs, identifier strings are cleaned in 
+    #   two separate steps. One step would be simpler, but pairtree is designed so 
+    #   that commonly used characters in reasonably opaque identifiers (e.g., not 
+    #   containing natural language words, phrases, or hints) result in reasonably 
+    #   short and familiar-looking paths. For completeness, the pairtree  algorithm 
+    #   specifies what to do with all possible UTF-8 characters, and relies for this 
+    #   on a kind of URL hex-encoding. To avoid conflict with URLs, pairtree 
+    #   hex-encoding is introduced with the '^' character instead of '%'.
+    #
+    #   First, the identifier string is cleaned of characters that are expected to 
+    #   occur rarely in object identifiers but that would cause certain known 
+    #   problems for file systems. In this step, every UTF-8 octet outside the range 
+    #   of visible ASCII (94 characters with hexadecimal codes 21-7e) [ASCII], as 
+    #   well as the following visible ASCII characters, must be converted to 
+    #   their corresponding 3-character hexadecimal encoding, ^hh, where ^ is a 
+    #   circumflex and hh is two hex digits. For example, ' ' (space) is converted 
+    #   to ^20 and '*' to ^2a. In the second step, the following single-character to 
+    #   single-character conversions must be done. These are characters that occur 
+    #   quite commonly in opaque identifiers but present special problems for 
+    #   filesystems. This step avoids requiring them to be hex encoded (hence 
+    #   expanded to three characters), which keeps the typical ppath reasonably 
+    #   short. Here are examples of identifier strings after cleaning and after 
+    #   ppath mapping.
+    # 
+    def self.encode(id)
+      #first pass
+      first_pass_id = id.gsub(ENCODE_REGEX) { |m| m.bytes.map{|b| "^%02x"%b }.join}
+    
+      # second pass
+      second_pass_id = first_pass_id.split(//).collect { |char| CHAR_ENCODE_CONV[char] || char}.join
+    end 
+
+    # Decodes a given +id+ <em>(String)</em>according to the pairtree 0.1 specifiaation. 
+    #
+    #   encode(id)
+    #
+    # ==== Examples
+    #
+    #   Pairtree.decode('ark+=13030=xt12t3')
+    #   # => ark:/13030/xt12t3
+    #
+    #   Pairtree.decode('http+==n2t,info=urn+nbn+se+kb+repos-1')
+    #   # => http://n2t.info/urn:nbn:se:kb:repos-1
+    #
+    #   Pairtree.decode('what-the-^2a@^3f#!^5e!^3f')
+    #   # => what-the-*@?#!^!?
+    #
+    def self.decode(id)
+      # first pass (reverse second from encode)
+      first_pass_id = id.split(//).collect { |char| CHAR_DECODE_CONV[char] || char}.join
+    
+      # second pass (reverse first from encode)
+      second_pass_id = first_pass_id.scan(DECODE_REGEX).map {|coded,chr| coded.nil? ? chr.ord : coded.hex}.pack('C*').force_encoding('utf-8')
+    end
+
+    # Constructs the pairpath for a given +id+ <em>(String)</em> and +options+. 
+    #
+    #   id_to_ppath(id, options = {})
+    #
+    # ==== Options
+    # * <tt>:prefix => Pairtree prefix</tt> - This will remove the prefix from the id
+    #   before creating a pairpath.
+    #
+    # ==== Examples
+    #
+    #   Pairtree.id_to_ppath('abcde')
+    #   # => ab/cd/e
+    #
+    # or with the prefix option
+    #
+    #   Pairtree.id_to_ppath('http://dom.org/abcde', :prefix => 'http://dom.org/')
+    #   # => ab/cd/e
+    #
+    # ==== Explanation (From Pairtree 0.1 Specification) The basic pairtree algorithm
+    #
+    #   The pairtree algorithm maps an arbitrary UTF-8 [RFC3629] encoded identifier 
+    #   string into a filesystem directory path based on successive pairs of 
+    #   characters, and also defines the reverse mapping (from pathname to 
+    #   identifier).
+    #
+    #   In this document the word "directory" is used interchangeably with the word 
+    #   "folder" and all examples conform to Unix-based filesystem conventions which 
+    #   should tranlate easily to Windows conventions after substituting the path 
+    #   separator ('\' instead of '/'). Pairtree places no limitations on file and 
+    #   pathlengths, so implementors thinking about maximal interoperation may 
+    #   wish to consider the issues listed in the Interoperability section of 
+    #   this document.
+    #
+    #   The mapping from identifier string to path has two parts. First, the string 
+    #   is cleaned by converting characters that would be illegal or especially 
+    #   problemmaticin Unix or Windows filesystems. The cleaned string is then 
+    #   split into pairs of characters, each of which becomes a directory name 
+    #   in a filesystem path: successive pairs map to successive path components 
+    #   until there are no characters left, with the last component being either 
+    #   a 1- or 2-character directory name. The resulting path is known as 
+    #   a pairpath, or ppath.
+    #
+    #   abcd	-> ab/cd/ 
+    #   abcdefg	-> ab/cd/ef/g/ 
+    #   12-986xy4 -> 12/-9/86/xy/4/
+    #
+    def self.id_to_ppath(*args)
+      id = args[0]
+      options = args[1] || {}
+      id.sub!(/^#{options[:prefix]}/,'') unless options[:prefix].nil?
+      self.string_to_dirpath(self.encode(id), MAX_SHORTY)
+    end
+
+    # Reconstructs the id for a given +pairpath+ and +options+. 
+    #
+    #   ppath_to_id(id, options = {})
+    #     # id is a String
+    #
+    # ==== Options
+    # * <tt>:prefix => Pairtree prefix</tt> - This will remove the prefix from the id
+    #   before creating a pairpath.
+    #
+    # ==== Examples
+    #
+    #   Pairtree.ppath_to_id('ab/cd/e')
+    #   # => abcde
+    #
+    # or with the prefix option
+    #
+    #   Pairtree.ppath_to_id('ab/cd/e', :prefix => 'http://dom.org/')
+    #   # => http://dom.org/abcde
+    #  
+    def self.ppath_to_id(*args)
+      ppath = args[0]
+      options = args[1] || {}
+      match = ppath.match(PPATH_REGEX)
+      if match.nil? 
+        throw InvalidPPathError 
+      end
+      id = self.decode(match[1].delete('/'))
+      options[:prefix].nil? ? id : options[:prefix] + id
+    end
+    
+    private
+    # Internal - split a string into a directory path by shorty length.
+    def self.string_to_dirpath(s, dir_length_max)
+      s.gsub(/(.{#{dir_length_max}}|.{1,#{dir_length_max}}$)/) { |m| $1.nil? ? m : m + '/' }
+    end
+  end
+end

data/lib/orchard/version.rb

@@ -0,0 +1,3 @@
+module Orchard
+  VERSION = '0.1'
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: orchard
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  version: "0.1"
+platform: ruby
+authors: 
+- Stephanie Collett
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-17 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: Orchard translates id strings to/from Pairtree paths for use with Pairtree file repositories.
+email: 
+- stephanie.collett@ucop.edu
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/orchard/pairtree.rb
+- lib/orchard/version.rb
+- lib/orchard.rb
+- LICENSE
+- README.md
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Pairtree implmentation for Ruby
+test_files: []
+