alter 0.0.1

data/.gitignore

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

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 David Baldwin
+
+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,116 @@
+# Alter
+
+Passing something like a blog post through many complex filters (Markdown, Liquid, regex, Nokogiri, etc) can get ugly and difficult to test and debug. Alter enforces structure and consistency by moving each filter to easy-to-write processor classes. It also keeps a handy history of all "alterations". The source is a mere 50 lines of code, so it should be easy to read and extend.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'alter'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install alter
+
+## Usage
+
+Suppose you are building a blog and you want to run posts through a number of filters when converting to HTML. You might run it through Liquid, then Markdown, then do some crazy Nokogiri stuff, then rewrite YouTube URLs to embedded videos, then sanitize, do some regex replaces, etc. And maybe you want to run it through only some filters in one area of the site, but all filters in other areas. This can quickly get ugly and disorganized.
+
+Alter gives you structure and consistency by passing text (or really anything) through easy to write processor classes. All you need to do is inherit from `Alter::Processor` and provide an `output` method.
+
+<pre lang="ruby"><code>
+class KumbayaProcessor &#60; Alter::Processor
+  def output
+    input.gsub("sucks", "is great")
+  end
+end
+</code></pre>
+    
+You will already have access to the `input` attribute. You are simply delivering the `output` based upon the `input`. To use the processor, you will first create a new Alter item which will setup that initial `input` value.
+
+<pre lang="ruby"><code>
+text = Alter::Item.new "Your language sucks"
+</code></pre>
+    
+Now you can run that item through the processor by passing the `KumbayaProcessor` class to the process method. The process method also accepts an array of processors.
+
+<pre lang="ruby"><code>
+text.process KumbayaProcessor
+# result: "Your language is great"
+</code></pre>
+    
+You will also have access to any `options` passed to the processor. Here is a class making use of `options`.
+
+<pre lang="ruby"><code>
+class EligibilityProcessor &#60; Alter::Processor
+  def output
+    if options[:age] >= 35
+      input + " and you could run for President"
+    else
+      input + " but you're too young to be President"
+    end
+  end
+end
+
+text = Alter::Item.new "Your language sucks", :age => 37
+text.process [KumbayaProcessor, EligibilityProcessor]
+# result: "Your language is great and you could run for President"
+</code></pre>
+    
+You can just as easily chain or separate these process calls. Options can also be passed to the process method if you only want them available to specific processors.
+
+<pre lang="ruby"><code>
+text = Alter::Item.new "Your language sucks"
+text.process KumbayaProcessor
+text.process EligibilityProcessor, :age => 33
+# result: "Your language is great but you're too young to be President"
+</code></pre>
+    
+### History
+
+Alter keeps a history of every "alteration" made to the original input and stores it in the `history` array.
+
+<pre lang="ruby"><code>
+pp text.history.collect {|h| {:processor => h.processor, :input => h.input, :output => h.output, :options => h.options, :meta => h.meta}}
+</code></pre>
+
+<pre lang="console"><code>
+result:  
+[{:processor=>KumbayaProcessor,
+  :input=>"Your language sucks",
+  :output=>"Your language is great",
+  :options=>{},
+  :meta=>nil},
+ {:processor=>EligibilityProcessor,
+  :input=>"Your language is great",
+  :output=>"Your language is great but you're too young to be President",
+  :options=>{:age=>33},
+  :meta=>nil}]
+</code></pre>
+        
+### Metadata
+
+Extra metadata can be written to the history by providing a `meta` method in the processor class.
+
+<pre lang="ruby"><code>
+class UselessProcessor &#60; Alter::Processor
+  def meta
+    { 
+      :random => "This is so #{rand(1000)}",
+      :data => "This is so meta"
+    }
+  end
+end
+</code></pre>
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/alter.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/alter/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["David Baldwin"]
+  gem.email         = ["baldwindavid@gmail.com"]
+  gem.description   = %q{Enforce structure by moving content filters to easy-to-write processor classes}
+  gem.summary       = %q{Alter enforces structure by moving content filters to easy-to-write processor classes}
+  gem.homepage      = ""
+  
+  gem.add_development_dependency "rspec"
+
+  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.name          = "alter"
+  gem.require_paths = ["lib"]
+  gem.version       = Alter::VERSION
+end

data/lib/alter.rb

@@ -0,0 +1,54 @@
+require "alter/version"
+
+module Alter
+  
+  class Item
+    attr_accessor :value, :history, :options
+    attr_reader :input
+    
+    def initialize(input, options = {})
+      @input = input
+      @value = input
+      @options = options
+      @history = []
+    end
+
+    def process(processors = [], mergeable_options = {})
+      merged_options = options.merge(mergeable_options)
+      
+      [processors].flatten.each do |processor|
+        run_processor(processor.new(value, merged_options))
+      end
+      
+      value
+    end
+    
+    def run_processor(processor)
+      self.value = processor.output
+      self.history << Alter::Alteration.new(:processor => processor.class, :input => processor.input, :output => processor.output, :options => processor.options, :meta => processor.meta)
+    end
+  end
+  
+  class Alteration
+    attr_accessor :processor, :input, :output, :options, :meta
+    
+    def initialize(attrs = {})
+      attrs.each { |k, v| self.send("#{k}=", v) }
+    end
+  end
+
+  class Processor
+    attr_accessor :output, :meta
+    attr_reader :input, :options
+
+    def initialize(input, options = {})
+      @input = input
+      @options = options
+    end
+    
+    def output
+      input
+    end
+  end
+
+end

data/lib/alter/version.rb

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

data/spec/item_spec.rb

@@ -0,0 +1,95 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Item" do
+  
+  before :each do
+    
+    class TextProcessor < Alter::Processor
+      def output
+        input + " + output"
+      end
+      
+      def meta
+        {
+          :color => "blue",
+          :rand => rand(1000)
+        }
+      end
+    end
+    
+    class FirstProcessor < Alter::Processor
+      def output
+        input + " + first"
+      end
+    end
+    
+    class SecondProcessor < Alter::Processor
+      def output
+        input + " + second"
+      end
+    end
+    
+    class EligibilityProcessor < Alter::Processor
+      def output
+        if options[:age] >= 35
+          input + " + President eligible"
+        else
+          input + " + Too young to be President"
+        end
+      end
+    end
+    
+  end
+
+  it "should update the value based upon a custom output method in a processor" do
+    @item = Alter::Item.new "Initial text"
+    @item.process TextProcessor
+    @item.value.should == "Initial text + output"
+  end
+
+  it "should allow an array of processors to be passed via the process method" do
+    @item = Alter::Item.new "Initial text"
+    @item.process [FirstProcessor, SecondProcessor]
+    @item.value.should == "Initial text + first + second"
+  end
+  
+  it "should allow processors to be chained" do
+    @item = Alter::Item.new "Initial text"
+    @item.process FirstProcessor
+    @item.value.should == "Initial text + first"
+    @item.process SecondProcessor
+    @item.value.should == "Initial text + first + second"
+  end 
+  
+  it "should write history to the item" do
+    @item = Alter::Item.new "Initial text"
+    @item.process [FirstProcessor, SecondProcessor]
+    @item.history.size.should == 2
+  end
+    
+  it "should attach meta data to the history if provided" do
+    @item = Alter::Item.new "Initial text"
+    @item.process TextProcessor
+    @item.history.first.meta[:color].should == "blue"
+  end 
+  
+  it "should write a static alteration record to the history" do
+    @item = Alter::Item.new "Initial text"
+    @item.process TextProcessor
+    first_request = @item.history.first.meta[:rand]
+    @item.history.first.meta[:rand] == first_request
+  end
+  
+  it "should allow passing options via the item" do
+    @item = Alter::Item.new "Initial text", :age => 36
+    @item.process EligibilityProcessor
+    @item.value.should == "Initial text + President eligible"
+  end
+  
+  it "should allow passing options via the process method" do
+    @item = Alter::Item.new "Initial text"
+    @item.process EligibilityProcessor, :age => 32
+    @item.value.should == "Initial text + Too young to be President"
+  end
+  
+end

data/spec/processor_spec.rb

@@ -0,0 +1,44 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Processor" do
+  
+  before :each do
+    
+    class TextProcessor < Alter::Processor
+      def output
+        input + " + output"
+      end
+    end
+    
+    class UselessProcessor < Alter::Processor
+    end
+    
+    class EligibilityProcessor < Alter::Processor
+      def output
+        if options[:age] >= 35
+          input + " + President eligible"
+        else
+          input + " + Too young to be President"
+        end
+      end
+    end
+    
+  end
+  
+  it "should produce an output based upon a custom output method" do
+    @processor = TextProcessor.new "Initial text" 
+    @processor.output.should == "Initial text + output"
+  end 
+
+  it "should have an output equal to its input if no custom output method is provided" do
+    @processor = UselessProcessor.new "Initial text"
+    @processor.output.should == "Initial text"
+  end
+  
+  it "should allow changing output based upon options" do
+    @processor = EligibilityProcessor.new "Initial text", :age => 42
+    @processor.output.should == "Initial text + President eligible"
+  end
+
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'alter'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: alter
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- David Baldwin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-23 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70266420215180 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70266420215180
+description: Enforce structure by moving content filters to easy-to-write processor
+  classes
+email:
+- baldwindavid@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- alter.gemspec
+- lib/alter.rb
+- lib/alter/version.rb
+- spec/item_spec.rb
+- spec/processor_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+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.10
+signing_key: 
+specification_version: 3
+summary: Alter enforces structure by moving content filters to easy-to-write processor
+  classes
+test_files:
+- spec/item_spec.rb
+- spec/processor_spec.rb
+- spec/spec_helper.rb