stupid_formatter 0.1.1 → 0.2.0

data/README.rdoc

@@ -1,23 +1,115 @@
 = StupidFormatter
 
-This is a super-stupid gem for formatting text in a chain. You can change the chain by doing this:
+StupidFormatter let's you pipe text through processors in a chain by abstracting the actual implementation
+details of each processor into a unified API. By default, it can do ERb, Markdown (via RDiscount) and
+syntax-highlight with CodeRay.
+
+Say you want to format some markdown-formatted text with RDiscount and also include some ERb processing
+with CodeRay syntax highlighting, you could configure the chain somewhere at the beginning of your app like so:
 
   StupidFormatter.chain = [StupidFormatter::Erb, StupidFormatter::RDiscount]
+  
+Then, pass in your Markdown-marked-up, ERb-riddled string to <code>StupidFormatter.result</code> or
+just call <code>string.formatted</code> and you'll see results. 
+
+The ERb, RDiscount chain mentioned above is actually the default, so if you want to stick with that,
+just skip that chain config step (yes, it is a stupid example).
+
+Formatters are processed in the order they are given in the Array, so ERb comes first, then RDiscount
+in this example.
 
-Then, pass in your Markdown-markedup, erb-riddled string to StupidFormatter.result and you'll
-see results. A coderay helper is included for erb, see test/fixtures/erb_coderay_markdown_example.txt
+To install, do:
 
-This is so completely alpha, you have no idea!
+  sudo gem install stupid_formatter
+  
+This is so completely alpha, you have no idea! Don't expect beautiful code or RDoc.
 
+== Using the formatters directly
+
+Of course, you can access the formatters directly as well. To format a string with RDiscount, do:
+  
+  StupidFormatter::RDiscount.new("# some markdown").result
+  
 == Custom formatters
 
-You can define your own formatters and by conforming to the public api, which is:
+You can define your own formatters very easily by conforming to the public API, which is:
 
 * inherit from StupidFormatter::AbstractFormatter
 * make a result instance method that does not take any arguments
 * use the local attribute 'input' to do whatever you want with the text, and return it
 
+=== Example custom formatter
+
+In our example, let's create a formatter that will reverse the text.
+
+  class StupidFormatter::WrittenInReverse < StupidFormatter::AbstractFormatter
+    def result
+      input.reverse
+    end
+  end
+  
+After adding that to the chain with
+
+  StupidFormatter.chain << StupidFormatter::WrittenInReverse
+  
+Your text will be reversed when calling <code>"some string".formatted</code>
+
+== ERb Helpers
+
+=== Capturing blocks with ERb
+
+The ERb-formatter offers a capture-helper, which allows you to capture the content of a block into
+a variable like so:
+
+  <% @foo = capture do %>
+    Bar
+  <% end %>
+  Foo<%= @foo %>
+  
+The above example will render into "FooBar". This functionality is used in the Coderay helper, which
+is automatically included in the ERb formatter, see next section.
+
+=== Syntax highlighting with Coderay
+
+With the CoderayHelper that gets included into the ERb formatter automatically, you can get syntax-highlighting
+very easily:
+  
+  <% highlight do %>
+    puts 'Your Awesome Ruby(tm) here!'
+  <% end %>
+  
+The language defaults to :ruby, but you can pass in any CodeRay-language to the highlight method:
+
+  <% highlight :javascript do %>
+    var foo = 'bar';
+  <% end %>
+  
+The highlighting is configured to use CSS instead of in-place colors, so you might want to add a 
+decent (http://railscasts.com/stylesheets/coderay.css) coderay css file into your HTML.
+
+Thanks Ryan for making that great CodeRay CSS and giving it away (http://railscasts.com/episodes/46-catch-all-route)!
+  
+=== Making your own helpers
+
+Let's make a helper that reverses the text you gave in the block, like so:
+
+  <% written_in_reverse do %>
+    anna
+  <% end %>
+  
+Just create a module that uses the capture helper and appends the result to the @output_buffer and include it
+in the ERb helper, like so:
+
+  module WrittenInReverse
+    def written_in_reverse
+      text = capture { yield }
+      @output_buffer << text.reverse
+    end
+  end
+  StupidFormatter::ERb.send :include, WrittenInReverse
 
+This will print 'anna' in your ERb. Easy, right?
+  
 == Note on Patches/Pull Requests
  
 * Fork the project.

data/Rakefile

@@ -6,13 +6,13 @@ begin
   Jeweler::Tasks.new do |gem|
     gem.name = "stupid_formatter"
     gem.summary = %Q{A stupid formatter for piping text through markup processors}
-    gem.description = %Q{With stupid_formatter you can pipe your blog post through erb and markdown in a chain}
+    gem.description = %Q{A stupid formatter for piping text through markup processors with a unified API}
     gem.email = "christoph at olszowka dot de"
     gem.homepage = "http://github.com/colszowka/stupid_formatter"
     gem.authors = ["Christoph Olszowka"]
     gem.add_dependency "rdiscount", ">= 1.5.0"
     gem.add_dependency "coderay", ">= 0.9.0"
-    gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
+    gem.add_development_dependency "shoulda", ">= 0"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/lib/stupid_formatter.rb

@@ -2,19 +2,36 @@ require 'rdiscount'
 require 'erb'
 require 'coderay'
 
+class String
+  #
+  # Pipes this string through the StupidFormatter and it's configured chain.
+  # The same as StupidFormatter.result(some_string)
+  #
+  def formatted
+    StupidFormatter.result(self)
+  end
+end
+
 module StupidFormatter
-  
-  # Make the formatter chain configurable.
   class << self
+    #
+    # Returns the current processing chain. Defaults to [StupidFormatter::Erb, StupidFormatter::RDiscount]
+    #
     def chain
-      @chain ||= [StupidFormatter::RDiscount]
+      @chain ||= [StupidFormatter::Erb, StupidFormatter::RDiscount]
     end
     
+    #
+    # Make the formatter chain configurable. Pass in an Array of Formatters in the order
+    # you want them processed in.
+    #
     def chain=(chain)
       @chain = chain
     end
     
+    #
     # Will put the input string through all formatters in the chain
+    #
     def result(input)
       output = input.clone
       chain.each do |formatter|
@@ -24,6 +41,9 @@ module StupidFormatter
     end
   end
   
+  #
+  # Base class for formatters, providing the basic API.
+  #
   class AbstractFormatter
     attr_reader :input
     

data/stupid_formatter.gemspec

@@ -5,12 +5,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{stupid_formatter}
-  s.version = "0.1.1"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Christoph Olszowka"]
-  s.date = %q{2010-02-11}
-  s.description = %q{With stupid_formatter you can pipe your blog post through erb and markdown in a chain}
+  s.date = %q{2010-02-13}
+  s.description = %q{A stupid formatter for piping text through markup processors with a unified API}
   s.email = %q{christoph at olszowka dot de}
   s.extra_rdoc_files = [
     "LICENSE",
@@ -51,16 +51,16 @@ Gem::Specification.new do |s|
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<rdiscount>, [">= 1.5.0"])
       s.add_runtime_dependency(%q<coderay>, [">= 0.9.0"])
-      s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+      s.add_development_dependency(%q<shoulda>, [">= 0"])
     else
       s.add_dependency(%q<rdiscount>, [">= 1.5.0"])
       s.add_dependency(%q<coderay>, [">= 0.9.0"])
-      s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+      s.add_dependency(%q<shoulda>, [">= 0"])
     end
   else
     s.add_dependency(%q<rdiscount>, [">= 1.5.0"])
     s.add_dependency(%q<coderay>, [">= 0.9.0"])
-    s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    s.add_dependency(%q<shoulda>, [">= 0"])
   end
 end
 

data/test/test_stupid_formatter.rb

@@ -25,6 +25,16 @@ class TestStupidFormatter < Test::Unit::TestCase
         assert_equal fixtures(:erb_coderay_markdown_expectation), @result
       end
     end
+    
+    context "when I call formatted on a complex fixture string" do
+      setup do
+        @result = fixtures(:erb_coderay_markdown_example).formatted
+      end
+      
+      should "render as in the expectation fixture" do
+        assert_equal fixtures(:erb_coderay_markdown_expectation), @result
+      end
+    end
   end
   
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: stupid_formatter
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors: 
 - Christoph Olszowka
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-11 00:00:00 +01:00
+date: 2010-02-13 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -33,7 +33,7 @@ dependencies:
         version: 0.9.0
     version: 
 - !ruby/object:Gem::Dependency 
-  name: thoughtbot-shoulda
+  name: shoulda
   type: :development
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
@@ -42,7 +42,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
     version: 
-description: With stupid_formatter you can pipe your blog post through erb and markdown in a chain
+description: A stupid formatter for piping text through markup processors with a unified API
 email: christoph at olszowka dot de
 executables: []