blockbuilder 0.0.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.komodoproject
+.komodotools

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Christopher Thornton
+
+MIT License
+
+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/README.md

@@ -0,0 +1,168 @@
+BlockBuilder
+============
+Make callbacks easily and build blocks with ease! BlockBuilder is intended to be used with more heavy weight method calls that might require intermediate callbacks. It's almost like creating classes on the fly!
+
+## Usage
+Some code samples to get you started:
+
+### File Download Example
+Downloading a file probably doesn't merit the block builder, but it demonstrates the concept of callbacks.
+
+```ruby
+def download_file(url, &block)
+  
+  # Configure your block here, along with defaults
+  builder = BlockBuilder.build block do
+    
+    # Set optional default variables!
+    set :verbose, true
+    
+    on_fail do |http_code, body|
+      puts "Oh no! HTTP download failed! Code: #{http_code}"
+      puts "Downloaded body: #{body}" if verbose
+    end
+    
+    on_success do |body|
+      puts "Downloaded file Successfully!"
+    end
+  end
+  
+  # Now execute your blocks! Note you don't have to explicitly
+  # define any of your callbacks.
+  result = download_some_file_from_internet(url)
+  if result.http_code == 200
+    builder.on_success.call result.body
+  else
+    builder.on_fail.call result.http_code, result.body
+  end
+  
+end
+
+
+# Now you can call the method above and change the defaults!
+download_file "example.com/exists.txt" do
+  on_success do |body|
+    File.open('some/file.txt', 'w') {|f| f.write body }
+  end
+end
+
+# Only outputs "Oh no! HTTP download failed! Code: 404"
+download_file "example.com/doesnotexist.txt" do
+  set :verbose, false
+end
+```
+
+### Callbacks and Remote Data
+Sometimes you might connect to another service or API that contains critical information. And perhaps you need to query multiple times with this API to get the data you need. Callbacks can help with this!
+
+```ruby
+ As a convention, you should always document a block builder method and let consumers of
+# this method know how to use it!
+# @example
+#   # Here is a code sample on how to use this method, etc
+def create_remote_user(username, password, &block)
+  builder = BlockBuilder.build block do
+    set :logger, Logger.new
+    
+    # You can force the creation of a callback using the abstract operator. By default,
+    # without the abstract modifier, calling an undefined callback will simply do nothing
+    abstract :on_user_created
+  end
+  
+  # If any callbacks label as 'abstract' aren't defined, then code execution will
+  # never reach this line.
+  
+  # Here, you may first want to create the user and create a callback. This callback
+  # can then be used to quickly save an entry in the database before other operations
+  # are executed. This is useful, for example, if the server crashes during the middle
+  # of the request or there is a bug later in the method call. This way, at least you
+  # have the user information saved in your local database and you can retrieve the
+  # user information later.
+  result = api.create_user username, password
+  builder.on_user_created.call(result)
+
+  # Now we can keep on executing methods and have somewhere else take care of it. Using
+  # the set logger variable, we can allow someone to externally change the logger used.
+  #
+  # Now what if the connection timed out here? Or the server crashed? That's the point
+  # of the earlier callback! It allows you to save partial data without interfering
+  # with the internal logic of this method!
+  start = Time.now
+  result2 = api.some_very_time_intensive_call_involving(username)
+  builder.logger.info "Executed time intensive call in #{Time.now - start} sec!"
+  builder.on_finish_lengthy_task.call(result2)
+  
+  # Another fun use for this: collecting statistics! It might be useful to collect a
+  # bunch of statistics for a particular task. However, not every consumer of your
+  # method will care for statistics. Just for fun, let's only calculate some
+  # statistics about this method call only if they care to calculate stats!
+  #
+  # We use 'builder.defined?' here because doing
+  #
+  #   builder.generate_statistics.call(some_lengthy_statistic_compilation)
+  #
+  # will compile statistics, regardless of whether 'generate_statistics' is defined.
+  if builder.defined? :generate_statistics
+    stats = some_lengthy_statistic_compilation
+    builder.generate_statistics.call(stats)
+  end
+  
+  
+  # Now you can add any more callbacks as you see fit! And don't forget, you can still
+  # return some data from this method call if you want!
+end
+```
+
+Now you can use this method in multiple places. Here, assume this is where the code is primarily used:
+
+```ruby
+create_remote_user 'user', 'password' do
+  
+  # This easily lets us use our Rails logger
+  set :logger, Rails.logger
+  
+  # Remember, our abstract callback was declared, so we must define it here. In this
+  # case, assume we have a Ruby on Rails model that deals with saving saved data
+  on_user_created do |result|
+    u = RemoteUser.new(result)
+    u.some_misc_operations
+    u.save!
+  end
+end
+```
+
+Finally, assume this is some benchmark suite, or something else:
+
+```ruby
+# Assume this is some benchmark suite or testing file
+create_remote_user 'user', 'password' do
+  on_user_created do |result|
+    # .. Implement here
+  end
+  
+  # In this case, we might enjoy statistics
+  generate_statistics do |stats|
+    puts "Statistics for this operation:"
+    puts " * Total execution time: #{stats.exec_time}"
+    puts "..."
+  end
+  
+end
+```
+
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'blockbuilder'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install blockbuilder
+

data/Rakefile

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

data/blockbuilder.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'block_builder/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "blockbuilder"
+  gem.version       = BlockBuilder::VERSION
+  gem.authors       = ["Christopher Thornton"]
+  gem.email         = ["rmdirbin@gmail.com"]
+  gem.description   = %q{Make callbacks easily and build blocks with ease! BlockBuilder is intended to be used with more heavy weight method calls that might require intermediate callbacks. It's almost like creating classes on the fly!}
+  gem.summary       = %q{Create complex function callbacks with ease!}
+  gem.homepage      = "https://github.com/cgthornt/BlockBuilder"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+end

data/lib/block_builder.rb

@@ -0,0 +1,14 @@
+require "block_builder/version"
+require "block_builder/builder"
+require "block_builder/attribute"
+
+module BlockBuilder
+  
+  class << self
+  
+    def build(target_block, *options, &default_block)
+      return BlockBuilder::Builder.new(target_block, *options, &default_block)
+    end
+  end
+  
+end

data/lib/block_builder/attribute.rb

@@ -0,0 +1,46 @@
+module BlockBuilder
+  class Attribute
+    
+    attr_accessor :name, :block, :args, :parent_builder
+    
+    def initialize(parent_builder, name, args = nil, block = nil)
+      @name = name
+      @args = args || []
+      @block = block
+      @parent_builder = parent_builder
+    end
+    
+    
+    #def set_block(some_block)
+    #  block = some_block
+    #  # builder._build(some_block) if some_block.is_a?(Proc)
+    #end
+    
+    #def builder
+    #  @builder = BlockBuilder::Builder.new(block) if @builder.nil?
+    #  return @builder
+    #end
+    
+    def call(*args)
+      block.call(*args) if block?
+    end
+    
+    def block?
+      block.is_a?(Proc)
+    end
+    
+    def blank?
+      args.empty? and !block?
+    end
+    
+    def val; args.first; end
+    def value; val; end
+    def to_s; val; end
+    
+    def vals; args; end
+    def values; vals; end
+    
+    
+    
+  end
+end

data/lib/block_builder/builder.rb

@@ -0,0 +1,69 @@
+module BlockBuilder
+  class Builder
+    
+    attr_reader :_target_block, :_symbol_table, :_options, :_config_table, :_abstract_list
+
+
+    def initialize(target_block, *args, &default_block)
+      @_target_block = target_block
+      options = {}
+      options = args.pop if args.last.is_a?(Hash)
+      args.each{|a| options[a] = true }
+      @_options = options
+      @_symbol_table = Hash.new
+      @_config_table = Hash.new
+      @_abstract_list = Array.new
+      
+      # Default block, target block!
+      _build(default_block)
+      _build(target_block)
+      
+      # Now call them out on abstractness!
+      _abstract_list.each do |method|
+        raise ArgumentError, "Abstract callback '#{method}' must be defined" unless _symbol_table.key?(method)
+      end
+    end
+    
+    
+    def _build(block)
+      instance_eval(&block) if block.is_a?(Proc)
+    end
+    
+    def set(key, val)
+      _config_table[key] = val
+    end
+    
+    # Define methods as abstract, so they must be implemented
+    def abstract(*methods)
+      @_abstract_list = _abstract_list | methods
+    end
+
+    def method_missing(method, *args, &block)
+      if _config_table.key?(method) and args.empty? and !block_given?
+        return _config_table[method]
+      end
+      
+      method = method.to_s.chomp('=').to_sym if method.to_s[-1] == "="
+      
+      attribute = _symbol_table[method]
+      if attribute.nil?
+        attribute = Attribute.new(self, method)
+        _symbol_table[method] = attribute
+      end
+      
+      # Read attribute if no params
+      return attribute if args.empty? and !block_given?
+      
+      attribute.args  = args
+      attribute.block = block if block_given?
+      
+      return attribute
+    end
+    
+    def defined?(method_call)
+      _symbol_table.key?(method_call)
+    end
+    
+    
+  end
+end

data/lib/block_builder/version.rb

@@ -0,0 +1,3 @@
+module BlockBuilder
+  VERSION = "0.0.1"
+end

data/test/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gem "blockbuilder", :path => '../'

data/test/testit.rb

@@ -0,0 +1,101 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'block_builder'
+
+
+# As a convention, you should always document a block builder method and let consumers of
+# this method know how to use it!
+# @example
+#   # Here is a code sample on how to use this method, etc
+def create_remote_user(username, password, &block)
+  builder = BlockBuilder.build block do
+    set :logger, Logger.new
+    
+    # You can force the creation of a callback using the abstract operator. By default,
+    # without the abstract modifier, calling an undefined callback will simply do nothing
+    abstract :on_user_created
+  end
+  
+  # If any callbacks label as 'abstract' aren't defined, then code execution will
+  # never reach this line.
+  
+  # Here, you may first want to create the user and create a callback. This callback
+  # can then be used to quickly save an entry in the database before other operations
+  # are executed. This is useful, for example, if the server crashes during the middle
+  # of the request or there is a bug later in the method call. This way, at least you
+  # have the user information saved in your local database and you can retrieve the
+  # user information later.
+  result = api.create_user username, password
+  builder.on_user_created(result)
+
+  # Now we can keep on executing methods and have somewhere else take care of it. Using
+  # the set logger variable, we can allow someone to externally change the logger used.
+  #
+  # Now what if the connection timed out here? Or the server crashed? That's the point
+  # of the earlier callback! It allows you to save partial data without interfering
+  # with the internal logic of this method!
+  start = Time.now
+  result2 = api.some_very_time_intensive_call_involving(username)
+  builder.logger.info "Executed time intensive call in #{Time.now - start} sec!"
+  builder.on_finish_lengthy_task.call(result2)
+  
+  # Another fun use for this: collecting statistics! It might be useful to collect a
+  # bunch of statistics for a particular task. However, not every consumer of your
+  # method will care for statistics. Just for fun, let's only calculate some
+  # statistics about this method call only if they care to calculate stats!
+  #
+  # We use 'builder.defined?' here because doing
+  #
+  #   builder.generate_statistics.call(some_lengthy_statistic_compilation)
+  #
+  # will compile statistics, regardless of whether 'generate_statistics' is defined.
+  if builder.defined? :generate_statistics
+    stats = some_lengthy_statistic_compilation
+    builder.generate_statistics.call(stats)
+  end
+  
+  
+  # Now you can add any more callbacks as you see fit! And don't forget, you can still
+  # return some data from this method call if you want!
+end
+
+
+create_remote_user 'user', 'password' do
+  
+  # This easily lets us use our Rails logger
+  set :logger, Rails.logger
+  
+  # Remember, our abstract callback was declared, so we must define it here. In this
+  # case, assume we have a Ruby on Rails model that deals with saving saved data
+  on_user_created do |result|
+    u = RemoteUser.new(result)
+    u.some_misc_operations
+    u.save!
+  end
+end
+
+
+# Assume this is some benchmark suite or testing file
+create_remote_user 'user', 'password' do
+  on_user_created do |result|
+    # .. Implement here
+  end
+  
+  # In this case, we might enjoy statistics
+  generate_statistics do |stats|
+    puts "Statistics for this operation:"
+    puts " * Total execution time: #{stats.exec_time}"
+    puts "..."
+  end
+  
+end
+
+
+
+puts "Testing!"
+def test(&block)
+  builder = BlockBuilder.build block do
+    abstract :my_method
+  end
+  builder.my_method.call
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: blockbuilder
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Christopher Thornton
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-23 00:00:00.000000000 Z
+dependencies: []
+description: Make callbacks easily and build blocks with ease! BlockBuilder is intended
+  to be used with more heavy weight method calls that might require intermediate callbacks.
+  It's almost like creating classes on the fly!
+email:
+- rmdirbin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- blockbuilder.gemspec
+- lib/block_builder.rb
+- lib/block_builder/attribute.rb
+- lib/block_builder/builder.rb
+- lib/block_builder/version.rb
+- test/Gemfile
+- test/testit.rb
+homepage: https://github.com/cgthornt/BlockBuilder
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Create complex function callbacks with ease!
+test_files:
+- test/Gemfile
+- test/testit.rb
+has_rdoc: