golly-utils 0.0.1 → 0.6.0

data/.corvid/Gemfile

@@ -0,0 +1,28 @@
+# vim:ft=ruby et ts=2 sw=2:
+
+#gem 'corvid'
+gem "corvid", git: 'git://github.com/japgolly/corvid.git' # TODO Use proper Corvid once released
+
+gem 'rake', group: :rake
+
+group :test do
+  gem 'ci_reporter', require: false
+  gem 'simplecov', '>= 0.6.4', require: false
+  gem 'guard', '>= 1.3.2', require: false
+end if Dir.exists?('test')
+
+group :test_unit do
+  gem 'minitest'
+  gem 'guard-minitest', '>= 0.5.0', require: false
+  gem 'turn', '>= 0.9.4'
+end if Dir.exists?('test/unit')
+
+group :test_spec do
+  gem 'rspec'
+  gem 'guard-rspec', require: false
+end if Dir.exists?('test/spec')
+
+group :doc do
+#  gem 'yard'
+  gem 'yard', git: 'git://github.com/japgolly/yard.git', branch: 'happy_days' # TODO Use proper yard
+end

data/.corvid/features.yml

@@ -0,0 +1,4 @@
+---
+- corvid:corvid
+- corvid:test_unit
+- corvid:test_spec

data/.corvid/plugins.yml

@@ -0,0 +1,4 @@
+---
+corvid:
+  :path: corvid/builtin/builtin_plugin
+  :class: Corvid::Builtin::BuiltinPlugin

data/.corvid/stats_cfg.rb

@@ -0,0 +1,13 @@
+# Customisable configuration for the Corvid 'rake stats' task.
+
+# Provide your own configuration
+#{
+#  'Source code'     => { category: :code, dirs: %w[src] },
+#  'Specifications'  => { category: :test, dirs: %w[test/spec], line_parser: :spec },
+#}
+
+# Add to the default configuration
+#defaults.merge 'Bin scripts' => { category: :code, dirs: %w[bin] }
+
+# Use the default configuration as is
+defaults

data/.corvid/todo_cfg.rb

@@ -0,0 +1,15 @@
+# Customisable configuration for the Corvid 'rake todo' task.
+#
+# See Corvid's corvid/builtin/todo_finder.rb for more details.
+
+# Ignore files that match find's -path switch.
+#todo_finder.ignore_paths += %w[
+#  */test/fixtures/*
+#  */vendor/*
+#]
+
+# Ignore files that match find's -name switch.
+#todo_finder.ignore_names += %w[
+#  *_spec.rb
+#  *.html
+#]

data/.corvid/versions.yml

@@ -0,0 +1,2 @@
+---
+corvid: 1

data/.simplecov

@@ -1,14 +1,17 @@
 SimpleCov.start do
-  # project_name 'My Awesome Project'
+  project_name 'Golly-Utils'
 
   # add_group 'Models', 'app/model'
   # add_group 'Plugins', '(app|lib)/plugins'
 
-  # Remove test code from coverage
-  add_filter 'test'
+  # Exclude tests from coverage
+  add_filter '^(?:(?<!/(?:app|lib)/).)*/test/'
 
   # Add files that don't get required to coverage too
   add_files_to_coverage_at_exit '{app,lib}/**/*.rb'
+
+  # Skip LOC that contain nothing but "end", "ensure", and so on.
+  skip_boring_loc_in_coverage
 end
 
 # vim:ft=ruby et ts=2 sw=2:

data/CHANGELOG.md

@@ -1,9 +1,52 @@
 Golly's Utils: Changelog
 ========================
 
-## 0.0.2 (WIP)
+## 0.6.0 (2012-09-17)
 
-WIP
+Lots of stuff:
+
+#### Added
+* Added {Object#validate_type!} and {Symbol#validate_lvar_type!}.
+* Added {Object#superclasses}.
+* Added {GollyUtils::Testing::DynamicFixtures}.
+* Added {Hash#validate_keys} and {Hash#validate_option_keys}.
+* Added {Kernel#at_exit_preserving_exit_status}.
+* {GollyUtils::Singleton Singleton} module.
+* Added new {GollyUtils::Delegator Delegator} option: `:allow_protected`
+* {GollyUtils::Callbacks Callbacks} can now be defined in modules.
+* Added {GollyUtils::Callbacks::ClassMethods#callbacks} and {GollyUtils::Callbacks::ModuleMethods#callbacks} to provide a list of all defined and inherited callbacks.
+* {GollyUtils::Callbacks::InstanceMethods#run_callbacks Callbacks#run_callbacks} now accepts options which currently allows for callback arguments to be specified.
+* {GollyUtils::Callbacks::InstanceMethods#run_callback Callbacks#run_callback} and {GollyUtils::Callbacks::InstanceMethods#run_callbacks Callbacks#run_callbacks}
+  now accept an option to pass arguments to callback functions.
+* {GollyUtils::Callbacks::InstanceMethods#run_callback Callbacks#run_callback} and {GollyUtils::Callbacks::InstanceMethods#run_callbacks Callbacks#run_callbacks}
+  now accept an option to provide a context for callback function execution.
+* Added Ruby extensions:
+  * {Enumerable#frequency_map}
+* Added test helpers:
+  * {GollyUtils::Testing::Helpers#get_dirs get_dirs}
+  * {GollyUtils::Testing::Helpers#get_files get_files}
+  * {GollyUtils::Testing::Helpers#get_dir_entries get_dir_entries}
+  * {GollyUtils::Testing::Helpers#inside_empty_dir inside_empty_dir}
+  * {GollyUtils::Testing::Helpers#in_tmp_dir? in_tmp_dir?}
+  * {GollyUtils::Testing::Helpers#step_out_of_tmp_dir step_out_of_tmp_dir}
+* Added RSpec helpers:
+  * {GollyUtils::Testing::Helpers::ClassMethods#run_all_in_empty_dir run_all_in_empty_dir}
+  * {GollyUtils::Testing::Helpers::ClassMethods#run_each_in_empty_dir run_each_in_empty_dir}
+  * {GollyUtils::Testing::Helpers::ClassMethods#run_each_in_empty_dir_unless_in_one_already run_each_in_empty_dir_unless_in_one_already}
+  * {GollyUtils::Testing::RSpecMatchers#be_file_with_contents be_file_with_contents}
+  * {GollyUtils::Testing::RSpecMatchers#exist_as_a_dir exist_as_a_dir}
+  * {GollyUtils::Testing::RSpecMatchers#exist_as_a_file exist_as_a_file}
+  * {GollyUtils::Testing::RSpecMatchers#equal_array equal_array}
+
+#### Modified
+* Finished the experiment that was {GollyUtils::AttrDeclarative}. No mucking around with blocks, eager/lazy evaluation anymore; now it's all values.
+* {GollyUtils::Delegator#respond_to? Delegator#respond_to?} now also indicates `true` for local methods (in addition to delegatable).
+* {GollyUtils::Callbacks::InstanceMethods#run_callback Callbacks#run_callback} now only runs a single callback.
+* Renamed dir: `golly-utils/test` => `golly-utils/testing`.
+* Renamed dir: `golly-utils/test/spec` => `golly-utils/testing/rpsec`.
+* Renamed module: `GollyUtils::TestHelpers` => `GollyUtils::Testing::Helpers`
+* Renamed module: `GollyUtils::DeferrableSpecs` => `GollyUtils::Testing::DeferrableSpecs`
+* Renamed `golly-utils/ruby_ext/subclasses.rb` => `golly-utils/ruby_ext/classes_and_types.rb`
 
 ## 0.0.1 (2012-07-16)
 

data/Gemfile

@@ -1,12 +1,15 @@
 source :rubygems
-
 gemspec
 
-# Load Gemfile.corvid
-eval File.read(__FILE__ + '.corvid')
+# Load Corvid dependencies
+eval File.read(File.expand_path '../.corvid/Gemfile', __FILE__)
 
 # Parser for Markdown documentation
 group :doc do
   gem 'rdiscount', platforms: :mri
   gem 'kramdown', platforms: :jruby
 end
+
+group :test do
+  gem 'rb-inotify', '>= 0.8.8', require: false
+end

data/Gemfile.lock

@@ -1,61 +1,59 @@
 GIT
   remote: git://github.com/japgolly/corvid.git
-  revision: b4bd43588c25b3496c703f5b31a212f35d887de9
+  revision: ea00947384e8d2a507724c8aacb00afdade6333a
   specs:
     corvid (0.0.1)
+      activesupport
+      golly-utils
+      thor (~> 0.15.4)
+
+GIT
+  remote: git://github.com/japgolly/yard.git
+  revision: 9e86df2a9c14412bd5c4b05005137e776b703129
+  branch: happy_days
+  specs:
+    yard (0.8.2.1)
 
 PATH
   remote: .
   specs:
-    golly-utils (0.0.1)
+    golly-utils (0.6.0)
 
 GEM
   remote: http://rubygems.org/
   specs:
+    activesupport (3.2.8)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
     ansi (1.4.3)
-    builder (3.0.0)
-    ci_reporter (1.7.0)
+    builder (3.1.3)
+    ci_reporter (1.7.2)
       builder (>= 2.1.2)
-    columnize (0.3.6)
-    debugger (1.1.4)
-      columnize (>= 0.3.1)
-      debugger-linecache (~> 1.1.1)
-      debugger-ruby_core_source (~> 1.1.3)
-    debugger-linecache (1.1.2)
-      debugger-ruby_core_source (>= 1.1.1)
-    debugger-ruby_core_source (1.1.3)
     diff-lcs (1.1.3)
-    ffi (1.0.11)
-    ffi (1.0.11-java)
-    guard (1.2.3)
+    ffi (1.1.5)
+    guard (1.3.2)
       listen (>= 0.4.2)
       thor (>= 0.14.6)
     guard-minitest (0.5.0)
       guard (>= 0.4)
-    guard-rspec (1.1.0)
+    guard-rspec (1.2.1)
       guard (>= 1.1)
-    kramdown (0.13.7)
-    listen (0.4.7)
-      rb-fchange (~> 0.0.5)
-      rb-fsevent (~> 0.9.1)
-      rb-inotify (~> 0.8.8)
-    minitest (3.2.0)
+    i18n (0.6.1)
+    listen (0.5.0)
+    minitest (3.4.0)
     multi_json (1.3.6)
     rake (0.9.2.2)
-    rb-fchange (0.0.5)
-      ffi
-    rb-fsevent (0.9.1)
     rb-inotify (0.8.8)
       ffi (>= 0.5.0)
     rdiscount (1.6.8)
-    rspec (2.10.0)
-      rspec-core (~> 2.10.0)
-      rspec-expectations (~> 2.10.0)
-      rspec-mocks (~> 2.10.0)
-    rspec-core (2.10.1)
-    rspec-expectations (2.10.0)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.3)
       diff-lcs (~> 1.1.3)
-    rspec-mocks (2.10.1)
+    rspec-mocks (2.11.2)
     simplecov (0.6.4)
       multi_json (~> 1.0)
       simplecov-html (~> 0.5.3)
@@ -63,24 +61,23 @@ GEM
     thor (0.15.4)
     turn (0.9.6)
       ansi
-    yard (0.8.2.1)
 
 PLATFORMS
-  java
   ruby
 
 DEPENDENCIES
   ci_reporter
   corvid!
-  debugger
   golly-utils!
+  guard (>= 1.3.2)
   guard-minitest (>= 0.5.0)
   guard-rspec
   kramdown
   minitest
   rake
+  rb-inotify (>= 0.8.8)
   rdiscount
   rspec
   simplecov (>= 0.6.4)
-  turn
-  yard
+  turn (>= 0.9.4)
+  yard!

data/Guardfile

@@ -1,4 +1,9 @@
-require 'corvid/guard'
+require 'corvid/builtin/guard'
+
+project_name  = Regexp.quote(determine_project_name)
+rspec_options = read_rspec_options(File.dirname __FILE__)
+
+ignore VIM_SWAP_FILES
 
 ########################################################################################################################
 # test/unit
@@ -7,7 +12,8 @@ group :unit do
   guard 'minitest', test_folders: 'test/unit', test_file_patterns: '*_test.rb' do
 
     # Src files
-    watch(%r'^lib/golly-utils/(.+)\.rb$') {|m| "test/unit/#{m[1]}_test.rb"}
+    watch(%r'^lib/(.+)\.rb$')                 {|m| "test/unit/#{m[1]}_test.rb"}
+    watch(%r'^lib/#{project_name}/(.+)\.rb$') {|m| "test/unit/#{m[1]}_test.rb"}
 
     # Each test
     watch(%r'^test/unit/.+_test\.rb$')
@@ -24,12 +30,12 @@ end if Dir.exists?('test/unit')
 ########################################################################################################################
 # test/spec
 
-rspec_options= read_rspec_options(File.dirname __FILE__)
 group :spec do
   guard 'rspec', binstubs: true, spec_paths: ['test/spec'], cli: rspec_options, all_on_start: false, all_after_pass: false do
 
     # Src files
-    watch(%r'^lib/(.+)\.rb$') {|m| "test/spec/#{m[1]}_spec.rb"}
+    watch(%r'^lib/(.+)\.rb$')                 {|m| "test/spec/#{m[1]}_spec.rb"}
+    watch(%r'^lib/#{project_name}/(.+)\.rb$') {|m| "test/spec/#{m[1]}_spec.rb"}
 
     # Each spec
     watch(%r'^test/spec/.+_spec\.rb$')

data/RELEASE.md

@@ -8,6 +8,8 @@ To perform a release:
 * Ensure no uncommitted changes.
 * `gem build golly-utils.gemspec`
 * `gem push golly-utils-x.x.x.gem`
+* `git tag -s x.x.x`
 * Update `version.rb`
+* `bundle install`
 * Commit
 

data/Rakefile

@@ -1,6 +1,6 @@
 raise "Rake must not be run directly. Either run via Bundler (bundle exec rake) or via bin/rake." unless defined?(Bundler)
 APP_ROOT ||= File.expand_path(File.dirname(__FILE__))
-require 'corvid/rake/tasks'
+require 'corvid/builtin/rake/tasks'
 
 # Set default task to test
 task :default => :test

data/golly-utils.gemspec

@@ -2,16 +2,25 @@
 require File.expand_path('../lib/golly-utils/version', __FILE__)
 
 Gem::Specification.new do |gem|
-  gem.name          = "golly-utils"
-  gem.version       = GollyUtils::VERSION
-  gem.date          = Date.today.to_s
-  gem.summary       = %q{Golly's Utils: Reusable Ruby utility code.}
-  gem.description   = %q{This contains a bunch of shared, utility code that has no external dependencies apart from Ruby stdlib.}
-  gem.authors       = ["David Barri"]
-  gem.email         = ["japgolly@gmail.com"]
-  gem.homepage      = "https://github.com/japgolly/golly-utils"
+  gem.name        = "golly-utils"
+  gem.version     = GollyUtils::VERSION.dup
+  gem.date        = Time.new.strftime '%Y-%m-%d'
+  gem.summary     = %q{Golly's Utils: Reusable Ruby utility code.}
+  gem.description = %q{This contains a bunch of shared, utility code that has no external dependencies apart from Ruby stdlib.}
+  gem.authors     = ["David Barri"]
+  gem.email       = ["japgolly@gmail.com"]
+  gem.homepage    = "https://github.com/japgolly/golly-utils"
 
-  gem.files         = File.exists?('.git') ? `git ls-files`.split($\) : Dir['*']
-  gem.require_paths = %w[lib]
+  gem.files         = File.exists?('.git') ? `git ls-files`.split($\) : \
+                      Dir['**/*'].reject{|f| !File.file? f or %r!^(?:target|resources/latest)/! === f}.sort
   gem.test_files    = gem.files.grep(/^test\//)
+  gem.require_paths = %w[lib]
+  gem.bindir        = 'bin'
+  gem.executables   = %w[]
+
+  gem.add_development_dependency 'corvid'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'minitest'
+  gem.add_development_dependency 'rspec'
 end
+

data/lib/golly-utils/attr_declarative.rb

@@ -1,15 +1,69 @@
 module GollyUtils
+  # Creates instance accessors much like `attr_accessor` with the following additional properties:
+  #
+  # 1. Default values can be specified.
+  # 1. Defaults can be overridden in subclasses.
+  # 1. Values can be declared, failing-fast on typos.
+  # 1. Explicit declaration of an attribute value can be required and enforced. (Optional)
+  #
+  #    i.e. if an attribute is read before a value has been specified, then an error will be thrown.
+  #
+  # Attributes ending in `?` or `!` will have said suffix removed in the instance variable, and writer method names.
+  #
+  # @example
+  #   require 'golly-utils/attr_declarative'
+  #
+  #   class Plugin
+  #     attr_declarative :name, :author
+  #     attr_declarative version: 10
+  #   end
+  #
+  #   class BluePlugin < Plugin
+  #     name 'The Blue Plugin'
+  #   end
+  #
+  #   p = BluePlugin.new
+  #   puts p.name              # => The Blue Plugin
+  #   puts p.author            # => nil
+  #   puts p.version           # => 10
+  #
+  # @example Typos fail-fast:
+  #   class RedPlugin < Plugin
+  #     aauthor 'Homer'        # This will fail to parse
+  #
+  #     def nnname()           # Alternatively, this wouldn't fail until runtime and even then only if
+  #       'The Red Plugin'     # name() was defined in the superclass to fail by default.
+  #     end
+  #   end
+  #
+  # @example Attribute value declaration can be required and enfored:
+  #   class Plugin
+  #     attr_declarative :name, required: true
+  #   end
+  #
+  #   class BluePlugin < Plugin
+  #   end
+  #
+  #   p = BluePlugin.new
+  #   puts p.name        # => RuntimeError: Attribute 'name' required by Plugin but not set in BluePlugin.
+  #
+  # @example Attibutes with special naming rules
+  #   class SpecialNames
+  #     attr_declarative :happy?
+  #     attr_declarative :my_fist!
+  #
+  #     happy?   false               # Class-level declaration includes suffix
+  #     my_fist! :its_amazing        # Class-level declaration includes suffix
+  #   end
+  #
+  #   puts SpecialNames.new.happy?   # Instance method includes suffix
+  #   puts SpecialNames.new.my_fist! # Instance method includes suffix
+  #
+  #   SpecialNames.new.happy= false  # Instance-level declaration replaces suffix with =
+  #   SpecialNames.new.my_fist= nil  # Instance-level declaration replaces suffix with =
   module AttrDeclarative
 
-    def self.included(base)
-      base.send :include, InstanceMethods
-      base.send :include, InstanceAndClassMethods
-      base.extend InstanceAndClassMethods
-      base.extend ClassMethods
-    end
-
-    private
-
+    # @!visibility private
     def self.get_default(key, clazz)
       while clazz
         if clazz.instance_variables.include?(key)
@@ -20,55 +74,72 @@ module GollyUtils
       nil
     end
 
-    #-------------------------------------------------------------------------------------------------------------------
+    # Declares one or more attributes.
+    #
+    # @overload attr_declarative(hash_of_names_to_defaults)
+    #   @param [Hash<String|Symbol, Object>] hash_of_names_to_defaults A hash with keys being attribute names, and
+    #     values being corresponding default values.
+    #
+    # @overload attr_declarative(*names, options={})
+    #   @param [Array<String|Symbol>] names The attribute names.
+    #   @option options [Object] :default (nil) The default value for all specified attributes.
+    #   @option options [Object] :required (false) If required, an attribute will raise an error if it is read before it
+    #     has been set.
+    # @return [nil]
+    def attr_declarative(first,*args)
+      # Parse args
+      names= ([first] + args).flatten.uniq
+      options= names.last.is_a?(Hash) ? names.pop.clone : {}
 
-    # TODO default should be default_value/default_proc
-    # TODO add an option to specify whether proc should be eval'd everytime or once and return value cached
-
-    module ClassMethods
-      def attr_declarative(first,*args)
-        names= ([first] + args).flatten.uniq
-        options= names.last.is_a?(Hash) ? names.pop.clone : {}
-        default= options.delete :default
-        raise "Unknown options: #{options.keys}" unless options.empty?
-        names.each do |name|
-          dvar= "@_#{name}_default"
-          class_eval <<-EOB
+      # Accept <name>: <default> syntax
+      if names.empty? and not options.empty?
+        options.each do |name,default|
+          attr_declarative name, default: default
+        end
+        return nil
+      end
 
-            def #{name}
-              if block_given?
-                @#{name}= yield
-              elsif not @#{name}.nil?
-                @#{name}
-              elsif d= ::GollyUtils::AttrDeclarative.get_default(:#{dvar}, self.class)
-                @#{name}= d.call
-              else
-                nil
-              end
-            end
+      # Validate options
+      default= options.delete :default
+      required= (options.has_key? :required) ? options.delete(:required): false
+      raise "Unknown options: #{options.keys}" unless options.empty?
 
-            def self.#{name}(&block)
-              instance_variable_set :#{dvar}, block
-            end
+      # Create attributes
+      names.each do |name|
+        raise "Invalid attribute name: #{name.inspect}" unless name.is_a?(String) or name.is_a?(Symbol)
+        safe_name= name.to_s.sub /[!?]$/, ''
+        dvar= "@__gu_attr_decl_#{safe_name}_default"
+        ivar= "@#{safe_name}"
+        meth_w= "#{safe_name}="
+        meth_r= name
 
-          EOB
-          instance_variable_set dvar.to_sym, lambda{ default } unless default.nil?
-        end
+        class_eval <<-EOB
 
+          def #{meth_w}(value)
+            #{ivar} = value
+          end
 
-            #{default.nil? ? '' : "instance_variable_set :#{dvar}, block
-                #{default.nil? ? 'nil' : "@#{name}= (#{default.inspect})"}
-      end
-    end
+          def #{meth_r}
+            if instance_variable_defined? :#{ivar}
+              #{ivar}
+            elsif d= ::GollyUtils::AttrDeclarative.get_default(:#{dvar}, self.class)
+              #{ivar}= d
+            else
+              #{required ? %[raise "Attribute '#{name}' required by #{self} but not set in #\{self.class}."] : 'nil'}
+            end
+          end
 
-    #-------------------------------------------------------------------------------------------------------------------
+          def self.#{meth_r}(value)
+            instance_variable_set :#{dvar}, value
+          end
 
-    module InstanceAndClassMethods
+        EOB
+        instance_variable_set dvar.to_sym, default unless default.nil?
+      end
+      nil
     end
 
-    #-------------------------------------------------------------------------------------------------------------------
-
-    module InstanceMethods
-    end
   end
 end
+
+Object.extend GollyUtils::AttrDeclarative