Require-Me

Includes a DSL for requiring files and folders and some also some static utility functions which can be used in combination. These tools in combination facilitates managing requiring various subfolder structures.

Important

The tool has gone through some more testing and some bugs have been found and fixed so it should now be more stable. The rspec tests in spec/dsl directory demonstrate most of these new features.

Installation

This gem is also available for installation on gemcutter.

$ gem install require-me

Usage

To load the full functionality

require 'require-me'

To load only the require DSL functionality

require 'require-dsl'

Require DSL

The following example code demonstrates how to use the Require DSL


require 'require-dsl'  # to include the Require DSL language only

Folder.enter 'mira' do |folder| # enter subfolder 'mira'
  `# from new location, enter a subdir`
  folder.enter 'subdir' do |path|  # mira/subdir      
    folder.all('**/*.rb').except(/sound\/*.rb/).do_require  
  end

  folder.enter 'another/subdir' do |path|               
    folder.all('**/*.rb').do_require # use file blobs here
  end

  folder.enter 'a_subdir' do |path|         
    `# matching and except are to be used as include and exclude filters
    # they each take a list containing regular expressions and strings
    # string arguments are postfixed with .rb internally if not present`  
    folder.all('blip/**/*.rb').matching(/_mixin.rb/, /.*\/power/).except(/sound/, /disco/).do_require

    folder.enter 'sub_a' do |path|         
      folder.enter 'sub_b' do |path| # a_subdir/sub_a/sub_b         
        folder.all('grusch/**/*.rb').do_require
      end

    end
    folder.all.do_require    
  end
end  

If no argument, current path is used as initial folder


require 'require-me' # include both the static require helpers and the DSL require language  
  
Folder.enter do |folder| # use current path as folder
  folder.enter 'game' do |f|
    folder.require_all # require all .rb files within this folder!  

    `# use static require functions`
    Require.base_path path # set base path to use for Require

    `# include .rb files within data1, data2 but not within their subfolders (use recursive instead)`
    Require.folders('data1', 'data2') 
     
    list = path.all('**/*.rb')    
    puts list.matching('sound', 'network').except(/sound/).show_require(:relative)
    list.matching('sound', 'network').except(/sound/).do_require
  end
end  

Using 'require_rel' method. This is nice when fx requiring helper files used in test suite files


require File.expand_path(File.dirname(__FILE__) + "../../../spec_helper")

Can be replaced with the following in all .rb files under /spec


Folder.require_rel 'spec/spec_helper', __FILE__

Or ... using special convenience wrappers


Folder.require_spec 'spec_helper', __FILE__  # relative to /spec folder 

Folder.require_test 'spec_helper', __FILE__ # relative to /test folder

Using 'require_me' method



# lib/gamer.rb
Folder.require_me '../fixtures/game/game.rb'
Folder.enter '../fixtures/game' do |f|
  f.require_me 'game.rb'
end   

# Set context in block using 'enter_here' method

# fixtures/game/game.rb
# ensure context is set relative to here for require statements within block
Folder.enter_here(__FILE__) do
  # require graphics within the game folder!
  Folder.require_me 'graphics/graphics'
end

Static helpers

Unit tests demonstrations how to use the static helpers (tests currently broken due to missing data files!):

Setting the base path

Setting global base_path


Require.base_path = File.dirname(__FILE__)  

Set basepath to use within block


Require.enter 'sound' do |path|
  Require.folders 'data' # can be used for any number of folders   
  Require.folder 'data2' # for one folder only
end

Override base_path


Require.folders 'data', {:base_path => File.dirname(__FILE__) + '/../my/path}

Simple usage examples Require .rb files from a folder


Require.folders 'data', 'data2' 
Require.recursive 'data', 'data2' # recursively require all in subtrees

Simple debugging

Get list of required files and print them


required_files = Require.folder 'data'
puts required_files  

Tracing mode (for debugging)

Apply tracing to see output for the process of requiring the files

  
  Require.tracing = :on # turn on tracing globally
  Require.folder 'data'  
  Require.tracing = :off # turn off tracing globally

Alternatively pass tracing as an option


Require.folder 'data', {:tracing => :on}  

Verbose mode (for detailed debugging)

Set verbose mode on to see full path of each required file

                      
  Require.tracing = :on # turn on tracing          
  Require.verbose = :on # turn on verbose globally
  Require.folder 'data'  
  Require.verbose = :off  # turn off verbose globally

Require.recursive

Require all files within the top level folder 'data' recursively


required_files = Require.recursive 'data'  

Require all files within the top level folders 'data' and 'data2' (non-recursively)


required_files = Require.recursive 'data', 'data2'  

Require all files within the top level folders 'data' and 'data2' recursively

 
required_files = Require.recursive 'data', 'data2'

Require.folders

Require files within the top level folders 'data' and 'data2' and also files within the subdirectory 'blip' if it exists


required_files = Require.folders 'data', 'data2', {:folders => 'blip'}  

Require files within 'data/blip' and 'data2/blip' only, NOT including the root files


required_files = Require.folders 'data', 'data2', {:folders => 'blip', :ignore_root_files => true}  

Require files within 'data' and 'data2' first and then AFTER any files within the subdirectory 'blip' (default order)


required_files = Require.folders 'data', 'data2', {:folders => 'blip', :root_files => :before}  

Require files within 'data/blip' and 'data2/blip' first and then AFTER any files within 'data' and 'data2' folders (the root files)


required_files = Require.folders(['data', 'data2'], {:folders => 'blip', :root_files => :after})

Require files within 'data' and 'data2' (the root files) first (BEFORE) and then any files within the subdirectories 'blip' and 'blap'


required_files = Require.folders(['data', 'data2'], {:folders => ['blip', 'blap'], :root_files => :before})  

Copyright (c) 2010 Kristian Mandrup. See LICENSE for details.