acts_as_markup_extended 1.0.1

data/CHANGELOG

@@ -0,0 +1,4 @@
+== 1.0.0 / 2011-06-29
+
+* Initial Release
+  * Forked from acts_as_markup

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2008 Brian Landau of Viget Labs
+
+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.rdoc

@@ -0,0 +1,198 @@
+= Acts as Markup Extended 
+
+* by Mitch Marx <mitch.marx@mdpaladin.com> 
+* based on acts_as_markup by Brian Landau of Viget Labs <brian.landau@viget.com>  
+
+GitHub Project: http://github.com/mitchmarx/acts_as_markup_extended
+
+RDoc: 
+* http://gitrdoc.com/vigetlabs/acts_as_markup/tree/master
+* http://vigetlabs.github.com/acts_as_markup
+
+
+== NOTE:
+
+This is an enhanced version of Brian Landau's acts_as_markup.  It includes the
+":extensions =>" option which allows you to specify methods that extend markup 
+languages (see the samples in lib/markup_methods).
+
+== DESCRIPTION:
+
+Allows you to specify columns of an ActiveRecord model that contain Markdown, 
+Textile, Wiki text and RDoc. You may then use +to_s+ to get the original markup 
+text or +to_html+ to get the formated HTML.
+
+Additionally you can have a model that contains a column that has a column with 
+markup text, and another that defines what language to process it as. If the field 
+is listed as "markdown" "textile", "wikitext" or "rdoc" (case insensitive) it will 
+treat it as such, any other value for markup language will have the value pass 
+through as a normal string.
+
+You can use 4 different types of Markdown processing backends: 
+BlueCloth, RDiscount, Ruby PEG or Maruku. You specify which one you want to use by setting
+a config value in your environment.rb file:
+
+    ActsAsMarkup.markdown_library = :bluecloth
+
+By default RDiscount will be used.
+
+You can specify additional options to pass to the markup library by using
+<tt>:markdown_options</tt>, <tt>:textile_options</tt> or <tt>:wikitext_options</tt>.
+RDoc does not support any useful options. The options should be given as an
+array of arguments. You can specify options for multiple languages when
+allowing more than one. See each library's documentation for more details on
+what options are available.
+
+== MARKUP EXTENSION METHODS:
+
+For any column you can specify markup extension methods by including 
+<tt>:extensions =></tt> in any of the forms of acts_as_markup illustrated below.
+
+Sample extensions methods are in: <tt>lib/markup_extensions</tt>.
+You can include methods that reside anywhere as long as they are 
+in module MarkupExtensionMethods.
+
+You can invoke all the methods in module MarkupExtensionMethods with <tt>:extensions => :all</tt>.
+
+== EXAMPLES:
+
+==== Using +acts_as_markdown+:
+
+    class Post < ActiveRecord
+      acts_as_markdown :body
+    end
+    
+    @post = Post.find(:first)
+    @post.body.to_s     #=> "## Markdown Headline"
+    @post.body.to_html  #=> "<h2> Markdown Headline</h2>"
+    
+
+==== Using +acts_as_textile+:
+
+    class Post < ActiveRecord
+      acts_as_textile :body
+    end
+
+    @post = Post.find(:first)
+    @post.body.to_s     #=> "h2. Textile Headline"
+    @post.body.to_html  #=> "<h2>Textile Headline</h2>"
+    
+
+==== Using +acts_as_wikitext+:
+
+    class Post < ActiveRecord
+      acts_as_wikitext :body
+    end
+
+    @post = Post.find(:first)
+    @post.body.to_s     #=> "== Wikitext Headline =="
+    @post.body.to_html  #=> "<h2>Wikitext Headline</h2>"
+    
+
+==== Using +acts_as_rdoc+:
+
+    class Post < ActiveRecord
+      acts_as_rdoc :body
+    end
+
+    @post = Post.find(:first)
+    @post.body.to_s     #=> "== RDoc Headline"
+    @post.body.to_html  #=> "<h2>RDoc Headline</h2>"
+    
+
+==== Using +acts_as_markup+:
+
+    class Post < ActiveRecord
+      acts_as_markup :language => :markdown, :columns => [:body]
+    end
+
+    @post = Post.find(:first)
+    @post.body.to_s     #=> "## Markdown Headline"
+    @post.body.to_html  #=> "<h2> Markdown Headline</h2>"
+    
+    
+==== Using +acts_as_markup+ with <tt>:variable</tt> language:
+
+    class Post < ActiveRecord
+      acts_as_markup :language => :variable, :columns => [:body]
+    end
+    
+    @post = Post.find(:first)
+    @post.markup_language      # => "markdown"
+    @post.body.to_s            # => "## Markdown Headline"
+    @post.body.to_html         # => "<h2> Markdown Headline</h2>"
+    
+
+==== Using options
+
+    class Post < ActiveRecord
+      acts_as_markdown :body, :markdown_options => [ :filter_html ]
+    end
+    
+    class Post < ActiveRecord
+      acts_as_textile :body, :textile_options => [ [ :filter_html ] ]
+    end
+    
+    class Post < ActiveRecord
+      acts_as_wikitext :body, :wikitext_options => [ { :space_to_underscore => true } ]
+    end
+    
+==== With markup extension methods
+
+    class Post < ActiveRecord
+      acts_as_markup :language => :markdown, :columns => [:body],
+         :extensions => [:method1, method2, ...].
+    end
+
+    class Post < ActiveRecord
+      acts_as_markdown :body, :extensions => :all
+    end        
+  
+
+== REQUIREMENTS:
+
+You will need the RedCloth[http://whytheluckystiff.net/ruby/redcloth/] library 
+for processing the Textile text, and the Wikitext[http://wikitext.rubyforge.org/] 
+library for processing wikitext.
+
+You will also need to install some type of Markdown processor.
+The three options currently supported are:
+
+* BlueCloth
+* RDiscount[http://github.com/rtomayko/rdiscount]
+* {Ruby PEG}[http://github.com/rtomayko/rpeg-markdown/tree/master]
+* Maruku[http://maruku.rubyforge.org/]
+
+== INSTALL:
+
+<tt>sudo gem install acts_as_markup</tt>
+ 
+Add "+acts_as_markup+" to your environment.rb:
+
+    config.gem "acts_as_markup"
+
+== CONTRIBUTING:
+
+Make a fork on GitHub, make your changes and do a pull request. Good places to start are adding new Markdown libraries or new markup languages, here's instructions for both:
+
+=== Instructions for how to add a new Markdown Library:
+
+1. Add another item to the <tt>ActsAsMarkup::MARKDOWN_LIBS</tt> hash in the form of:
+       :bluecloth => {:class_name => "BlueCloth",
+                      :lib_name   => "bluecloth"}
+   <tt>:lib_name</tt> should be the name needed to require the library, while <tt>:class_name</tt> should be the class that we are making an instance of.
+2. If you need to modify the object in anyway (e.g. to add a <tt>to_s</tt> or <tt>to_html</tt> method), add a file to the "lib/acts_as_markup/exts/" directory.
+3. Add appropriate tests (see current tests).
+
+=== Instructions for how to add a new Markup Language:
+
+1. Add a "<tt>when</tt>" statement to the "<tt>case</tt>" statement in <tt>acts_as_markup</tt>. The "<tt>when</tt>" statement should match with a symbol that represents the language name in some way (e.g. "<tt>:markdown</tt>").
+2. In the "<tt>when</tt>" block you need to set the "<tt>klass</tt>" local variable and require the library and the extension file if you need one (use the special <tt>require_extensions</tt> method to require extensions).
+3. Add the same lines you added to the previous "<tt>when</tt>" statement to the "<tt>:variable</tt>" "<tt>when</tt>" statement. But replace "<tt>klass</tt>" with "<tt>language_klass</tt>" (e.g. "<tt>markdown_klass</tt>").
+4. Add a relevant "<tt>when</tt>" statement to the <tt>class_eval</tt> block for the "<tt>:variable</tt>" language option. This should look something like:
+       when /markdown/i
+         markup_klasses[:markdown].new self[col].to_s
+5. Add a convenience method (e.g. "<tt>acts_as_markdown</tt>")
+6. Add an extension file to the "lib/acts_as_markup/exts/" directory if you need to modify the object in anyway.
+7. Add appropriate tests (see current tests).
+

data/Rakefile

@@ -0,0 +1,35 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+$:.unshift(File.expand_path('lib'))
+
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "acts_as_markup_extended"
+    gem.summary = %Q{Represent ActiveRecord Markdown, Textile, Wiki text, RDoc columns as Markdown, Textile Wikitext, RDoc objects using various external libraries to convert to HTML. Includes markup extension methods.}
+    gem.description = %Q{Represent ActiveRecord Markdown, Textile, Wiki text, RDoc columns as Markdown, Textile Wikitext, RDoc objects using various external libraries to convert to HTML. Includes markup extension methods.}
+    gem.email = "mitch.marx@mdpaladin.com"
+    gem.homepage = "https://github.com/mitchmarx/acts_as_markup_extended/"
+    gem.authors = ["Mitch Marx"]
+    gem.version = '1.0.1'
+    gem.add_dependency('activesupport', '>= 2.3.2')
+    gem.add_dependency('activerecord', '>= 2.3.2')
+    gem.add_dependency('rdiscount', '~> 1.3')
+    gem.add_dependency('wikitext', '~> 2.0')
+    gem.add_dependency('RedCloth', '~> 4.2')
+    gem.files =  FileList["[A-Z]*", "{lib,test}/**/*"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'tasks/test'
+require 'tasks/rdoc'
+
+task :test => :check_dependencies
+task :default => :test

data/lib/acts/as_markup.rb

@@ -0,0 +1,251 @@
+require 'active_record'
+
+module ActiveRecord # :nodoc:
+  module Acts # :nodoc:
+    module AsMarkup
+      def self.included(base) # :nodoc:
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        
+        # This allows you to specify columns you want to define as containing 
+        # Markdown, Textile, Wikitext or RDoc content.
+        # Then you can simply call <tt>.to_html</tt> method on the attribute.
+        # 
+        # You can also specify the language as <tt>:variable</tt>. The language used
+        # to process the column will be based on another column. By default a column
+        # named "<tt>markup_language</tt>" is used, but this can be changed by providing 
+        # a <tt>:language_column</tt> option. When a value is accessed it will create 
+        # the correct object (Markdown, Textile, Wikitext or RDoc) based on the value 
+        # of the language column. If any value besides markdown, textile, wikitext, or 
+        # RDoc is supplied for the markup language the text will pass through as a string.
+        #
+        # You can specify additional options to pass to the markup library by using
+        # <tt>:markdown_options</tt>, <tt>:textile_options</tt> or <tt>:wikitext_options</tt>.
+        # RDoc does not support any useful options. The options should be given as an array
+        # of arguments. You can specify options for more than one language when using
+        # <tt>:variable</tt>. See each library's documentation for more details on what
+        # options are available.
+        # 
+        # For any column you can specify markup extensions by including 
+        # <tt>:extensions =></tt> in any of the forms of acts_as_markup illustrated below.
+        #
+        # Sample extensions methods are in: lib/markup_extensions.
+        # You can include methods that reside anywhere as long as they are 
+        # in module MarkupExtensionMethods. (see the samples in lib/markup_methods).
+        #
+        # You can invoke all the methods in module MarkupExtensionMethods with :extensions => :all.
+        #
+        # ==== Examples
+        # 
+        # ===== Using Markdown language
+        # 
+        #     class Post < ActiveRecord
+        #       acts_as_markup :language => :markdown, :columns => [:body]
+        #     end
+        #     
+        #     @post = Post.find(:first)
+        #     @post.body.to_s            # => "## Markdown Headline"
+        #     @post.body.to_html         # => "<h2> Markdown Headline</h2>"
+        #     
+        # 
+        # ===== Using variable language
+        # 
+        #     class Post < ActiveRecord
+        #       acts_as_markup :language => :variable, :columns => [:body], :language_column => 'language_name'
+        #     end
+        #     
+        #     @post = Post.find(:first)
+        #     @post.language_name        # => "markdown"
+        #     @post.body.to_s            # => "## Markdown Headline"
+        #     @post.body.to_html         # => "<h2> Markdown Headline</h2>"
+        #     
+        # 
+        # ===== Using options
+        # 
+        #     class Post < ActiveRecord
+        #       acts_as_markup :language => :markdown, :columns => [:body], :markdown_options => [ :filter_html ]
+        #     end
+        #     
+        #     class Post < ActiveRecord
+        #       acts_as_markup :language => :textile, :columns => [:body], :textile_options => [ [ :filter_html ] ]
+        #     end
+        #     
+        #     class Post < ActiveRecord
+        #       acts_as_markup :language => :wikitext, :columns => [:body], :wikitext_options => [ { :space_to_underscore => true } ]
+        #     end
+        #     
+        # ===== With markup extension methods
+        #
+        #     class Post < ActiveRecord
+        #       acts_as_markup :language => :markdown, :columns => [:body],
+        #             :extensions => [:method1, method2, ...].
+        #     end
+        #
+        #     class Post < ActiveRecord
+        #       acts_as_markdown :body, :extensions => :all
+        #     end        
+          
+        def acts_as_markup(options)
+          case options[:language].to_sym
+          when :markdown, :textile, :wikitext, :rdoc
+            klass = require_library_and_get_class(options[:language].to_sym)
+          when :variable
+            markup_klasses = {}
+            [:textile, :wikitext, :rdoc, :markdown].each do |language|
+              markup_klasses[language] = require_library_and_get_class(language)
+            end
+            options[:language_column] ||= :markup_language
+          else
+            raise ActsAsMarkup::UnsupportedMarkupLanguage, "#{options[:langauge]} is not a currently supported markup language."
+          end
+          
+          # create the proc object in current scope
+          set_markup_object = markup_object_proc
+          unless options[:language].to_sym == :variable
+            markup_options = options["#{options[:language]}_options".to_sym] || []
+            options[:columns].each do |col|
+              define_method col do
+                if instance_variable_defined?("@#{col}")
+                  unless send("#{col}_changed?")
+                    return instance_variable_get("@#{col}")
+                  end
+                end
+                # call the proc to make all 'to_html' methods return an MString instead of a String
+                set_markup_object.call("@#{col}",options,          
+                  klass.new(self[col].to_s, *markup_options))
+              end
+            end
+          else
+            options[:columns].each do |col|
+              define_method col do
+                if instance_variable_defined?("@#{col}")
+                  unless send("#{col}_changed?") || send("#{options[:language_column]}_changed?")
+                    return instance_variable_get("@#{col}")
+                  end
+                end 
+                # call the proc to make all 'to_html' methods return an MString instead of a String
+                set_markup_object.call("@#{col}",options, case send(options[:language_column])
+                when /markdown/i
+                  markup_klasses[:markdown].new self[col].to_s, *(options[:markdown_options] || [])
+                when /textile/i
+                  markup_klasses[:textile].new self[col].to_s, *(options[:textile_options] || [])
+                when /wikitext/i
+                  markup_klasses[:wikitext].new self[col].to_s, *(options[:wikitext_options] || [])
+                when /rdoc/i
+                  markup_klasses[:rdoc].new self[col].to_s
+                else
+                  self[col]
+                end)
+              end
+            end
+          end
+        end
+        
+        # This is a convenience method for 
+        # `<tt>acts_as_markup :language => :markdown, :columns => [:body]</tt>`
+        # Additional options can be given at the end, if necessary.
+        # 
+        def acts_as_markdown(*columns)
+          options = columns.extract_options!
+          acts_as_markup options.merge(:language => :markdown, :columns => columns)
+        end
+        
+        # This is a convenience method for 
+        # `<tt>acts_as_markup :language => :textile, :columns => [:body]</tt>`
+        # Additional options can be given at the end, if necessary.
+        #
+        def acts_as_textile(*columns)
+          options = columns.extract_options!
+          acts_as_markup options.merge(:language => :textile, :columns => columns)
+        end
+        
+        # This is a convenience method for 
+        # `<tt>acts_as_markup :language => :wikitext, :columns => [:body]</tt>`
+        # Additional options can be given at the end, if necessary.
+        #
+        def acts_as_wikitext(*columns)
+          options = columns.extract_options!
+          acts_as_markup options.merge(:language => :wikitext, :columns => columns)
+        end
+        
+        # This is a convenience method for 
+        # `<tt>acts_as_markup :language => :rdoc, :columns => [:body]</tt>`
+        # Additional options can be given at the end, if necessary.
+        #
+        def acts_as_rdoc(*columns)
+          options = columns.extract_options!
+          acts_as_markup options.merge(:language => :rdoc, :columns => columns)
+        end
+        
+        
+        private
+          def get_markdown_class
+            if ActsAsMarkup::MARKDOWN_LIBS.keys.include? ActsAsMarkup.markdown_library
+              markdown_library_names = ActsAsMarkup::MARKDOWN_LIBS[ActsAsMarkup.markdown_library]
+              require markdown_library_names[:lib_name]
+              require_extensions(markdown_library_names[:lib_name])
+              return markdown_library_names[:class_name].constantize
+            else
+              raise ActsAsMarkup::UnsportedMarkdownLibrary, "#{ActsAsMarkup.markdown_library} is not currently supported."
+            end
+          end
+          
+          def require_extensions(library)# :nodoc:
+            if ActsAsMarkup::LIBRARY_EXTENSIONS.include? library.to_s
+              require "#{ActsAsMarkup::LIBPATH}/acts_as_markup/exts/#{library}"
+            end
+          end
+          
+          def require_library_and_get_class(language)
+            case language
+            when :markdown
+              return get_markdown_class
+            when :textile
+              require 'redcloth'
+              return RedCloth
+            when :wikitext
+              require 'wikitext'
+              require_extensions 'wikitext'
+              return WikitextString
+            when :rdoc
+              require 'rdoc/markup/simple_markup'
+              require 'rdoc/markup/simple_markup/to_html'
+              require_extensions 'rdoc'
+              return RDocText
+            else
+              return String
+            end
+          end
+          
+          # This method returns a Proc object that is called
+          # when acts_as_markup intercepts ActiveRecord
+          # while it is creating a column instance.
+          # The Proc creates an Eigenclass for the markup
+          # object. The eigenclass overrides the <tt>to_html</tt> method
+          # in the markup object (Rdiscount, Textile, etc.) so
+          # that it returns an instance of MString instead of String
+          # MString includes all the markup extension methods and invokes
+          # the ones named in <tt>:extensions =></tt>.
+          #
+          def markup_object_proc
+            Proc.new {|col, options, markup_object |  
+              if options[:extensions]
+                singleton = markup_object.singleton_class
+                singleton.send(:alias_method,:old_to_html, :to_html)
+                singleton.send(:define_method, :to_html)  {
+                 MarkupExtensions::MString.new(old_to_html).
+                  run_methods(options[:extensions])
+                }
+              end
+              instance_variable_set(col, markup_object)           
+            }
+          end
+          
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, ActiveRecord::Acts::AsMarkup