data_paths 0.2.1

data/.gitignore

@@ -0,0 +1,8 @@
+pkg
+doc
+web
+tmp
+.DS_Store
+.yardoc
+*.swp
+*~

data/.specopts

@@ -0,0 +1 @@
+--colour --format specdoc

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title 'DataPaths Documentation' --protected --files ChangeLog.md,LICENSE.txt

data/ChangeLog.md

@@ -0,0 +1,13 @@
+### 0.2.1 / 2010-04-13
+
+* Minor bug-fix in {DataPaths::Methods#unregister_data_dirs!}.
+
+### 0.2.0 / 2010-04-13
+
+* Renamed the static_paths gem to data_paths, since the `data/` directory
+  is the prefered directory for storing static-content in Ruby libraries.
+
+### 0.1.0 / 2010-01-22
+
+* Initial release:
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+
+Copyright (c) 2010 Hal Brodigan
+
+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,84 @@
+# data_paths
+
+* http://data_paths.rubyforge.org/
+* http://github.com/postmodern/data_paths
+* http://github.com/postmodern/data_paths/issues
+* Postmodern (postmodern.mod3 at gmail.com)
+
+## DESCRIPTION:
+
+DataPaths is a library to manage the paths of directories containing
+static-content across multiple libraries.
+
+For example, DataPaths can manage the `data/` directories of
+multiple RubyGems, in much the same way RubyGems manages the paths of
+`lib/` directories using `$LOAD_PATH`.
+
+## FEATURES:
+
+* Allows libraries to register static-content directories using the
+  `register_data_dir` class or instance method.
+* Allows libraries to unregister a single path using
+  `unregister_data_dir` or all paths registered by that library with
+  `unregister_data_dirs`.
+* Provides helper methods in {DataPaths::Finders} for searching through
+  the registered static-content directories.
+* Does not use global variables.
+
+## EXAMPLES:
+
+Register a directory containing static-content:
+
+    require 'data_paths'
+    
+    module MyLibrary
+      include DataPaths
+    
+      # define the data dir(s)
+      register_data_dir File.join(File.dirname(__FILE__),'..','..','data')
+    end
+
+List previously registered static-content directories:
+
+    # all data directories
+    DataPaths.paths
+    # => #<Set: {...}>
+
+    # the data directories registeed in MyLibrary
+    MyLibrary.data_paths
+    # => #<Set: {...}>
+
+    # list data directories registered in an object
+    lib = MyLibrary.new
+    lib.register_data_dir File.join('path','to','data')
+
+    lib.data_paths
+    # => #<Set: {...}>
+
+Using {DataPaths::Finders} to access content from within the
+static-content directories:
+
+    module MyLibrary
+      class UsesContent
+    
+        include DataPaths::Finders
+    
+        def index
+          find_data_file('index.html')
+        end
+
+        def file_dirs
+          all_data_dirs('extra')
+        end
+    
+      end
+    end
+
+## INSTALL:
+
+    $ sudo gem install data_paths
+
+## LICENSE:
+
+See {file:LICENSE.txt} for license information.
+

data/Rakefile

@@ -0,0 +1,41 @@
+require 'rubygems'
+require 'rake'
+require './lib/data_paths/version.rb'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = 'data_paths'
+    gem.version = DataPaths::VERSION
+    gem.summary = %Q{DataPaths is a library to manage the paths of directories containing static-content across multiple libraries.}
+    gem.description = %Q{DataPaths is a library to manage the paths of directories containing static-content across multiple libraries. For example, DataPaths can manage the `data/` directories of multiple RubyGems, in much the same way RubyGems manages the paths of `lib/` directories using `$LOAD_PATH`.}
+    gem.email = 'postmodern.mod3@gmail.com'
+    gem.homepage = 'http://github.com/postmodern/data_paths'
+    gem.authors = ['Postmodern']
+    gem.add_development_dependency 'rspec', '>= 1.3.0'
+    gem.add_development_dependency 'yard', '>= 0.5.3'
+    gem.has_rdoc = 'yard'
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs += ['lib', 'spec']
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+  spec.spec_opts = ['--options', '.specopts']
+end
+
+task :spec => :check_dependencies
+task :default => :spec
+
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yard do
+    abort "YARD is not available. In order to run yard, you must: gem install yard"
+  end
+end

data/data_paths.gemspec

@@ -0,0 +1,75 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{data_paths}
+  s.version = "0.2.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Postmodern"]
+  s.date = %q{2010-04-13}
+  s.description = %q{DataPaths is a library to manage the paths of directories containing static-content across multiple libraries. For example, DataPaths can manage the `data/` directories of multiple RubyGems, in much the same way RubyGems manages the paths of `lib/` directories using `$LOAD_PATH`.}
+  s.email = %q{postmodern.mod3@gmail.com}
+  s.extra_rdoc_files = [
+    "ChangeLog.md",
+     "LICENSE.txt",
+     "README.md"
+  ]
+  s.files = [
+    ".gitignore",
+     ".specopts",
+     ".yardopts",
+     "ChangeLog.md",
+     "LICENSE.txt",
+     "README.md",
+     "Rakefile",
+     "data_paths.gemspec",
+     "lib/data_paths.rb",
+     "lib/data_paths/data_paths.rb",
+     "lib/data_paths/finders.rb",
+     "lib/data_paths/methods.rb",
+     "lib/data_paths/version.rb",
+     "spec/classes/data_class.rb",
+     "spec/data_paths_spec.rb",
+     "spec/finders_spec.rb",
+     "spec/helpers/data.rb",
+     "spec/helpers/data1/dir/two.txt",
+     "spec/helpers/data1/one.txt",
+     "spec/helpers/data2/dir/two.txt",
+     "spec/methods_examples.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.has_rdoc = %q{yard}
+  s.homepage = %q{http://github.com/postmodern/data_paths}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{DataPaths is a library to manage the paths of directories containing static-content across multiple libraries.}
+  s.test_files = [
+    "spec/finders_spec.rb",
+     "spec/methods_examples.rb",
+     "spec/spec_helper.rb",
+     "spec/helpers/data.rb",
+     "spec/classes/data_class.rb",
+     "spec/data_paths_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.3.0"])
+      s.add_development_dependency(%q<yard>, [">= 0.5.3"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.3.0"])
+      s.add_dependency(%q<yard>, [">= 0.5.3"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.3.0"])
+    s.add_dependency(%q<yard>, [">= 0.5.3"])
+  end
+end
+

data/lib/data_paths/data_paths.rb

@@ -0,0 +1,21 @@
+require 'data_paths/methods'
+
+require 'set'
+
+module DataPaths
+  include Methods
+
+  def self.included(base)
+    base.extend Methods
+  end
+
+  #
+  # The registered `data/` directories.
+  #
+  # @return [Set]
+  #   The directories which contain static content.
+  #
+  def DataPaths.paths
+    @@data_paths ||= Set[]
+  end
+end

data/lib/data_paths/finders.rb

@@ -0,0 +1,195 @@
+require 'data_paths/data_paths'
+
+require 'enumerator'
+
+module DataPaths
+  module Finders
+    include Enumerable
+
+    #
+    # Passes all existing data paths for the specified path,
+    # within the data directories, to the given block.
+    #
+    # @param [String] path
+    #   The path to search for in all data directories.
+    #
+    # @yield [potential_path]
+    #   The given block will be passed every existing combination of the
+    #   given path and the data directories.
+    #
+    # @yieldparam [String] potential_path
+    #   An existing data path.
+    #
+    def each_data_path(path,&block)
+      DataPaths.paths.each do |dir|
+        full_path = File.join(dir,path)
+
+        block.call(full_path) if File.exists?(full_path)
+      end
+    end
+
+    #
+    # Searches for the given path within any data directory.
+    #
+    # @param [String] path
+    #   The path to search for.
+    #
+    # @return [String, nil]
+    #   Returns the first valid match for the given path within a data 
+    #   directory. Returns `nil` if the given path could not be found
+    #   in any data directory.
+    #
+    def find_data_path(path)
+      enum_for(:each_data_path,path).first
+    end
+
+    #
+    # Searches for a file at the given path, within any data directory.
+    #
+    # @param [String] path
+    #   The file path to search for.
+    #
+    # @return [String, nil]
+    #   Returns the first valid file at the given path within a data
+    #   directory. Returns `nil` if the given path could not be found
+    #   in any data directory.
+    #
+    def find_data_file(path)
+      each_data_path(path) do |full_path|
+        return full_path if File.file?(full_path)
+      end
+
+      return nil
+    end
+
+    #
+    # Searches for a directory at the given path, within any data
+    # directory.
+    #
+    # @param [String] path
+    #   The directory path to search for.
+    #
+    # @return [String, nil]
+    #   Returns the first valid directory at the given path within a
+    #   data directory. Returns `nil` if the given path could not be
+    #   found in any data directory.
+    #
+    def find_data_dir(path)
+      each_data_path(path) do |full_path|
+        return full_path if File.directory?(full_path)
+      end
+
+      return nil
+    end
+
+    #
+    # Finds all occurrences of a given path, within all data directories.
+    #
+    # @param [String] path
+    #   The path to search for.
+    #
+    # @return [Array<String>]
+    #   The occurrences of the given path within all data directories.
+    #
+    def all_data_paths(path)
+      enum_for(:each_data_path,path).to_a
+    end
+
+    #
+    # Finds all occurrences of a given file path, within all data
+    # directories.
+    #
+    # @param [String] path
+    #   The file path to search for.
+    #
+    # @yield [data_file]
+    #   If a block is given, it will be passed every found path.
+    #
+    # @yieldparam [String] data_file
+    #   The path of a file within a data directory.
+    #
+    # @return [Array<String>]
+    #   The occurrences of the given file path within all data
+    #   directories.
+    #
+    def each_data_file(path,&block)
+      each_data_path(path) do |full_path|
+        block.call(full_path) if File.file?(full_path)
+      end
+    end
+
+    #
+    #
+    # Finds all occurrences of a given file path, within all data
+    # directories.
+    #
+    # @param [String] path
+    #   The file path to search for.
+    #
+    # @return [Array<String>]
+    #   The occurrences of the given file path within all data
+    #   directories.
+    #
+    def all_data_files(path)
+      enum_for(:each_data_file,path).to_a
+    end
+
+    #
+    # Finds all occurrences of a given directory path, within all data
+    # directories.
+    #
+    # @param [String] path
+    #   The directory path to search for.
+    #
+    # @yield [data_dir]
+    #   If a block is given, it will be passed every found path.
+    #
+    # @yieldparam [String] data_dir
+    #   The path of a directory within a data directory.
+    #
+    # @return [Array<String>]
+    #   The occurrences of the given directory path within all data
+    #   directories.
+    #
+    def each_data_dir(path,&block)
+      each_data_path(path) do |full_path|
+        block.call(full_path) if File.directory?(full_path)
+      end
+    end
+
+    #
+    # Finds all occurrences of a given directory path, within all data
+    # directories.
+    #
+    # @param [String] path
+    #   The directory path to search for.
+    #
+    # @return [Array<String>]
+    #   The occurrences of the given directory path within all data
+    #   directories.
+    #
+    def all_data_dirs(path)
+      enum_for(:each_data_dir,path).to_a
+    end
+
+    #
+    # Finds all paths that match a given pattern, within all data
+    # directories.
+    #
+    # @param [String] pattern
+    #   The path glob pattern to search with.
+    #
+    # @return [Array<String>]
+    #   The matching paths found within all data directories.
+    #
+    def data_glob(pattern)
+      paths = []
+
+      DataPaths.paths.each do |path|
+        paths += Dir[File.join(path,pattern)]
+      end
+
+      return paths
+    end
+  end
+end

data/lib/data_paths/methods.rb

@@ -0,0 +1,70 @@
+require 'set'
+
+module DataPaths
+  module Methods
+    #
+    # The directories registered within a specific module or class.
+    #
+    # @return [Set]
+    #   The directories registered so far.
+    #
+    def data_paths
+      @data_paths ||= Set[]
+    end
+
+    #
+    # Registers a path as a data directory.
+    #
+    # @param [String] path
+    #   The path to add to {DataPaths.paths}.
+    #
+    # @return [String]
+    #   The fully qualified form of the specified path.
+    #
+    # @example
+    #   register_data_dir File.join(File.dirname(__FILE__),'..','..','..','data')
+    #
+    # @raise [RuntimeError]
+    #   The specified path is not a directory.
+    #
+    def register_data_dir(path)
+      path = File.expand_path(path)
+
+      unless File.directory?(path)
+        raise(RuntimeError,"#{path.dump} must be a directory")
+      end
+
+      self.data_paths << path
+
+      DataPaths.paths << path
+      return path
+    end
+
+    #
+    # Unregisters any matching data directories.
+    #
+    # @param [String] path
+    #   The path to unregistere.
+    #
+    # @return [true]
+    #
+    def unregister_data_dir!(path)
+      path = File.expand_path(path)
+
+      self.data_paths.reject! { |dir| dir == path }
+      DataPaths.paths.reject! { |dir| dir == path }
+      return true
+    end
+
+    #
+    # Unregisters all previously registered data directories.
+    #
+    # @return [true]
+    #
+    def unregister_data_dirs!
+      DataPaths.paths.reject! { |dir| self.data_paths.include?(dir) }
+      self.data_paths.clear
+      return true
+    end
+  end
+end

data/lib/data_paths/version.rb

@@ -0,0 +1,4 @@
+module DataPaths
+  # data_paths version
+  VERSION = '0.2.1'
+end

data/lib/data_paths.rb

@@ -0,0 +1,3 @@
+require 'data_paths/finders'
+require 'data_paths/data_paths'
+require 'data_paths/version'

data/spec/classes/data_class.rb

@@ -0,0 +1,8 @@
+require 'data_paths/finders'
+
+class DataClass
+
+  include DataPaths
+  include DataPaths::Finders
+
+end

data/spec/data_paths_spec.rb

@@ -0,0 +1,26 @@
+require 'data_paths/data_paths'
+
+require 'spec_helper'
+require 'helpers/data'
+require 'classes/data_class'
+require 'methods_examples'
+
+describe DataPaths do
+  describe "instance methods" do
+    include DataPaths
+
+    before(:all) do
+      @context = self
+    end
+
+    it_should_behave_like "Methods"
+  end
+
+  describe "class methods" do
+    before(:all) do
+      @context = DataClass
+    end
+
+    it_should_behave_like "Methods"
+  end
+end

data/spec/finders_spec.rb

@@ -0,0 +1,39 @@
+require 'data_paths/finders'
+
+require 'spec_helper'
+require 'helpers/data'
+
+describe DataPaths::Finders do
+  before(:all) do
+    @example = DataClass.new
+  end
+
+  it "should find a file" do
+    @example.find_data_file('one.txt').should == File.join(Helpers::DATA_DIRS[0],'one.txt')
+  end
+
+  it "should find a directory" do
+    @example.find_data_dir('dir').should == File.join(Helpers::DATA_DIRS[0],'dir')
+  end
+
+  it "should find all matching files" do
+    @example.all_data_files('dir/two.txt').should == [
+      File.join(Helpers::DATA_DIRS[0],'dir','two.txt'),
+      File.join(Helpers::DATA_DIRS[1],'dir','two.txt')
+    ]
+  end
+
+  it "should find all matching directories" do
+    @example.all_data_dirs('dir').should == [
+      File.join(Helpers::DATA_DIRS[0],'dir'),
+      File.join(Helpers::DATA_DIRS[1],'dir')
+    ]
+  end
+
+  it "should find all paths matching a pattern" do
+    @example.data_glob('*/*.txt').should == [
+      File.join(Helpers::DATA_DIRS[0],'dir','two.txt'),
+      File.join(Helpers::DATA_DIRS[1],'dir','two.txt')
+    ]
+  end
+end

data/spec/helpers/data.rb

@@ -0,0 +1,12 @@
+require 'data_paths/data_paths'
+
+module Helpers
+  include DataPaths
+
+  DATA_DIRS = [
+    File.expand_path(File.join(File.dirname(__FILE__),'data1')),
+    File.expand_path(File.join(File.dirname(__FILE__),'data2')),
+  ]
+
+  DATA_DIRS.each { |dir| register_data_dir dir }
+end

data/spec/methods_examples.rb

@@ -0,0 +1,30 @@
+require 'data_paths/data_paths'
+
+require 'spec_helper'
+require 'helpers/data'
+
+shared_examples_for "Methods" do
+  before(:all) do
+    Helpers::DATA_DIRS.each do |dir|
+      @context.register_data_dir dir
+    end
+  end
+
+  it "should list data directories" do
+    Helpers::DATA_DIRS.each do |dir|
+      @context.data_paths.should include(dir)
+    end
+  end
+
+  it "should prevent the addition of non-existant directories" do
+    lambda {
+      @context.register_data_dir 'lol'
+    }.should raise_error(RuntimeError)
+  end
+
+  it "should prevent the addition of non-directories" do
+    lambda {
+      @context.register_data_dir __FILE__
+    }.should raise_error(RuntimeError)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'rubygems'
+gem 'rspec', '>=1.2.9'
+require 'spec'
+
+require 'data_paths/version'

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification 
+name: data_paths
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 1
+  version: 0.2.1
+platform: ruby
+authors: 
+- Postmodern
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-13 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 5
+        - 3
+        version: 0.5.3
+  type: :development
+  version_requirements: *id002
+description: DataPaths is a library to manage the paths of directories containing static-content across multiple libraries. For example, DataPaths can manage the `data/` directories of multiple RubyGems, in much the same way RubyGems manages the paths of `lib/` directories using `$LOAD_PATH`.
+email: postmodern.mod3@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- ChangeLog.md
+- LICENSE.txt
+- README.md
+files: 
+- .gitignore
+- .specopts
+- .yardopts
+- ChangeLog.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- data_paths.gemspec
+- lib/data_paths.rb
+- lib/data_paths/data_paths.rb
+- lib/data_paths/finders.rb
+- lib/data_paths/methods.rb
+- lib/data_paths/version.rb
+- spec/classes/data_class.rb
+- spec/data_paths_spec.rb
+- spec/finders_spec.rb
+- spec/helpers/data.rb
+- spec/helpers/data1/dir/two.txt
+- spec/helpers/data1/one.txt
+- spec/helpers/data2/dir/two.txt
+- spec/methods_examples.rb
+- spec/spec_helper.rb
+has_rdoc: yard
+homepage: http://github.com/postmodern/data_paths
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: DataPaths is a library to manage the paths of directories containing static-content across multiple libraries.
+test_files: 
+- spec/finders_spec.rb
+- spec/methods_examples.rb
+- spec/spec_helper.rb
+- spec/helpers/data.rb
+- spec/classes/data_class.rb
+- spec/data_paths_spec.rb