required 0.1.0

data/README

@@ -0,0 +1,97 @@
+= Required, a utility to require all files in a directory
+
+Required provides the ability to <b>require</b> all files within a
+<b>d</b>irectory, with options for file inclusion/exclusion based on pattern
+matching, as well as recursive descent. An array of all the files that were
+loaded ('require' only loads a file the first time) are returned.
+
+== Quick start
+
+First pull in the 'required' module:
+    require 'required'
+
+To pull in all ruby files in a directory (this excludes subdirectories):
+
+    required "some/path/to/dir"
+
+Same as before, but require the files in reverse alphanumeric order:
+
+    required "some/path/to/dir", :sort => lambda { |x, y| y <=> x}
+
+To pull in files from multiple directories:
+
+    required ["some/path/to/dir", "another/path/another/dir"]
+
+Or to recurse through subdirectories, requiring all files along the way:
+
+    required "lib", {:recurse => true}
+
+Same as before, but exclude ruby files tagged as "_old":
+
+    required "lib", {:recurse => true, :exclude => /_old/}
+    # Will not require "lib/extensions/string_old.rb"
+
+Same as before, but only require ruby files tagged with "_new":
+
+    required "lib", {:recurse => true, :include => /_new/}
+
+== Installing with RubyGems
+
+A Gem of Required is available at gemcutter.org.  You can install it with:
+
+    gem install required
+
+== Running the tests
+
+Testing Required requires the shoulda testing framework:
+
+    gem install shoulda
+
+There is one rake-based test task:
+
+    rake test       runs all the tests
+
+== History
+
+* 2010-02-23: First public release 0.1.
+
+== Contact
+
+Git repository (send Git patches to the mailing list):
+* http://github.com/required
+
+== Thanks
+
+I would like to thank Ryan Wilcox for coming up with the initial idea and
+implementation of a convenience method for requiring everything in a directory
+for a project we work on.
+
+== Copyright
+
+Copyright (C) 2010 Arild Shirazi
+
+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 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.
+
+== Links
+
+Required:: <http://blog.codesherpas.com/>
+Required's Rubyforge project:: <http://rubyforge.org/projects/required>
+Official Required repository:: <http://github.com/required>
+
+Arild Shirazi:: <http://setup-a-personal-site-quick.com/>
+

data/lib/required.rb

@@ -0,0 +1,51 @@
+module Kernel
+
+  # Searches through the given directory or array of directories, and will
+  # `require` all ruby files found.  Returns an array of files that were
+  # actually loaded in the order which they were loaded.
+  # Available options:
+  #   :recurse => [true|false]         # Descend into subdirectories or not
+  #   :include => /filename_pattern/   # Only require files matching this regex
+  #   :exclude => /filename_pattern/   # Don't require files matching this regex
+  #   :sort => lambda { |x, y| y <=> x }
+  #                # Specify a custom sort order for files within each directory
+  #
+  # Note: required files are loaded only once.
+  def required(directories, options={})
+    validate_options(options)
+    loaded_files = []
+    directories.each do |directory|
+      next unless File.directory? directory
+      loaded_files << require_within(directory, options)
+
+      next unless options[:recurse]
+      sub_dirs = Dir["#{directory}/*"].select { |d| File.directory? d }
+      options[:sort] ? sub_dirs.sort!(&options[:sort]) : sub_dirs.sort!
+      # TODO AS: Reject sub_dir for includes and excludes
+      sub_dirs.each { |sub_dir| loaded_files << required(sub_dir, options) }
+    end
+    loaded_files.flatten
+  end
+
+  private
+  def require_within(directory, opt)
+    next unless File.directory? directory
+    loaded_files = []
+    ruby_files = Dir["#{directory}/*.rb"].reject{ |f| File.directory? f }
+    ruby_files = ruby_files.select { |f| f =~ opt[:include] } if opt[:include]
+    ruby_files = ruby_files.reject { |f| f =~ opt[:exclude] } if opt[:exclude]
+    opt[:sort] ? ruby_files.sort!(&opt[:sort]) : ruby_files.sort!
+    ruby_files.each { |file| loaded_files << file if require file }
+    loaded_files
+  end
+
+  def validate_options(options)
+    valid = [:recurse, :include, :exclude, :sort]
+    given = options.keys
+    unless valid.size - given.size == (valid - given).size
+      puts "warn: required recognizes only #{valid.inspect}, " +
+          "but was given #{given.inspect}\n#{caller[1].sub(/:in.*/, '')}"
+    end
+  end
+
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: required
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Arild Shirazi
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-31 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: 
+email: ashirazi@codesherpas.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/required.rb
+- README
+has_rdoc: true
+homepage: http://blog.codesherpas.com/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: Provides the ability to 'require' many or all files within directories, using a simple statement.
+test_files: []
+