magicloader 0.9.0

data/CHANGES

@@ -0,0 +1,5 @@
+1.0.0:
+
+* Initial release (was originally require_all, converted to MagicLoader which 
+  is a lot cooler, seriously trust me. And let's forget I said that the last
+  time, if anyone wants to dig through require_all's CHANGES)

data/LICENSE

@@ -0,0 +1,58 @@
+Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.co.jp>.
+You can redistribute it and/or modify it under either the terms of the GPL
+(see COPYING.txt file), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+	  with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under this terms.
+
+     They are gc.c(partly), utils.c(partly), regex.[ch], st.[ch] and some
+     files under the ./missing directory.  See each file for the copying
+     condition.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+

data/README.markdown

@@ -0,0 +1,151 @@
+MagicLoader
+===========
+
+What if you could just point something at a big directory full of code and have
+everything just automagically load regardless of the dependency structure?
+
+Wouldn't that be nice?  Well, now you can!
+
+<code>require 'magic_loader'</code>
+
+MagicLoader uses a special algorithm, sort of like Bundler, to calculate the
+order in which various files in your project must be required in order for
+your project to load successfully. If you've been manually maintaining a
+dependencies list, MagicLoader provides for your code the same automation that
+Bundler provides for your gem dependencies.
+
+The "magicload" Rake task
+-------------------------
+
+The main way MagicLoader should be used is as a Rake task. Inside of your
+project's Rakefile, do:
+
+<pre><code>
+ require 'magicloader/tasks'
+ 
+ MagicLoader::Task.new 'lib/my_project', 
+  :target => 'lib/my_project.rb',
+  :strip  => 'lib/', 
+  :name   => 'magicload'
+</code></pre>
+ 
+What does this do exactly? Let's dig in.
+
+The MagicLoader::Task.new method takes a list of strings as its arguments,
+with an option options hash on the end (of course options are optional!)
+
+In this example, we have only one string, which is the path to our project.
+However, you can have multiple strings, and they don't need to just be paths,
+they can be globs, too! For more information on the string arguments, see
+"The wonderful require_all" method below.
+
+Pay special attention to the :target option. If you leave this out, 
+MagicLoader will print what it would've generated to standard output. However,
+if you set the target, you can annotate a particular file with a MagicLoader
+Magic Block. What's that you ask? Well it looks a bit like this:
+
+<pre><code>
+  #-----BEGIN MAGICLOADER MAGIC BLOCK-----
+  # Automagically generated by MagicLoader. Editing may
+  # result in bad juju. Edit at your own risk!
+  require "my_project/foo.rb"
+  require "my_project/bar.rb"
+  require "my_project/baz.rb"
+  require "my_project/qux.rb"
+  #------END MAGICLOADER MAGIC BLOCK------
+</code></pre>
+
+Here MagicLoader is automagically writing the dependency order of your library
+into the master file for your project. The dependency order is appended to the
+end of the file if it doesn't exist or updated if it does. The rest of your
+file remains unchanged.
+
+MagicLoader loads up your whole project within the Rake task, which is a nice,
+clean-room, thread-free environment where your code can be safely loaded
+without crazy wonky stuff going on. Here MagicLoader uses its magic algorithm
+to calculate the dependencies, then writes them all out for you in the
+MagicLoader Magic Block.
+
+Now, let's dig into the rest of the options hash. You might be able to guess
+what the options do already, but if you can't, here's some help:
+
+* __target__: output file to annotate. See above.
+
+* __strip__: remove the given leading string from all of the output paths written
+  to the target file. Optionally, you can give an arbitrary regular 
+  expression, and whatever it matches will be removed from the string.
+  This is good if you have a leading directory prefix you want to remove
+  from the generated output files.
+  
+* __name__: the name of the Rake task to define. It defaults to "magicload" if you
+  don't specify it yourself, so specifying it explicitly as "magicload" is a
+  bit redundant. Otherwise, you can set it to whatever you want.
+
+The wonderful require_all method
+--------------------------------
+
+You can probably guess what MagicLoader.require_all does: it requires a whole
+bunch of files.  It's highly configurable and can pull in globs or whole 
+directories of code.
+
+However, there are some caveats about the require_all method: it's slow and it
+isn't thread safe. That said, if you would like runtime code dependency 
+management, then proceed, young sorcerer. 
+
+The easiest way to use require_all is to just point it at a directory
+containing a bunch of .rb files:
+
+ <code>MagicLoader.require_all 'lib'</code>
+
+This will find all the .rb files under the lib directory (including all 
+subdirectories as well) and load them.
+
+The proper order to in which to load them is determined automatically.  If the 
+dependencies between the matched files are unresolvable, it will throw the 
+first unresolvable NameError.
+
+You can also give it a glob, which will enumerate all the matching files: 
+
+ <code>MagicLoader.require_all 'lib/**/*.rb'</code>
+
+It will also accept an array of files:
+
+ <code>MagicLoader.require_all Dir.glob("blah/**/*.rb").reject { |f| stupid_file? f }</code>
+ 
+Or if you want, just list the files directly as arguments:
+
+ <code>MagicLoader.require_all 'lib/a.rb', 'lib/b.rb', 'lib/c.rb', 'lib/d.rb'</code>
+
+So what's the magic?
+--------------------
+
+MagicLoader is just a Ruby library, after all. There's no magic but what you
+don't understand.  I didn't invent the approach this gem uses.  It was 
+shamelessly stolen from Merb (which apparently stole it from elsewhere).
+
+Here's how it works:  
+
+* Enumerate the files to be loaded
+* Try to load all of the files.  If we encounter a NameError loading a 
+  particular file, store that file in a "try to load it later" list.
+* If all the files loaded, great, we're done!  If not, go through the
+  "try to load it later" list again rescuing NameErrors the same way.
+* If we walk the whole "try to load it later" list and it doesn't shrink
+  at all, we've encountered an unresolvable dependency.  In this case,
+  require_all will rethrow the first NameError it encountered.
+
+Questions? Comments? Concerns?
+------------------------------
+
+You can reach the author on github or freenode: "tarcieri"
+
+or on Twitter: @bascule or email: [bascule@gmail.com](mailto:bascule@gmail.com)
+
+Got issues with require_all to report?  Post 'em here:
+
+[Github Tracker](http://github.com/tarcieri/require_all/issues)
+
+License
+-------
+
+MIT (see the LICENSE file for details)

data/Rakefile

@@ -0,0 +1,12 @@
+require 'rake'
+require 'rake/clean'
+
+Dir['tasks/**/*.rake'].each { |task| load task }
+
+task :default => :spec
+
+task :clean do
+  %w[pkg coverage].each do |dir|
+    rm_rf dir
+  end
+end

data/lib/magic_loader.rb

@@ -0,0 +1,115 @@
+#--
+# Copyright (C)2009-10 Tony Arcieri
+# You can redistribute this under the terms of the MIT license
+# See file LICENSE for details
+#++
+
+# MagicLoader: painless code dependency management
+# For more information, see http://github.com/tarcieri/MagicLoader
+module MagicLoader
+  # A wonderfully simple way to load your code.
+  #
+  # The easiest way to use require_all is to just point it at a directory
+  # containing a bunch of .rb files.  These files can be nested under 
+  # subdirectories as well:
+  #
+  #  MagicLoader.require_all 'lib'
+  #
+  # This will find all the .rb files under the lib directory and load them.
+  # The proper order to load them in will be determined automatically.
+  #
+  # If the dependencies between the matched files are unresolvable, it will 
+  # throw the first unresolvable NameError.
+  #
+  # You can also give it a glob, which will enumerate all the matching files: 
+  #
+  #  MagicLoader.require_all 'lib/**/*.rb'
+  #
+  # It will also accept an array of files:
+  # 
+  #  MagicLoader.require_all Dir.glob("blah/**/*.rb").reject { |f| stupid_file(f) }
+  # 
+  # Or if you want, just list the files directly as arguments:
+  #
+  #  MagicLoader.require_all 'lib/a.rb', 'lib/b.rb', 'lib/c.rb', 'lib/d.rb'
+  #
+  def self.require_all(*args)
+    # Handle passing an array as an argument
+    args.flatten!
+    
+    if args.size > 1
+      # Expand files below directories
+      files = args.map do |path|
+        if File.directory? path
+          Dir[File.join(path, '**', '*.rb')]
+        else
+          path
+        end
+      end.flatten
+    else
+      arg = args.first
+      begin
+        # Try assuming we're doing plain ol' require compat
+        stat = File.stat(arg)
+        
+        if stat.file?
+          files = [arg]
+        elsif stat.directory?
+          files = Dir.glob File.join(arg, '**', '*.rb')
+        else
+          raise ArgumentError, "#{arg} isn't a file or directory"
+        end
+      rescue Errno::ENOENT
+        # If the stat failed, maybe we have a glob!
+        files = Dir.glob arg
+        
+        # Maybe it's an .rb file and the .rb was omitted
+        if File.file?(arg + '.rb')
+          require(arg + '.rb')
+          return true
+        end
+        
+        # If we ain't got no files, the glob failed
+        raise LoadError, "no such file to load -- #{arg}" if files.empty?
+      end
+    end
+
+    # If there's nothing to load, you're doing it wrong!
+    raise LoadError, "no files to load" if files.empty?
+    
+    # Sort input files to give semi-deterministic results
+    files.sort!
+    
+    # Store load order as it's calculated
+    load_order = []
+    
+    begin
+      failed = []
+      first_name_error = nil
+      
+      # Attempt to load each file, rescuing which ones raise NameError for
+      # undefined constants.  Keep trying to successively reload files that 
+      # previously caused NameErrors until they've all been loaded or no new
+      # files can be loaded, indicating unresolvable dependencies.
+      files.each do |file|
+        begin
+          require file
+          load_order << file
+        rescue NameError => ex
+          failed << file
+          first_name_error ||= ex
+        end
+      end
+      
+      # If this pass didn't resolve any NameErrors, we've hit an unresolvable
+      # dependency, so raise one of the exceptions we encountered.
+      if failed.size == files.size
+        raise first_name_error
+      else
+        files = failed
+      end
+    end until failed.empty?
+    
+    load_order
+  end
+end

data/lib/magic_loader/tasks.rb

@@ -0,0 +1,85 @@
+#--
+# Copyright (C)2010 Tony Arcieri
+# You can redistribute this under the terms of the MIT license
+# See file LICENSE for details
+#++
+
+require 'magic_loader'
+require 'rake/tasklib'
+
+# Generates the MagicLoader rake task
+module MagicLoader
+  BEGIN_MAGIC = "#-----BEGIN MAGICLOADER MAGIC BLOCK-----"
+  END_MAGIC   = "#------END MAGICLOADER MAGIC BLOCK------"
+  MAGIC_WARNING = [
+    "# Automagically generated by MagicLoader. Editing may",
+    "# result in bad juju. Edit at your own risk!"
+  ]
+  MAGIC_REGEXP = /#{BEGIN_MAGIC}.*#{END_MAGIC}/m
+  
+  # Generates the MagicLoader rake task
+  class Task < Rake::TaskLib
+    def initialize(*paths)
+      options = paths.last.is_a?(Hash) ? paths.pop : {}
+      task_name = options[:name] || 'magicload'
+    
+      task task_name do
+        load_order = MagicLoader.require_all(*paths)
+        strip_paths!(load_order, options[:strip]) if options[:strip]
+
+        magic_block = [
+          BEGIN_MAGIC,
+          MAGIC_WARNING,
+          "# Run \"rake #{task_name}\" to regenerate",
+          load_order.map { |t| "require #{t.dump}" },
+          END_MAGIC
+        ].flatten.join("\n")
+      
+        if options[:target]
+          if File.exists? options[:target]
+            annotate_file options[:target], magic_block
+          else
+            File.open(options[:target], "w") { |f| f << magic_block }
+          end
+        else
+          puts magic_block
+        end
+      end
+    end
+  
+    #######
+    private
+    #######
+  
+    # Implement the path stripping logic described in the README
+    def strip_paths!(paths, to_strip)
+      paths.map! do |path|
+        case to_strip
+        when String
+          if path.index(to_strip) == 0
+            path.sub to_strip, ''
+          else
+            path
+          end
+        when Regexp
+          path.sub to_strip, ''
+        else raise ArgumentError, ":strip given a #{to_strip.class}"
+        end
+      end
+    end
+  
+    # Annotate a MagicLoader Magic Block onto the end of an existing file
+    def annotate_file(path, magic_block)
+      data = File.read path
+      magic_matches = data.match(MAGIC_REGEXP)
+      case magic_matches
+      when MatchData
+        data.sub!(MAGIC_REGEXP, magic_block)
+      else
+        data << "\n\n" << magic_block
+      end
+    
+      File.open(path, 'w') { |f| f << data }
+    end
+  end
+end

data/magicloader.gemspec

@@ -0,0 +1,24 @@
+require 'rubygems'
+
+GEMSPEC = Gem::Specification.new do |s|
+  s.name = "magicloader"
+  s.description = "Painless code dependency management"
+  s.summary = <<EOD
+Painless code dependency management. Think Bundler, but for managing file load
+ordering dependencies.
+EOD
+  s.version = "0.9.0"
+  s.authors = "Tony Arcieri"
+  s.email = "bascule@gmail.com"
+  s.homepage = "http://github.com/tarcieri/MagicLoader"
+  s.date = Time.now
+  s.platform = Gem::Platform::RUBY
+
+  # Gem contents
+  s.files = Dir.glob("{lib,spec}/**/*") + ['Rakefile', 'magicloader.gemspec']
+
+  # RDoc settings
+  s.has_rdoc = true
+  s.rdoc_options = %w(--title MagicLoader --main README.textile --line-numbers)
+  s.extra_rdoc_files = ["LICENSE", "README.markdown", "CHANGES"]
+end

data/spec/fixtures/resolvable/a.rb

@@ -0,0 +1 @@
+class A < C; end

data/spec/fixtures/resolvable/b.rb

@@ -0,0 +1 @@
+class B < A; end

data/spec/fixtures/resolvable/c.rb

@@ -0,0 +1 @@
+class C; end

data/spec/fixtures/resolvable/d.rb

@@ -0,0 +1 @@
+class D < C; end

data/spec/fixtures/unresolvable/a.rb

@@ -0,0 +1 @@
+class A < C; end

data/spec/fixtures/unresolvable/b.rb

@@ -0,0 +1 @@
+class B < A; end

data/spec/fixtures/unresolvable/c.rb

@@ -0,0 +1 @@
+class C < Nonexistent; end

data/spec/fixtures/unresolvable/d.rb

@@ -0,0 +1 @@
+class D < C; end

data/spec/magic_loader_spec.rb

@@ -0,0 +1,49 @@
+require File.expand_path('../spec_helper.rb', __FILE__)
+
+describe MagicLoader do
+  describe :require_all do
+    describe "dependency resolution" do
+      it "handles load ordering when dependencies are resolvable" do
+        MagicLoader.require_all File.expand_path('../fixtures/resolvable/*.rb', __FILE__)
+    
+        defined?(A).should == "constant"
+        defined?(B).should == "constant"
+        defined?(C).should == "constant"
+        defined?(D).should == "constant"
+      end
+  
+      it "raises NameError if dependencies can't be resolved" do
+        proc do 
+          MagicLoader.require_all File.expand_path('../fixtures/unresolvable/*.rb', __FILE__)
+        end.should raise_error(NameError)
+      end
+    end
+  
+    describe "syntactic sugar" do
+      before :each do
+        @base_dir = File.expand_path('../fixtures/resolvable', __FILE__)
+        @file_list = ['b.rb', 'c.rb', 'a.rb', 'd.rb'].map { |f| "#{@base_dir}/#{f}" }   
+      end
+    
+      it "works like a drop-in require replacement" do
+        MagicLoader.require_all(@base_dir + '/c').should be_true
+      end
+    
+      it "accepts lists of files" do
+        MagicLoader.require_all(@file_list).should be_true
+      end
+    
+      it "is totally cool with a splatted list of arguments" do
+        MagicLoader.require_all(*@file_list).should be_true
+      end
+    
+      it "will load all .rb files under a directory without a trailing slash" do
+        MagicLoader.require_all(@base_dir).should be_true
+      end
+    
+      it "will load all .rb files under a directory with a trailing slash" do
+        MagicLoader.require_all("#{@base_dir}/").should be_true
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+$LOAD_PATH << File.expand_path('../../lib', __FILE__)
+
+require 'magic_loader'

data/spec/task_spec.rb

@@ -0,0 +1,75 @@
+require File.expand_path('../spec_helper.rb', __FILE__)
+
+require 'rubygems'
+require 'rake'
+require 'magic_loader/tasks'
+
+describe MagicLoader::Task do
+  before :all do
+    @prefix  = File.dirname(__FILE__) + '/fixtures/'
+    @sources = @prefix + 'resolvable'
+    @output  = File.expand_path('../tmp/example.rb', __FILE__)
+  end
+  
+  before :each do
+    rm @output if File.exists? @output
+    File.exists?(@output).should be_false
+  end
+  
+  it "prints to standard output unless a :target is specified" do
+    # It's left as an exercise to the end user to visually confirm this
+    MagicLoader::Task.new @sources, :strip => @prefix
+    Rake::Task['magicload'].invoke
+  end
+  
+  it "creates new files if they don't exist" do
+    MagicLoader::Task.new @sources,
+      :target => @output,
+      :strip  => @prefix,
+      :name   => 'magicload2'
+      
+    Rake::Task['magicload2'].invoke
+    
+    File.exists?(@output).should be_true
+  end
+  
+  it "annotates files that do exist" do
+    important_crap = "# OMFG IMPORTANT CRAP DON'T DELETE THIS"
+    File.open(@output, 'w') { |f| f << important_crap }
+    
+    MagicLoader::Task.new @sources,
+      :target => @output,
+      :strip  => @prefix,
+      :name   => 'magicload3'
+      
+    Rake::Task['magicload3'].invoke
+
+    File.exists?(@output).should be_true
+    data = File.read @output
+    data[important_crap].should be_an_instance_of(String)
+  end
+  
+  it "annotates files that do exist and already have magic blocks" do
+    important_crap = "# OMFG IMPORTANT CRAP DON'T DELETE THIS"
+    fake_magic_block = [
+      MagicLoader::BEGIN_MAGIC,
+      "# omgfake!",
+      MagicLoader::END_MAGIC
+    ].join("\n")
+    
+    important_crap << "\n\n" << fake_magic_block
+    File.open(@output, 'w') { |f| f << important_crap }
+    
+    MagicLoader::Task.new @sources,
+      :target => @output,
+      :strip  => @prefix,
+      :name   => 'magicload4'
+      
+    Rake::Task['magicload4'].invoke
+    
+    File.exists?(@output).should be_true
+    data = File.read @output
+    data["omgfake"].should be_nil
+    data[MagicLoader::MAGIC_REGEXP].should be_an_instance_of(String)
+  end
+end

data/spec/tmp/example.rb

@@ -0,0 +1,11 @@
+# OMFG IMPORTANT CRAP DON'T DELETE THIS
+
+#-----BEGIN MAGICLOADER MAGIC BLOCK-----
+# Automagically generated by MagicLoader. Editing may
+# result in bad juju. Edit at your own risk!
+# Run "rake magicload4" to regenerate
+require "resolvable/a.rb"
+require "resolvable/b.rb"
+require "resolvable/c.rb"
+require "resolvable/d.rb"
+#------END MAGICLOADER MAGIC BLOCK------

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: magicloader
+version: !ruby/object:Gem::Version 
+  hash: 59
+  prerelease: false
+  segments: 
+  - 0
+  - 9
+  - 0
+  version: 0.9.0
+platform: ruby
+authors: 
+- Tony Arcieri
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-30 00:00:00 -06:00
+default_executable: 
+dependencies: []
+
+description: Painless code dependency management
+email: bascule@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+- CHANGES
+files: 
+- lib/magic_loader/tasks.rb
+- lib/magic_loader.rb
+- spec/fixtures/resolvable/a.rb
+- spec/fixtures/resolvable/b.rb
+- spec/fixtures/resolvable/c.rb
+- spec/fixtures/resolvable/d.rb
+- spec/fixtures/unresolvable/a.rb
+- spec/fixtures/unresolvable/b.rb
+- spec/fixtures/unresolvable/c.rb
+- spec/fixtures/unresolvable/d.rb
+- spec/magic_loader_spec.rb
+- spec/spec_helper.rb
+- spec/task_spec.rb
+- spec/tmp/example.rb
+- Rakefile
+- magicloader.gemspec
+- LICENSE
+- README.markdown
+- CHANGES
+has_rdoc: true
+homepage: http://github.com/tarcieri/MagicLoader
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --title
+- MagicLoader
+- --main
+- README.textile
+- --line-numbers
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Painless code dependency management. Think Bundler, but for managing file load ordering dependencies.
+test_files: []
+