cheap_advice 1.0.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,17 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "rspec", "~> 2.3.0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+  # Scarlet
+  gem 'open4'
+  gem 'RedCloth'
+  gem 'rtex'
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Kurt Stephens
+
+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.rdoc

@@ -0,0 +1,70 @@
+= cheap_advice
+
+Add/remove advice around, before or after methods in Ruby.
+
+== Example
+
+  class MyClass
+    def foo
+      42
+    end
+  end
+
+  class MyOtherClass
+    def bar
+      43
+    end
+  end
+
+  a = MyClass.new
+  b = MyOtherClass.new
+
+  trace_advice = CheapAdvice.new(:around) do | ar, body |
+    ar.advice[:log].puts "#{Time.now.iso8601(6)} #{ar.rcvr.class} #{ar.method} #{ar.rcvr.object_id}"
+    body.call
+    ar.advice[:log].puts "#{Time.now.iso8601(6)} #{ar.rcvr.class} #{ar.method} #{ar.rcvr.object_id} => #{ar.result.inspect}"    
+  end
+  trace_advice[:log] = File.open("trace.log", "a+")
+  trace_advice.advise!(MyClass, :foo)
+  trace_advice.advise!(MyOtherClass, :bar)
+
+
+  a.foo
+  b.bar
+
+  trace_advice.disable!
+
+  a.foo
+  b.bar
+
+trace.log will contain something like:
+
+  2011-01-17T16:33:27.882122-06:00 MyClass foo 69872883178280
+  2011-01-17T16:33:27.882262-06:00 MyClass foo 69872883178280 => 42
+  2011-01-17T16:33:27.882319-06:00 MyOtherClass bar 69872883178200
+  2011-01-17T16:33:27.882367-06:00 MyOtherClass bar 69872883178200 => 43
+
+== Other Features
+
+* CheapAdvice::Configuration provides a generic mechanism to configure multiple advices on different methods.
+* CheapAdvice::Trace provides an example advice factory for generic method tracing/logging.  See examples/ex02.rb.
+
+== Issues
+
+* Rails-type autoloading can confuse CheapAdvice.
+  
+== Contributing to cheap_advice
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2008-2011 Kurt Stephens. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,79 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "cheap_advice"
+  gem.homepage = "http://github.com/kstephens/cheap_advice"
+  gem.license = "MIT"
+  gem.summary = %Q{Add dynamic advice wrappers to methods.}
+  gem.description = %Q{http://kurtstephens.com/pub/cheap_advice.slides/index.html}
+  gem.email = "ks.github@kurtstephens.com"
+  gem.authors = ["Kurt Stephens"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :example do
+  Dir['example/ex*.rb'].sort.each do | ex |
+    cpid = Process.fork do 
+      load ex
+    end
+    Process.wait(cpid) or raise "#{ex} failed"
+  end
+end
+
+task :default => :spec
+task :default => :example
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "cheap_advice #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+$SCARLET = ENV['SCARLET'] ||= File.expand_path("../../scarlet/bin/scarlet", __FILE__)
+
+slides_src  = 'cheap_advice.slides.textile'
+slides_html = 'doc/cheap_advice.slides/index.html'
+file slides_html => slides_src do
+  slides_dir = File.dirname(slides_html)
+  sh "mkdir -p #{slides_dir}"
+  sh "#{$SCARLET} -f html -g #{slides_dir}"
+  sh "#{$SCARLET} -f html #{slides_src} > #{slides_html}"
+  sh "open #{slides_html}"
+end
+
+task :doc => slides_html
+
+task :publish => :doc do
+  sh "rsync -aruzv doc/cheap_advice.slides/ kscom:kurtstephens.com/pub/cheap_advice.slides/"
+end
+

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/cheap_advice.slides.textile

@@ -0,0 +1,257 @@
+!SLIDE
+!TITLE Cheap Advice
+
+h1. Cheap Advice
+
+* Kurt Stephens
+* Enova Financial -- "http://enovafinancial.com":http://enovafinancial.com
+* RubyConf 2011
+* Slides -- "http://kurtstephens.com/pub/cheap_advice.slides/index.html":http://kurtstephens.com/pub/cheap_advice.slides/index.html
+* Code -- "http://github.com/kstephens/cheap_advice":http://github.com/kstephens/cheap_advice
+
+!SLIDE
+!TITLE Clean Code
+
+h1. Clean Code
+
+@@@ ruby
+
+class MyClass
+  def foo; 42; end
+end
+class MyOtherClass
+  def bar; 43; end
+end
+a = MyClass.new
+b = MyOtherClass.new
+a.foo
+b.bar
+
+@@@
+
+!SLIDE
+!TITLE Add Logging
+
+h1. Add Logging
+
+@@@ ruby
+
+class MyClass
+  def foo
+    $stderr.puts "#{self}#foo => 42"
+    42
+  end
+end
+class MyOtherClass
+  def bar
+    $stderr.puts "#{self}#bar => 43"
+    43
+  end
+end
+a = MyClass.new
+b = MyOtherClass.new
+a.foo
+b.bar
+
+@@@
+
+!SLIDE
+!TITLE Add Security
+
+h1. Add Security
+
+@@@ ruby
+
+class MyClass
+  def foo
+    raise "SecurityError" unless $roles.include?("MyClass#foo")
+    $stderr.puts "#{self}#foo => 42"
+    42
+  end
+end
+class MyOtherClass
+  def bar
+    raise "SecurityError" unless $roles.include?("MyClass#bar")
+    $stderr.puts "#{self}#bar => 43"
+    43
+  end
+end
+a = MyClass.new
+b = MyOtherClass.new
+$roles = [ "MyClass#foo" ]
+a.foo
+b.bar
+
+@@@
+
+!SLIDE
+!TITLE YUCK!
+
+h1. ...YUCK!
+
+@@@ ruby
+
+class MyClass
+  def foo
+    # YUCK!: raise "SecurityError" unless $roles.include?("MyClass#foo")
+    # YUCK!: $stderr.puts "#{self}#foo => 42"
+    42
+  end
+end
+class MyOtherClass
+  def bar
+    # YUCK!: raise "SecurityError" unless $roles.include?("MyClass#bar")
+    # YUCK!: $stderr.puts "#{self}#bar => 43"
+    43
+  end
+end
+a = MyClass.new
+b = MyOtherClass.new
+$roles = [ "MyClass#foo" ] # ???
+a.foo
+b.bar
+
+@@@
+
+
+!SLIDE
+!TITLE Dumb and Clean, Smart and Dirty
+
+h1. Dumb and Clean, Smart and Dirty
+
+* Real World is Smart Code.
+* Dumb Code is Clean, Smart Code is Dirty. 
+* Get Dirt Out Of Code -- (problem-domain vs. solution-domain) 
+* Sweep It Somewhere Else -- (modularize the smart dirt)
+* Don't be Dirty All the Time -- (dynamic, stateful dirt: logging, debugging, security, etc.)
+
+!SLIDE
+!TITLE Separation of Concerns
+
+h1. Separation of Concerns
+
+* Logging
+* Security
+
+... are not problem-domain issues.
+
+!SLIDE
+!TITLE Advice
+
+h1. Advice
+
+* Commonplace in the Lisp world, (esp. Emacs).
+* Advice is function that wraps another function: "before", "after" or "around".
+* Advice can be added or removed at run-time.
+
+!SLIDE
+!TITLE Advice != Aspects
+
+h1. Advice != Aspects
+
+* Aspects are woven into code based on complex "codepoint" criteria at build-time (or load-time).
+* Advice is applied to a more well-known constructs: applicable objects: functions, methods, etc.
+* Advice are objects.
+* Advice can be added and removed at run-time.
+
+!SLIDE
+!TITLE Cheap Advice
+
+h1. Cheap Advice
+
+* ... adds dynamic Advice to Ruby methods.
+* ... is applied to methods.
+* ... are stateful objects.
+* ... can be added and removed at run-time.
+* ... are configurable.
+
+!SLIDE
+!TITLE Logging Advice
+
+h1. Logging Advice
+
+@@@ ruby
+
+# Advice 
+trace_advice = CheapAdvice.new(:around) do | ar, body |
+  ar.advice[:log] << 
+    "#{Time.now.iso8601(6)} " <<
+    "#{ar.rcvr.class} #{ar.meth} #{ar.rcvr.object_id}\n"
+  body.call
+  ar.advice[:log] << 
+    "#{Time.now.iso8601(6)} " <<
+    "#{ar.rcvr.class} #{ar.meth} #{ar.rcvr.object_id} " <<
+    "=> #{ar.result.inspect}\n"    
+end
+# State attached to trace_advice.
+trace_advice[:log] = File.open("trace.log", "a+")
+
+@@@
+
+!SLIDE
+!TITLE Applying Advice
+
+h1. Applying Advice
+
+@@@ ruby
+
+...
+# Activate trace_advice:
+trace_advice.advise!(MyClass, :foo)
+trace_advice.advise!(MyOtherClass, :bar)
+a.foo
+b.bar
+
+# Disable trace_advice:
+trace_advice.disable!
+a.foo
+b.bar
+@@@
+
+!SLIDE
+!TITLE Configuration
+
+h1. Configuration
+
+@@@ yaml
+
+:advice:
+  ~:
+    :enabled: false
+    :options:
+      :trace:
+        :logger:
+          :name: :default
+
+  'MyClass':
+    :advice:  trace
+
+  'MyClass#foo':
+    :enabled: false
+
+  'MyClass#bar':
+    :enabled: false
+
+@@@
+
+!SLIDE
+!TITLE Security Advice
+
+h1. Security Advice
+
+You get the idea.
+
+!SLIDE
+!TITLE Example
+
+h1. See example/ex01.rb
+
+!SLIDE
+!TITLE CheapAdvice
+
+h1. Questions?
+
+h1. Code!
+
+http://github.com/kstephens/cheap_advice
+