transfigr 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Daniel Neighman
+
+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.textile

@@ -0,0 +1,102 @@
+h1. Transfigr
+
+A simple, pluggable plugin to transfigure an object into a format.  
+It can be used as a simple markup transfigurer, i.e. textile or markdown.
+It can also be used as a general purpose presenter if you define it as such. 
+
+h2. Example
+
+<pre><code>
+  Transfigr.format!(:textile, "h1. I am a textile string")
+  Transfigr.format!(:markdown, "I _am_ a markdown string")
+</code></pre>
+
+h3. Using options
+You can configure your formatters to take an options hash to customize
+the format based on options.
+
+<pre><code>
+  Transfigr.add(:xml) do
+    def format!(opts)
+      target.to_xml(opts)
+    end
+  end
+  
+  Transfigr.format!(:xml, @person_list, :fields => [:name, :age])
+</code></pre>
+
+This is especially useful when using it as a presenter in merb.
+
+h2. Using it as a Presenter
+
+<pre><code>
+  Transfigr.presenter(@article).to_xml # requires an :xml format be setup
+</code></pre>
+
+This is especially useful when using something like Merb's display method.  
+
+All _active_ formats have a method added to the presenter @to_<format>@
+  
+h3. Options in the presenter.
+
+Sometimes you need to customize the format of an object based on 
+the current environment or state of the application.
+
+Transfigr presenters allow options to be passed into the format! method.
+
+As an example, in merb you may use:
+
+<pre><code>
+  display Transfigr.presenter(@user, :fields => [:name, :age])
+</code></pre>
+
+When you define the formats, you can make use of any options passed it.
+
+h2. Pluggable Back End
+
+The architecture is pluggable so that you can add your own custom formatters.
+
+By default there are currently:
+
+* :textile - Via RedCloth (you need to install redcloth)
+* :markdown - Via RDiscount or as a fallback Bluecloth.  RDiscount is much faster http://tomayko.com/writings/ruby-markdown-libraries-real-cheap-for-you-two-for-price-of-one
+
+h3. Make your own store
+
+To define your own format is really simple.  Lets look at the textile one.
+
+<pre><code>
+  Transfigr.add(:textile)
+      after_activation do
+        require 'redcloth'
+      end
+
+      def format!(options = {})
+        RedCloth.new(target).to_html
+      end
+    end
+  end
+</code></pre>
+
+You can define any helpers inline.  You can also @edit@ existing formats.  
+Replace formats by simply adding a new one with the same name.
+
+The @after_activation@ block in the add methodis called when the formatter is activated.  
+It is a good place to put any dependencies the formatter may require.
+
+The @format!(options = {})@ method is the work horse.  This is the method that is called to actually transform
+a string to the new format.  
+
+h3. Activation
+
+You must activate a format in order to use it.  
+It is not secure to simply automatically load them.
+
+You can activate existing formats like this:
+<pre><code>
+  Transfigr.activate!(:textile, :markdown, :xml, :html, :pdf, :foo)
+</code></pre>
+
+You must have these formats defined.  Check like @Transfigr.defined?(:foo)@
+
+That's basically it.

data/Rakefile

@@ -0,0 +1,44 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require "spec/rake/spectask"
+
+GEM_NAME = "transfigr"
+GEM_VERSION = "0.1.0"
+AUTHOR = "Daniel Neighman"
+EMAIL = "has.sox@gmail.com"
+HOMEPAGE = "http://rubunity.com"
+SUMMARY = "A Pluggable Markup Formatter"
+
+spec = Gem::Specification.new do |s|
+  s.rubyforge_project = 'transfigr'
+  s.name = GEM_NAME
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README.textile", "LICENSE", 'TODO']
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  s.require_path = 'lib'
+  s.files = %w(LICENSE README.textile Rakefile TODO) + Dir.glob("{lib,spec}/**/*")
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "Install the gem"
+task :install => [:clobber_package, :package] do
+  system "gem install pkg/transfigr-#{GEM_VERSION}.gem"
+end
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new("spec") do |t|
+  t.spec_opts = ["--format", "specdoc", "--colour"]
+  t.spec_files = Dir["spec/**/*_spec.rb"].sort
+  t.rcov = false
+  t.rcov_opts << '--sort' << 'coverage' << '--sort-reverse'
+  t.rcov_opts << '--only-uncovered'
+end

data/TODO

@@ -0,0 +1,5 @@
+TODO:
+Fix LICENSE with your name
+Fix Rakefile with your name and contact info
+Add your code to lib/transfigr.rb
+Add your Merb rake tasks to lib/transfigr/merbtasks.rb

data/lib/transfigr.rb

@@ -0,0 +1,127 @@
+require 'rubygems'
+
+module Transfigr
+  class MissingFormatMethod < Exception; end
+  class FormatterNotFound < Exception; end
+  
+  class << self
+    # Use the format method to format an object via a given formatter
+    # Normally this would be a string, but it could be anything.
+    # 
+    # Example: 
+    #   
+    #   Transfigr.format!(:textile, "h1. I'm a textile string")
+    #
+    # :api: public
+    def format!(format, object, opts = {})
+      raise "#{format.inspect} is not an active format" unless active?(format)
+      self[format].new(object).format!(opts)
+    end
+  
+    # Activate formatters that you want to actually use.  This 
+    # allows formatters to be loaded, but not actually activated,
+    # leaving their dependencies behind.  Activation can be done implicitly
+    # by just using a registered format.
+    #
+    # :api: public
+    def activate!(*args)
+      args.each do |f|
+        fmtr = formatters[f]
+        raise "No Formatter found for format #{f.inspect}" unless fmtr
+        _active_formats[f.to_s] = f
+        Presenter.add_format!(f)
+        fmtr.after_activation.call if fmtr.after_activation
+        true
+      end
+    end
+    
+    # Deactivate and already active format
+    #
+    # :api: public
+    def deactivate!(*args)
+      args.each do |f|
+        _active_formats.delete(f.to_s)
+        Presenter.remove_format!(f)
+      end
+    end
+    
+    # Allows you to add a formatter.  A formatter should 
+    # At minimum define a format!(opts={}) method.  
+    # I there is no format! method Transfigr::MissingFormatMethod will be raised
+    # 
+    # Example
+    #
+    #   Transfigr.add(:foo) do
+    #     def format!(opts = {})
+    #       "<foo>#{target}</foo>"
+    #     end
+    #   end
+    #
+    # :api: public
+    def add(name, &block)
+      formatter = Class.new(Formatter, &block)
+      raise MissingFormatMethod unless formatter.instance_methods.include?("format!")
+      self.formatters[name] = formatter
+    end
+    
+    # Provides acces to edit the formatter.  It's the same as getting another crack
+    # at the add block
+    # 
+    # Example
+    # 
+    #   Transfigr.edit(:foo){ def my_helper; "bar"; end }
+    #
+    # :api: public
+    def edit(name, &block)
+      fmtr = formatters[name]
+      raise FormatterNotFound unless fmtr
+      fmtr.class_eval(&block)
+    end
+     
+    # Provides a list of currently active formats
+    # :api: public
+    def active_formats
+      _active_formats.keys.sort
+    end
+    
+    # Check to see if a format has been activated
+    # :api: public
+    def active?(format)
+      !!_active_formats[format.to_s]
+    end
+    
+    # Checks to see if a formatter has been defined
+    # :api: public
+    def defined?(format)
+      formatters.keys.include?(format)
+    end
+    
+    protected
+    # provides a list of declared formatters
+    # :api: private
+    def formatters
+      @formatters ||= {}
+    end
+
+    private
+    # Provides access to the formatter
+    # :api: private
+    def [](formatter)
+      formatters[_active_formats[formatter.to_s]]
+    end
+    
+    # A hash of active formats with the format_as as the key, and the class as the value
+    # :api: private
+    def _active_formats
+      @_active_formats ||= {}
+    end
+    
+
+  end # self
+end # Transfigr
+
+$:.unshift File.dirname(__FILE__)
+require 'transfigr/presenter'
+require 'transfigr/abstract_formatter'
+require 'transfigr/formatters/markdown'
+require 'transfigr/formatters/textile'

data/lib/transfigr/abstract_formatter.rb

@@ -0,0 +1,27 @@
+module Transfigr
+  # Transfigr::Formatter is the base class to inherit from when developing your own formatters
+  class Formatter
+    attr_accessor :target
+    
+    def initialize(target)
+      @target = target
+    end
+    
+    # The after_activation block allows you to call code after the formatter has been activated.
+    # This includes requireing any dependencies
+    #
+    # Example 
+    # 
+    #   class MyFoo < Transfigr::Formatter
+    #     # snip
+    #     after_activation{ require "foo" }
+    #     #snip
+    #   end
+    #
+    # :api: plugin
+    def self.after_activation(&block)
+      @after_activation = block if block_given?
+      @after_activation
+    end
+  end
+end

data/lib/transfigr/formatters/markdown.rb

@@ -0,0 +1,14 @@
+Transfigr.add(:markdown) do
+  after_activation do
+    begin
+      require 'rdiscount'
+      BlueCloth = RDiscount
+    rescue LoadError
+      require 'bluecloth'
+    end
+  end
+  
+  def format!(opts = {})
+    BlueCloth.new(target).to_html
+  end
+end

data/lib/transfigr/formatters/textile.rb

@@ -0,0 +1,9 @@
+Transfigr.add(:textile) do
+  after_activation do
+    require 'redcloth'
+  end
+    
+  def format!(opts = {})
+    RedCloth.new(target).to_html
+  end
+end

data/lib/transfigr/presenter.rb

@@ -0,0 +1,58 @@
+module Transfigr
+  
+  # Use this as a presenter object to access the object by a to_<format> method.
+  # This is useful when using something like Merb's display method.
+  # It stronly defines presentation logic elsewhere from the object
+  #
+  # Example
+  # 
+  #   display Transfigr.presenter(@article)
+  #
+  #   Tranfigr.presenter(@article).to_textile
+  #
+  # :api: public
+  def self.presenter(object, opts = {})
+    Presenter.new(object, opts)    
+  end
+  
+  # :api: private
+  class Presenter
+    attr_reader :target, :options
+    
+    def initialize(target, options = {})   
+      @target, @options = target, options
+    end
+    
+    # Need to undefine all the to_xxx methods
+    to_methods = self.instance_methods.grep(/^to_/)
+    to_methods.each do |meth|
+      undef_method meth.to_sym unless meth == "to_s" || meth == "to_string"
+    end
+    
+    # Adds a formatter to the presenter
+    # :api: private
+    def self.add_format!(format)
+      self.class_eval <<-RUBY
+        def to_#{format}
+          Transfigr.format!(:#{format}, target, options)
+        end
+      RUBY
+    end
+    
+    # Removes the formatter method from the presenter
+    # :api: private
+    def self.remove_format!(format)
+      undef_method :"to_#{format}"
+    end
+    
+    # :api: overwritable
+    def method_missing(name, *rest)
+      if name.to_s =~ /^to_/
+        return target.send(name) if target.respond_to?(name)
+        raise FormatterNotFound, "No active #{name.inspect} format was found" 
+      end
+      super
+    end
+    
+  end # Presenter
+end # Transfigr

data/spec/formatters/markdown_spec.rb

@@ -0,0 +1,10 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe "markdown formatting" do
+  before(:all) do
+    Transfigr.activate!(:markdown)
+  end
+  it "should render a textile string as html" do
+    Transfigr.format!(:markdown, "I'm biched _es_").should match(/^<p>I'm biched <em>es<\/em><\/p>/)
+  end
+end

data/spec/formatters/textile_spec.rb

@@ -0,0 +1,10 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe "textile formatting" do
+  before(:all) do
+    Transfigr.activate!(:textile)
+  end
+  it "should render a textile string as html" do
+    Transfigr.format!(:textile, "h1. Foo Dude").should == "<h1>Foo Dude</h1>"
+  end
+end

data/spec/presenter_spec.rb

@@ -0,0 +1,39 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "Transfigr.presenter(obj)" do
+  
+  before(:each) do
+    Transfigr.add(:active_presenter_format) do
+      def format!(o)
+        :presenter_format_formatted
+      end
+    end
+    Transfigr.activate!(:active_presenter_format)
+  end
+  
+  it "should setup a presenter" do
+    Transfigr.presenter(Object.new).should be_an_instance_of(Transfigr::Presenter)
+  end
+  
+  it "should allow me to call me to call a format via to_<format> on an activated format" do
+
+    Transfigr.presenter(Object.new).to_active_presenter_format.should == :presenter_format_formatted
+  end
+  
+  it "should raise a FormatterNotFound when calling to_<unknown_format>" do
+    Transfigr.should_not be_defined(:not_defined)
+    lambda do
+      Transfigr.presenter(Object.new).to_not_defined
+    end.should raise_error(Transfigr::FormatterNotFound)
+  end
+  
+  it "should fall back to the objects to_xxx method if there is no format one found" do
+    class PresenterFoo
+      def to_xxx
+        :fallback
+      end
+    end
+    Transfigr.presenter(PresenterFoo.new).to_xxx.should == :fallback
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+$:.push File.join(File.dirname(__FILE__), '..', 'lib')
+require 'transfigr'

data/spec/transfigr_spec.rb

@@ -0,0 +1,119 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "transfigr" do
+  before(:each){$captures = []}
+    
+  it "should allow a developer to activate a formatter" do
+    Transfigr.add(:foo1){ def format!(opts={}); end }
+    Transfigr.activate!(:foo1)
+    Transfigr.active?(:foo1).should be_true
+  end
+  
+  it "should allow activation of multiple formatters" do
+    Transfigr.add(:foo2){ def format!(opts={}); end }
+    Transfigr.add(:foo3){ def format!(opts={}); end }
+    Transfigr.activate!(:foo2, :foo3)
+    [:foo2, :foo3].each do |foo|
+      Transfigr.active?(foo).should be_true
+    end
+  end
+  
+  it "should raise and exception if there is no format! method defined" do
+    lambda do
+      Transfigr.add(:no_format_foo){ }
+    end.should raise_error(Transfigr::MissingFormatMethod)
+  end
+  
+  it "should not define a format! method on the base class" do
+    Transfigr::Formatter.instance_methods.should_not include("format!")
+  end
+  
+  it "should not be activated for a formatter that has not been activate" do
+    Transfigr.add(:foo4){ def format!(opts={}); end }
+    Transfigr.active?(:foo4).should be_false
+  end
+  
+  it "should allow the formatter to run after_activation code" do
+    Transfigr.add(:foo5) do
+      after_activation { $captures << :foo5 }
+      def format!(opts={}); end
+    end
+    Transfigr.activate!(:foo5)
+    $captures.should == [:foo5]
+  end
+  
+  it "should not run the after_Activation code if the formatter has not been activated" do
+    Transfigr.add(:foo6) do
+      after_activation{ $captuers << :foo6 }
+      def format!(opts={}); end
+    end
+    $captures.should_not include(:foo6)
+  end
+  
+  it "should format a string with the provided fromatter" do
+    Transfigr.add(:foo8) do
+      def format!(opts = {})
+        ":foo8 - #{target}"
+      end
+    end
+    Transfigr.activate!(:foo8)
+    Transfigr.format!(:foo8, "foobar").should == ":foo8 - foobar"
+    Transfigr.format!("foo8", "bazbar").should == ":foo8 - bazbar"
+  end
+  
+  it "should allow for options to be passed to the format" do
+    Transfigr.add(:foo9) do
+      def format!(opts = {})
+        ":foo9 - #{target} - #{opts.inspect}"
+      end
+    end
+    Transfigr.activate!(:foo9)
+    Transfigr.format!(:foo9, "string", :foo => :bar).should == ":foo9 - string - {:foo=>:bar}"
+  end
+  
+  it "should allow me to edit a formatter" do
+    Transfigr.add(:foo10){ def format!(o={}); $captures << :original; end }
+    Transfigr.activate!(:foo10)
+    Transfigr.format!(:foo10, :foo)
+    Transfigr.edit(:foo10){ def format!(o={}); $captures << :modified; end}
+    Transfigr.format!(:foo10, :foo)
+    $captures.should == [:original, :modified]
+  end
+  
+  it "should raise an exception if a formatter is edited that does not exist" do
+    lambda do
+      Transfigr.edit(:will_never_exist){ def format!(o); "foo"; end }
+    end.should raise_error(Transfigr::FormatterNotFound)
+  end
+  
+  it "should allow me to replace a formatter" do
+    Transfigr.add(:foo11) do
+      def helper; :helper; end
+      def format!(o); $captures << :noooo; end 
+    end
+    Transfigr.activate!(:foo11)
+    Transfigr.add(:foo11) do
+      def format!(o)
+        $captures << :yeeees
+        $captures << self.respond_to?(:helper)
+      end
+    end
+    
+    Transfigr.format!(:foo11, "")
+    $captures.should == [:yeeees, false]
+  end
+  
+  it "should allow you to deactivate a format" do
+    Transfigr.add(:foo12){ def format!(o); :foo12; end }
+    Transfigr.activate!(:foo12)
+    Transfigr.should be_active(:foo12)
+    Transfigr.deactivate!(:foo12)
+    Transfigr.should_not be_active(:foo12)
+  end
+  
+  it "should tell you if a formatter has been defined" do
+    Transfigr.should_not be_defined(:to_be_defined)
+    Transfigr.add(:to_be_defined){ def format!(o); :foo; end }
+    Transfigr.should be_defined(:to_be_defined)
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: transfigr
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Daniel Neighman
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-10 00:00:00 +11:00
+default_executable: 
+dependencies: []
+
+description: A Pluggable Markup Formatter
+email: has.sox@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+- LICENSE
+- TODO
+files: 
+- LICENSE
+- README.textile
+- Rakefile
+- TODO
+- lib/transfigr
+- lib/transfigr/abstract_formatter.rb
+- lib/transfigr/formatters
+- lib/transfigr/formatters/markdown.rb
+- lib/transfigr/formatters/textile.rb
+- lib/transfigr/presenter.rb
+- lib/transfigr.rb
+- spec/formatters
+- spec/formatters/markdown_spec.rb
+- spec/formatters/textile_spec.rb
+- spec/presenter_spec.rb
+- spec/spec_helper.rb
+- spec/transfigr_spec.rb
+has_rdoc: true
+homepage: http://rubunity.com
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: transfigr
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: A Pluggable Markup Formatter
+test_files: []
+