Skip to content
Browse files

Updated documentation

  • Loading branch information...
1 parent 7a57acd commit ed6127971f611fadc0fe367fb5bf500895bef7e4 @colszowka committed Feb 13, 2010
Showing with 126 additions and 10 deletions.
  1. +91 −5 README.rdoc
  2. +2 −2 Rakefile
  3. +23 −3 lib/stupid_formatter.rb
  4. +10 −0 test/test_stupid_formatter.rb
View
96 README.rdoc
@@ -1,23 +1,109 @@
= 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.
+
+Say you want to format some markdown-formatted text with RDiscount and also include some ERb processing,
+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 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 %>
+
+=== 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.
View
4 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
View
26 lib/stupid_formatter.rb
@@ -2,19 +2,36 @@
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 @@ def result(input)
end
end
+ #
+ # Base class for formatters, providing the basic API.
+ #
class AbstractFormatter
attr_reader :input
View
10 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

0 comments on commit ed61279

Please sign in to comment.
Something went wrong with that request. Please try again.