texttube 6.1.0 → 7.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 610f0fe430a90ce6e8de9b697d41e81029cdd82c
-  data.tar.gz: a334d2477567f2be643d05076866fb4fd6f41e1e
+  metadata.gz: 3b2a5ba68a11010904a881a8aa8d05f96cbd4cb4
+  data.tar.gz: bb6e54ec1473035c6b0324ad51dc885edc04bea7
 SHA512:
-  metadata.gz: eb605ac48e32f2cb5066fddeaab12be996435e5517d205f774f4957e7530b2fd174ec0e7b64e092907f69e2418470762de03a63f0a059ff3b8cd2cbf8009ab1a
-  data.tar.gz: c9df73120109399f0efd543c46f5c521c76f05a42bb6fde52b75e91321012d2c6cf75c8369dc2ff455abc5066b4a3e332d43fb0045e15292520f532fd805072c
+  metadata.gz: 7e4018b23e62df19927781d886e74b6666f5fd2756b05a9f69532fe2be9874f5beef2ca6b2c0760879f682a2731cfcc8a6b5a7eb20b365155330da3d4af528bb
+  data.tar.gz: 423f6494980562823c69298a183a1a30c583d41387935bc758cde142c493f6427aa2ca2be142bd1940160506771382bbebc9057f9169f2b51de9800d3b58f1d2

data/.gitignore

@@ -22,5 +22,6 @@ vendor/
 vendor.noindex/
 coverage/
 docs/
+doc/
 .yardoc/
 .bundle/

data/.travis.yml

@@ -1,10 +1,21 @@
 language: ruby
 rvm:
-  - 1.9.3
   - 2.0.0
+  - 2.1.0
+  - 2.2.2
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx
+  - ruby-head
+  - jruby-head
 
 # whitelist
 branches:
   only:
     - master
     - develop
+
+matrix:
+  allow_failures:
+    - rvm: jruby-head
+    - rvm: ruby-head
+    - rvm: rbx

data/CHANGES.md

@@ -1,5 +1,21 @@
 # CH CH CH CHANGES! #
 
+## Sunday the 14th of June 2015# 
+
+# v7.0.1 ##
+
+* Added fences to code block in example.
+
+----
+
+# v7.0.0 #
+
+* Added more examples of how to use options.
+* Cleaned up the options a lot, clarified and better tested.
+* Fixed the ever moving target of the Travis-CI settings.
+
+----
+
 
 ## Friday the 12th of June 2015, v6.1.0 ##
 

data/Gemfile

@@ -1,4 +1,4 @@
-# A sample Gemfile
+RUBY_ENGINE = 'ruby' unless defined? RUBY_ENGINE
 source "https://rubygems.org"
 
 gemspec
@@ -7,19 +7,17 @@ gem "rake"
 
 group :documentation do
   gem "yard"
-  gem "rdiscount"
+  gem "kramdown"
 end
 
 group :development do
-  gem "rdiscount"
-  gem "wirble"
+  unless RUBY_ENGINE == 'jruby' || RUBY_ENGINE == "rbx"
+    gem "pry-byebug"
+  end
 end
 
 group :test do
   gem "rspec"
   gem "simplecov", :require => false
-  gem "maruku"
-  gem "rdiscount"
-  gem "kramdown"
   gem "rspec-its"
 end

data/README.md

@@ -139,6 +139,115 @@ s.filter
 # => "Let me introduce <a href="iainbarnett.me.uk" title="My blog">Iain Barnett</a>. He writes Ruby code. ©2013. Let me introduce <a href="iainbarnett.me.uk" title="My blog">Iain Barnett</a>. He writes Ruby code. ©2013. "
 ```
 
+### Options ###
+
+There are 3 types of options available:
+
+#### Class options ####
+
+These options are available for all instances of that class. One was used in the previous example:
+
+```ruby
+MyString.options.merge! :number => {times: 2}
+```
+
+#### Instance options ####
+
+Using this type of option will mean that option is used with this instance and no other. It will override class options:
+
+```ruby
+m = NeuS.new "abc", :order=>[:dashes, :double, :spacial]
+m.filter # will use :dashes, :double, :spacial
+```
+
+#### Method options ####
+
+These will affect only this call of the `filter` method:
+
+```ruby
+# this does :triple, :dashes, :spacial
+m.filter :order=>[:triple, :dashes, :spacial]
+# this does :dashes, :double, :spacial
+m.filter
+```
+
+Of course, if you just want to effect the order in a one off call then `m.filter :triple, :dashes, :spacial` would work just as well.
+
+If you have several filters and you want to pass some options then you need give the name of the filter along with the options. Here's an example:
+
+```ruby
+class FutureString < TextTube::Base
+  register do
+    filter_with :read_more do |text,options|
+      text + " " + options.fetch(:teaser, "READ MORE")
+    end
+    filter_with :add_title do |text,options|
+      title = "#{options.fetch(:title, 'My article')}\n\n"
+      title + text
+    end
+  end
+end
+
+future = FutureString.new "It's looking bright!"
+future.filter :read_more =>{teaser: "carry on reading…"}, :add_title =>{title: "Feeling optimistic"}
+```
+
+Which would output:
+
+> Feeling optimistic
+> 
+> It's looking bright! carry on reading…
+
+You can see from this example that you can register more than one filter on the fly within a register block.
+
+
+#### Overrides ####
+
+Keep in mind that class options are overriden by instance options, and instance options (and class options) are overriden by method options.
+
+#### Note! ####
+
+Options are only applied if you pass a block with the 2nd options argument available. For example, this will apply options:
+
+```ruby
+class Optional < TextTube::Base
+  register do
+    filter_with :something_with_options do |text,options|
+      extras = options.fetch :extra, " "
+      text + extras + "This should be ok."
+    end
+  end
+end
+
+This will not:
+
+class Optional < TextTube::Base
+  register do
+    filter_with :something_without_options do |text|
+      text + options + "This will throw an error."
+    end
+  end
+end
+```
+
+If you don't plan to use the options then don't provide them as an argument, but don't refer to them in the block, e.g.
+
+```ruby
+class NotBothered < TextTube::Base
+  register do
+    filter_with :something_without_options do |text|
+      text + "We're just not giving you the option."
+    end
+  end
+end
+```
+
+
+### All of these examples have been used as specs ###
+
+Take a look and run them.
+
+
 ### Ready made filters ###
 
 They used to come with this library, but sometimes they caused problems with installation (things like Nokogiri can be painful to install at times) so I spun them off into their own library - [TextTubeBaby](https://github.com/yb66/TextTubeBaby)!

data/Rakefile

@@ -2,11 +2,11 @@
 
 desc "(Re-) generate documentation and place it in the docs/ dir."
 task :docs => :"docs:yard"  
-namespace :docs do
+namespace :doc do
   require 'yard'
   YARD::Rake::YardocTask.new do |t|
     t.files   = ['lib/**/*.rb']
-    t.options = ['-odocs/', '--no-private']
+    t.options = ['-odoc/', '--no-private']
   end
 
   desc "Docs including private methods."

data/lib/texttube.rb

@@ -0,0 +1,2 @@
+require_relative "texttube/base.rb"
+require_relative "texttube/filterable.rb"

data/lib/texttube/base.rb

@@ -58,11 +58,6 @@ module TextTube
 
     class << self
 
-      # Global options. Every descendant will get these.
-      def options
-        @options ||= {}
-      end
-
       # remove all filters
       # @todo remove methods too.
       def reset!
@@ -112,6 +107,13 @@ module TextTube
       # @private
       def inherited(subclass)
         subclass.reset!
+        
+        # Per class options
+        subclass.instance_eval do
+          def options
+            @options ||= {}
+          end
+        end
       end
     end
 
@@ -142,8 +144,9 @@ module TextTube
       else
         order,options = order_and_options, {}
       end
-      order = order.flatten
-      order = @options.fetch :order, self.class.filters if order.empty?
+      options = self.class.options.merge(@options.merge(options))
+      order.flatten!
+      order = options.fetch :order, self.class.filters if order.empty?
       order.inject(self){|current,filter|
         send filter, current, options
       }

data/lib/texttube/filterable.rb

@@ -35,17 +35,13 @@ module TextTube
       name = name.to_sym
       filters << name unless filters.include? name
       define_method name do |current=self, options=nil|
-        if current.respond_to? :keys
-          options=current
-          current=self
-        end
         options = [options, @options, self.class.options].find{|opts|
           !opts.nil? && 
           opts.respond_to?(:keys) && 
           !opts.empty?
         } || {}
 
-        block.call current, options[name]
+        block.call current, (options[name] || {})
       end
     end
 

data/lib/texttube/version.rb

@@ -2,5 +2,5 @@
 
 module TextTube
   # This library's version.
-  VERSION = "6.1.0"
+  VERSION = "7.0.1"
 end

data/spec/base_spec.rb

@@ -15,16 +15,27 @@ describe Base do
 			its(:options) { should be_empty }
 		end
 		context "Class methods and their defaults" do
+		  shared_examples "any instance from a kind of Base" do
+        it { should respond_to :reset! }
+        it { should respond_to :filters }
+        its(:filters) { should respond_to :empty? }
+        its(:filters) { should be_empty }
+        it { should respond_to :register }
+        it { should respond_to :inherited }
+      end
 			subject { Base }
-			it { should respond_to :options }
-			its(:options) { should respond_to :empty? }
-			its(:options) { should be_empty }
-			it { should respond_to :reset! }
-			it { should respond_to :filters }
-			its(:filters) { should respond_to :empty? }
-			its(:filters) { should be_empty }
-			it { should respond_to :register }
-			it { should respond_to :inherited }
+			it { should_not respond_to :options }
+			it_should_behave_like "any instance from a kind of Base"
+			context "when subclassed" do
+			  before :all do
+			    SubClassed = Class.new TextTube::Base
+			  end
+			  subject { SubClassed }
+        it { should respond_to :options }
+        its(:options) { should respond_to :empty? }
+        its(:options) { should be_empty }
+        it_should_behave_like "any instance from a kind of Base"
+      end
 		end
 	end
 end

data/spec/examples_spec.rb

@@ -5,6 +5,8 @@ require_relative "../lib/texttube/filterable.rb"
 
 module TextTube # for convenience
 
+TimeNow = "2060" # According to Sir Isaac Newton's research of the Bible, the world will end in this year!
+
 describe "Example usage" do
 	before :all do
 		module AFilter
@@ -27,6 +29,18 @@ describe "Example usage" do
 			end
 		end
 
+    module AnotherFilter
+      extend TextTube::Filterable
+
+      filter_with :copyright do |text|
+        text << " ©#{TimeNow}. "
+      end
+
+      filter_with :number do |text,options|
+        text * options[:times].to_i
+      end
+    end
+
 		class NeuS < TextTube::Base
 			register BFil
 			register AFilter
@@ -36,28 +50,217 @@ describe "Example usage" do
 				end
 			end
 		end
+
+    class NewerS < TextTube::Base
+			register BFil
+			register AFilter
+			register do
+				filter_with :dashes do |text|
+					"---#{text}---"
+				end
+			end
+		end
+
+    class Optional < TextTube::Base
+      register do
+        filter_with :something_with_options do |text,options|
+          extras = options.fetch :extra, " "
+          text + extras + "This should be ok."
+        end
+      end
+      register do
+        filter_with :something_without_options do |text|
+          text + options + "This will throw an error."
+        end
+      end
+    end
+
+    class FutureString < TextTube::Base
+      register do
+        filter_with :read_more do |text,options|
+          text + " " + options.fetch(:teaser, "READ MORE")
+        end
+        filter_with :add_title do |text,options|
+          title = "#{options.fetch(:title, 'My article')}\n\n"
+          title + text
+        end
+      end
+    end
+
 	end # before
 
-	context "Instantiation" do
+	context "Simple" do
 		let(:n) { NeuS.new "abc" }
+    let(:the_no_options_filtered_result){ "---a b ca b ca b ca b ca b ca b c---" }
 		subject { n }
 		it { should == "abc" }
 
 		context "filtering" do
 			context "With no arguments" do
 				subject { n.filter }
-				it { should == "---a b ca b ca b ca b ca b ca b c---" }
+				it { should == the_no_options_filtered_result }
 			end
 			context "Given a specific filter" do
 				subject { n.filter :spacial }
 				it { should == "a b c" }
+        it { should_not == the_no_options_filtered_result }
 			end
 			context "Given several specific filters" do
 				subject { n.filter :spacial, :dashes, :spacial }
 				it { should == "- - - a   b   c - - -" }
+        it { should_not == the_no_options_filtered_result }
 			end
 		end
 	end
+	context "with options passed to the instance" do
+	  context "To set the order" do
+      let(:n) { NeuS.new "abc", :order=>[:spacial, :dashes, :spacial] }
+      let(:the_no_options_filtered_result){ "- - - a   b   c - - -" }
+      subject { n }
+      it { should == "abc" }
+      context "filtered" do
+        subject { n.filter }
+        it { should == the_no_options_filtered_result }
+        context "and then given method options" do
+          subject { n.filter :order=>[:triple, :dashes, :spacial] }
+          it { should == "- - - a b c a b c a b c - - -" }
+          it { should_not == the_no_options_filtered_result }
+        end
+      end
+      context "with a different instance" do
+        let(:m) { NeuS.new "def" }
+        subject { m }
+        it { should == "def" }
+        context "filtered" do
+          subject { m.filter }
+          it { should_not == "- - - d   e   f - - -" }
+          it { should_not == the_no_options_filtered_result }
+        end
+        context "and given instance options" do
+          let(:k) { NeuS.new "abc", :order=>[:dashes, :double, :spacial] }
+          subject { k }
+          it { should == "abc" }
+          context "filtered" do
+            subject { k.filter }
+            it { should == "- - - a b c - - - - - - a b c - - -" }
+            it { should_not == the_no_options_filtered_result }
+          
+            context "and then given method options" do
+              subject { k.filter :order=>[:triple, :dashes, :spacial] }
+              it { should == "- - - a b c a b c a b c - - -" }
+              it { should_not == the_no_options_filtered_result }
+            end
+          end
+        end
+      end
+      context "with a different class" do
+        let(:n) { NewerS.new "abc" }
+        subject { n }
+        it { should == "abc" }
+        context "filtered" do
+          subject { n.filter }
+          it { should == "---a b ca b ca b ca b ca b ca b c---" }
+          it { should_not == the_no_options_filtered_result }
+        end        
+      end
+    end
+	end
+	context "with class options" do
+	  context "To set the order" do
+	    before :all do
+	      NeuS.options.merge! :order=>[:spacial, :dashes, :spacial]
+	    end
+      let(:n) { NeuS.new "abc" }
+      let(:the_no_options_filtered_result){ "- - - a   b   c - - -" }
+      subject { n }
+      it { should == "abc" }
+      context "filtered" do
+        subject { n.filter }
+        it { should == the_no_options_filtered_result }
+      end
+      context "and given method options" do
+        subject { n.filter :order=>[:dashes, :double, :spacial] }
+        it { should == "- - - a b c - - - - - - a b c - - -" }
+        it { should_not == the_no_options_filtered_result }
+      end
+      context "with a different instance" do
+        let(:m) { NeuS.new "def" }
+        subject { m }
+        it { should == "def" }
+        context "filtered" do
+          subject { m.filter }
+          it { should == "- - - d   e   f - - -" }
+        end        
+      end
+      context "with a different class" do
+        let(:n) { NewerS.new "abc" }
+        subject { n }
+        it { should == "abc" }
+        context "filtered" do
+          subject { n.filter }
+          it { should == "---a b ca b ca b ca b ca b ca b c---" }
+          it { should_not == the_no_options_filtered_result }
+        end        
+      end
+      context "and given instance options" do
+        let(:m) { NeuS.new "abc", :order=>[:dashes, :double, :spacial] }
+        subject { m }
+        it { should == "abc" }
+        context "filtered" do
+          subject { m.filter }
+          it { should == "- - - a b c - - - - - - a b c - - -" }
+          it { should_not == the_no_options_filtered_result }
+          
+          context "and then given method options" do
+            subject { m.filter :order=>[:triple, :dashes, :spacial] }
+            it { should == "- - - a b c a b c a b c - - -" }
+            it { should_not == the_no_options_filtered_result }
+          end
+        end
+      end
+    end
+	end
+
+  describe "Naming options" do
+    let(:future) { FutureString.new "It's looking bright!" }
+    subject{
+      future.filter :read_more =>{teaser: "carry on reading…"}, :add_title =>{title: "Feeling optimistic"}
+    }
+    it { should == "Feeling optimistic\n\nIt's looking bright! carry on reading…" }
+  end
+
+	describe "Block option arguments" do
+    let(:optional){ Optional.new "Does this block have an options argument?" }
+	  context "Given a block" do
+	    context "with an options argument *and* that uses the options" do
+        context "with method options" do
+          subject { optional.filter :something_with_options, :something_with_options => {extra: " Yes, I told you so. " } }
+          it { should == "Does this block have an options argument? Yes, I told you so. This should be ok." }
+        end
+        context "without method options" do
+          subject { optional.filter :something_with_options }
+          it { should == "Does this block have an options argument? This should be ok." }
+        end
+      end
+      context "without an options argument *and* a block that uses the options" do
+        context "with method options" do
+          it "should raise an error" do
+            expect{
+              optional.filter :something_without_options, :something_without_options => {extra: " Yes, I told you so. " }
+            }.to raise_error(NameError)
+          end
+        end
+        context "without method options" do
+          it "should raise an error" do
+            expect{
+              optional.filter :something_without_options
+            }.to raise_error(NameError)
+          end
+        end
+      end
+    end
+	  
+	end
 end
 
 end # inconvenient

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: texttube
 version: !ruby/object:Gem::Version
-  version: 6.1.0
+  version: 7.0.1
 platform: ruby
 authors:
 - Iain Barnett
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-12 00:00:00.000000000 Z
+date: 2015-06-14 00:00:00.000000000 Z
 dependencies: []
 description: Create chainable filters with ease.
 email: iainspeed @nospam@ gmail.com
@@ -22,6 +22,7 @@ files:
 - Gemfile
 - README.md
 - Rakefile
+- lib/texttube.rb
 - lib/texttube/base.rb
 - lib/texttube/filterable.rb
 - lib/texttube/version.rb