again 1.1.4

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.DS_Store
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in again.gemspec
+gemspec

data/README.md

@@ -0,0 +1,201 @@
+# again.rb #
+
+## DESCRIPTION ##
+
+again is the best way to iteratively develop with Ruby.
+
+It monitors your application's code or any required library
+for changes. In the likely event of a change, the code is
+automatically loaded again.
+
+## Why? ##
+
+After seeing a [live stream](http://www.youtube.com/watch?v=zdLDYUNRErQ&feature=player_detailpage#t=532s)
+of Markus Persson [hyper-incrementally developing a game for a 48h game development competition in Java](
+http://news.ycombinator.com/item?id=2911696), where he debugged
+his 3d rendering code by just changing expressions, hitting save
+and instantly seeing the effect, I wanted to have support for
+hyper-iterative development in Ruby. 
+
+Change a color, save, switch to your application and it's changed.
+
+again has been tested with Ruby 1.8, Ruby 1.9 and JRuby 1.6.2.
+I use it for my personal development, including [Sinatra](
+http://www.sinatrarb.com/) web development as well as
+[Ruby/Gosu](http://www.libgosu.org/) game development.
+
+(If anybody has a better link for the video of Markus Persson working incrementally,
+[please drop me a mail](mailto:florian.s.gross@web.de)!)
+
+
+## INSTALL ##
+
+  gem install again
+
+
+## SYNOPSIS ##
+
+### Getting started with again ###
+
+All you need to do to setup automatic reloading of your
+code is to require again:
+
+```ruby
+  require 'again'       # ...and again and again
+```
+
+You should do this after all other libraries of your application
+have already been loaded: Make it your last `require`.
+
+
+### Controlling what to execute again ###
+
+#### Not running start-up logic again ####
+
+When again detects a change to a file, it will reexecute all code
+in that file. This also applies to the main file of your application,
+the one you actually run from the command line.
+
+For method and class definitions, this is no problem and things will
+work exactly as you expect.
+
+You should however wrap the actual start-up logic of your application
+like this:
+
+```ruby
+  # Current file being executed from command line?
+  if __FILE__ == $PROGRAM_NAME then
+    # Show them windows
+    window = GameWindow.new
+    window.show
+  end
+```
+
+This is something that is good style anyway (in order to allow your
+code to be used as a library): The above would only be executed on
+direct execution from the command line; and not when the file is
+loaded as a library. [More detailed explanation of `__FILE__ == $PROGRAM_NAME`](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/184607)
+
+again actually invests some extra effort to make sure that
+`__FILE__ == $PROGRAM_NAME` blocks will not be run again
+after reloading your main application file.
+
+
+#### Running additional code on reloads ####
+
+You can also have logic that is only run on reloads:
+
+```ruby
+  if Again.reloaded? then
+    puts "Hello again"
+  end
+```
+
+This is useful when you want to reset your application into a
+predictable state or when your frameworks need some special logic
+to make sure that your changes will be picked up. (Such as clearing
+routes in Sinatra, [see below](#sinatra-again).)
+
+
+### gosu again ###
+
+I'm using again for game development with Ruby, together with
+[Ruby/Gosu](http://www.libgosu.org/). My code typically looks like this:
+
+```ruby
+  require 'rubygems'
+  require 'gosu'
+  # ...
+  require 'again'
+  
+  include Gosu
+  
+  class GameWindow < Gosu::Window
+    def initialize()
+      @objects = ...
+    end
+    
+    def update()
+      @objects.each(&:update)
+    rescue Exception => err
+      handle_error(err)
+    end
+
+    def draw()
+      @objects.each(&:draw)
+    rescue Exception => err
+      handle_error(err)
+    end
+    
+    def handle_error(err)
+      # Simple logic, but it does the trick
+      STDERR.puts err, err.backtrace
+      sleep 3
+    end
+  end
+  
+  # Current file being executed from command line?
+  if __FILE__ == $PROGRAM_NAME then
+    # Let's play
+    window = GameWindow.new
+    window.show
+  end
+```
+
+Rescuing exceptions in `update()` and `draw()` and
+handling them in a central place is a very good idea.
+If you have uncaught exceptions in there, Gosu will
+shutdown your application. This would kill our nice
+incremental development loop in the case of an error.
+
+
+### sinatra again ###
+
+I also use again to incrementalize my [Sinatra](http://www.libgosu.org/) development.
+This is very similar to the above Gosu example, but with
+one special twist:
+
+```ruby
+  require 'rubygems'
+  require 'sinatra'
+  require 'json'
+  # ...
+  require 'again'
+  
+  if Again.reloaded? then
+    # Here's the twist
+    Sinatra::Application.routes.clear
+  end
+  
+  get '/' do
+    return "Awesome!"
+  end
+```
+
+We need to clear the Application routes first. Otherwise
+sinatra won't let us redefine our routes. That's all!
+
+
+## LICENSE ##
+
+(The MIT License)
+
+Copyright (c) 2012, Florian Gross <florian.s.gross@web.de>
+
+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/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/again.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "again/version"
+
+Gem::Specification.new do |s|
+  s.name        = "again"  
+  s.version     = Again::VERSION
+
+  s.authors     = ["Florian Gross"]
+  s.email       = ["Florian.S.Gross@web.de"]
+  s.homepage    = "https://github.com/flgr/again"
+  s.summary     = %q{The best way to iteratively develop with Ruby}
+  s.description = %q{again automatically reloads your application's code when it changes}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = [] # `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  s.add_runtime_dependency "listen"
+end

data/bin/again_test.rb

@@ -0,0 +1,9 @@
+lib_dir = File.expand_path(File.join(File.dirname(__FILE__), "..", "lib"))
+$LOAD_PATH << lib_dir
+
+require 'again'
+
+if __FILE__ == $0 then
+  puts "Again loaded"
+  Again.join
+end

data/lib/again.rb

@@ -0,0 +1,198 @@
+require 'again/version'
+require 'again/extras'
+require 'again/patches'
+
+require 'set'
+require 'pathname'
+require 'tmpdir'
+require 'singleton'
+require 'fileutils'
+
+require 'rubygems'
+require 'listen'
+
+class Again
+  include Singleton 
+
+  def self.start() self.instance end
+  def self.join() instance.join end
+  def self.reloaded?() instance.reloaded? end
+
+  def reloaded?() @reloaded end
+    
+  def join()
+    # Can't simply join @watch_thread here as a refresh() can stop it.
+    # We want to survive refreshes so we instead join a thread which
+    # keeps checking for new watch_threads...
+    Thread.new do
+      loop do
+        if @watch_thread then
+          @watch_thread.alive?() ? @watch_thread.join : sleep(0.5)
+        end
+      end
+    end.join
+  end
+
+  private
+
+  def with_reloaded()
+    old_reloaded, @reloaded = @reloaded, true
+    yield
+  ensure
+    @reloaded = old_reloaded
+  end
+    
+  def initialize()
+    @reloaded, @handler = false, nil
+    @watch_threads = ThreadGroup.new
+    @full_prog_name = File.expand_path($PROGRAM_NAME)
+    refresh()
+  end
+
+  def refresh()
+    refresh_libraries
+    refresh_handler
+  end
+
+  def refresh_libraries()
+    @base_paths = find_base_paths()
+    @libraries = find_libraries()
+  end
+  
+  def find_features()
+    features = $LOADED_FEATURES.dup
+    
+    # Allow realoding of main file (which is not a loaded library
+    # and thus does not appear in $LOADED_FEATURES)
+    features << @full_prog_name
+    
+    # features doesn't include this file by default since
+    # technically it is still in the process of being loaded
+    # ...so manually include it
+    features << File.basename(__FILE__)
+
+    return features
+  end
+  
+  # Avoid warnings on self-reload
+  remove_const(:JRUBY_PSEUDO_LIBS) if defined?(JRUBY_PSEUDO_LIBS)
+  remove_const(:PSEUDO_LIBS) if defined?(PSEUDO_LIBS)
+  
+  # Probably incomplete...
+  JRUBY_PSEUDO_LIBS = %w(enumerable.jar enumerator.jar thread.rb tempfile.rb 
+    java.rb jruby.rb socket.jar strscan.jar iconv.jar stringio.jar etc.jar 
+    fcntl.rb timeout.rb digest/md5.jar jsignal_internal.rb rbconfig.rb 
+    jruby/util.rb digest/sha1.jar digest.jar jruby/path_helper.rb)
+
+  PSEUDO_LIBS = %w(enumerable.so enumerator.so)
+
+  PSEUDO_LIBS.push(*JRUBY_PSEUDO_LIBS) if defined? JRUBY_VERSION
+  
+  def pseudo_lib?(lib) PSEUDO_LIBS.include?(lib) end
+  
+  RELOAD_MARKER = "--reload-temp--" unless defined?(RELOAD_MARKER)
+
+  def find_base_paths()
+    base_paths = *$LOAD_PATH.uniq
+    base_paths << File.dirname(@full_prog_name)
+
+    base_paths.map! { |path| File.expand_path(path) }
+    base_paths.reject! { |path| not File.exist?(path) or path.include?(RELOAD_MARKER) }
+    base_paths.uniq!
+    
+    return base_paths
+  end
+  
+  def find_libraries()
+    libraries, features = Set[], find_features
+
+    features.each do |rel_lib|
+      next if rel_lib.include?(RELOAD_MARKER)
+      
+      res_lib = resolve_library(rel_lib)
+        
+      if res_lib then
+        libraries << res_lib
+      elsif not pseudo_lib?(rel_lib) then
+        warn "Failed to resolve library %s to full path" % rel_lib
+      end
+    end
+    
+    return libraries
+  end
+  
+  def resolve_library(rel_lib)
+    return rel_lib if Pathname.new(rel_lib).absolute?
+
+    @base_paths.each do |path|
+      full_lib = File.join(path, rel_lib)
+      return full_lib if File.exist?(full_lib)
+    end
+    
+    return nil
+  end
+  
+  def refresh_handler()
+    # Our old @watch_thread will finish running after this
+    @handler.stop if @handler
+
+    @handler = Listen.to(*@base_paths)
+    @handler.change(&method(:on_change))
+    
+    @watch_thread = Thread.new { @handler.start(true) }
+  end
+      
+  def on_change(modified, added, removed)
+    (modified + added).each do |path|
+      reload(path) if @libraries.include?(path)
+    end
+  end
+  
+  def reload(path)
+    STDERR.puts "Reloading %s" % path
+    
+    # We don't want __FILE__ == $0 conditions to evaluate to true on reloads
+    # to avoid duplicate startup logic execution issues...
+    #
+    # So we intentionally create a copy of the file in that case to make
+    # those checks evaluate to false.
+    
+    load_path = path
+    tmp_dir = nil
+    
+    if @full_prog_name == path then
+      time = Time.now.to_i.to_s
+      tmp_dir = File.join(Dir.tmpdir, RELOAD_MARKER + "-dir-" + time)
+      Dir.mkdir(tmp_dir)
+
+      load_path = File.join(tmp_dir, RELOAD_MARKER + File.basename(load_path))
+      
+      begin
+        # Try to hardlink first...
+        FileUtils.ln(path, load_path)
+      rescue Exception
+        # ...if that fails, create a copy.
+        FileUtils.copy(path, load_path)
+      end
+    end
+    
+    begin
+      with_reloaded { load(load_path) }
+    rescue Exception => e
+      STDERR.puts e, "", e.backtrace.join("\n")
+    end
+
+    # need to do this from separate thread...
+    # we can not call handler.stop() from the thread
+    # that is getting the handler's callback
+    Thread.new { refresh }
+  ensure
+    FileUtils.rm_rf(tmp_dir) if tmp_dir
+  end
+end
+
+Again.start
+
+if Again.reloaded? then
+  puts "Again reloaded"
+end

data/lib/again/extras.rb

@@ -0,0 +1,17 @@
+class Again
+  def self.open_cmd()
+    (`which mate` rescue nil || "open").chomp
+  end
+  
+  def self.open_lib(lib, cmd=open_cmd)
+    if lib = instance.resolve_library(lib) then
+      system(cmd, lib)
+    end
+  end
+  
+  def self.open_libdir(lib, cmd=open_cmd)
+    if lib = instance.resolve_library(lib) then
+      system(cmd, File.dirname(lib))
+    end
+  end
+end

data/lib/again/patches.rb

@@ -0,0 +1,2 @@
+require 'again/patches/singleton'
+require 'again/patches/listen'

data/lib/again/patches/listen.rb

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'listen'
+
+class Listen::Adapter
+  def self.usable_and_works?(directories, options = {})
+    usable? #&& Array(directories).all? { |d| !writable?(d) || works?(d, options) }
+  end
+
+  def self.writable?(directory)
+    test_file = "#{directory}/.listen_test"
+    FileUtils.touch(test_file)
+    return true
+  rescue SystemCallError
+    return false
+  ensure
+    FileUtils.rm(test_file) if File.exists?(test_file)
+  end
+end
+
+# class Listen::DirectoryRecord
+#   # Don't use content-based modification at all (performance optimization)
+#   def content_modified?(path)
+#     return true
+#   end
+# end

data/lib/again/patches/singleton.rb

@@ -0,0 +1,17 @@
+# Fix a bug in singleton: When the Singleton module is included multiple times
+# in the same class, it will reset the instance variable on each inclusion.
+#
+# Together with again.rb this can easily result in lost state.
+# So this version only sets the instance variable to nil if it was undefined.
+
+require 'singleton'
+
+class << Singleton
+  alias :included_without_guard :included
+  
+  def included(klass)
+    return if klass.instance_variable_get(:@singleton_included)
+    included_without_guard(klass)
+    klass.instance_variable_set(:@singleton_included, true)
+  end
+end

data/lib/again/version.rb

@@ -0,0 +1,3 @@
+class Again
+  VERSION = "1.1.4"
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification 
+name: again
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 1
+  - 1
+  - 4
+  version: 1.1.4
+platform: ruby
+authors: 
+- Florian Gross
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-07-02 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: listen
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: again automatically reloads your application's code when it changes
+email: 
+- Florian.S.Gross@web.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- again.gemspec
+- bin/again_test.rb
+- lib/again.rb
+- lib/again/extras.rb
+- lib/again/patches.rb
+- lib/again/patches/listen.rb
+- lib/again/patches/singleton.rb
+- lib/again/version.rb
+homepage: https://github.com/flgr/again
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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.8.11
+signing_key: 
+specification_version: 3
+summary: The best way to iteratively develop with Ruby
+test_files: []
+