wbzyl-rack-codehighlighter 0.2.0 → 0.2.1

data/README.markdown

@@ -1,33 +1,103 @@
-# Rack Middleware for Code Highlighting
+# Rack::Codehighlighter middleware
 
-Why one should use middleware (filter) for code highlighting?
-The short answer is: because it is unobtrusive.
+*Rack::Codehighlighter* provides a thin wrapper over 
+a bunch of code highlighters to make their usage as generic possible.
 
-In pre-Rack applications era the possible approaches were:
+* ultraviolet
+* coderay
+* syntax
+* prettify
+* censor
 
-1. pure javascript
+Install the gem with:
 
-[*Ruby tips from me, your idol*](http://www.binarylogic.com/2009/04/19/ruby-tips-from-me-your-idol):
-I can not tell you how much time I’ve wasted trying to add in some
-cool feature into rails. I would dig into the rails internals,
-override methods, do all kinds of tricky stuff. I thought I was
-awesome. A month later rails comes out with some cool new feature, I
-update rails and everything explodes.
+    sudo gem install wbzyl-rack-codehighlighter -s http://gems.github.com
 
-Code must be html-escaped.
 
-2. gems (ok) + conection (obtrusive)
+The middleware reads HTML produced by an application, where it looks
+for code blocks to highlight. Below we ask *coderay* to
+highlight all `pre` elements:
 
+    use Rack::Codehighlighter, :coderay, :element => "pre", :pattern => /\A:::(\w+)\s*\n/
 
-To install it, run:
+The middleware uses the pattern to learn what language the code block
+contains, for example
+
+    <pre>:::ruby
+    puts "hello world"
+    </pre>
+
+Plain description what the pattern says: 
+If the element contents begins with three colons, the text following
+the colons, up to the end of line, identifies the language. The text
+matched by the pattern is removed from the code block before
+processing.
+
+The above example could be shortened to:
+
+    use Rack::Codehighlighter, :coderay
+
+because the default values for options are used.
+
+Normalization: 
+
+* highlighted code is always wrapped with `pre` element
+  with attributes appropriate for codehighlighter used. (2
+* language names are taken from Ultraviolet
+
+
+## A simple example with inline template
+
+    # example.rb
+
+    require 'rubygems'
+      
+    gem 'sinatra', '>=0.9.0'
+    require 'sinatra'
+
+    gem 'wbzyl-rack-codehighlighter', '>=0.2.0'
+    require 'rack/codehighlighter'
+    
+    use Rack::Codehighlighter, :censor, :reason => '[[--difficult code removed--]]'
+    
+    get "/" do
+      erb :hello
+    end
+    
+    __END__
+    
+    @@ hello
+    <h3>Fibonacci numbers in Ruby</h3>
+    
+    <pre>:::ruby
+    def fib(n)
+      if n < 2
+        1
+      else
+        fib(n-2) + fib(n-1)
+      end
+    end
+    </pre>
+
+Run the above example with:
+
+    ruby example.rb
+
+The results are accessible from `http://localhost:4567`.
 
-    sudo gem install wbzyl-rack-codehighlighter -s http://gems.github.com
 
-Analyze
+## Why using middleware for code highlighting is awesome?
+
+In pre-Rack applications era possible approaches were:
+
+* pure javascript; cons code must be html-escaped
+* gems;  conection to methods responsible for code highlighting
+  is obtrusive, i.e. via plugin + additional markup
+
+Analyze packages mentioned at the *The Ruby Toolbox* page:
 [Syntax Highlighting](http://ruby-toolbox.com/categories/syntax_highlighting.html)
-packages from the *The Ruby Toolbox* page.
 
-Exisitng practice is obtrusive:
+Links:
 
     http://carboni.ca/projects/harsh/  
       unless HAML is used
@@ -37,14 +107,15 @@ Exisitng practice is obtrusive:
       does't degrade to html: new source tag
     http://github.com/arya/tm_syntax_highlighting/
       how to connect to rails/sinatra?
-    
-Pure Javascript highlighters:
-
-In Ruby on Rails (redcloth)
-
-Add censored method/example.
 
+[*Ruby tips from me, your idol*](http://www.binarylogic.com/2009/04/19/ruby-tips-from-me-your-idol):
+I can not tell you how much time I’ve wasted trying to add in some
+cool feature into rails. I would dig into the rails internals,
+override methods, do all kinds of tricky stuff. I thought I was
+awesome. A month later rails comes out with some cool new feature, I
+update rails and everything explodes.
 
+Conclusion: highlighting via plugins is doomed to explode sooner or later.
 
 
 ## Using with Rack application
@@ -54,128 +125,89 @@ a **Sinatra** application. If your application includes a rackup file or
 uses *Rack::Builder* to construct the application pipeline, simply
 require and use as follows:
 
+    # get one of supported highlighters 
+    gem 'coderay'
+    require 'coderay'
+     
     gem 'wbzyl-rack-codehighlighter'
     require 'rack/codehighlighter'
-    
-    gem 'ultraviolet'
-    require 'uv'
-    
-    use Rack::Codehighlighter, :ultraviolet
+     
+    use Rack::Codehighlighter, :coderay
     run app
 
-Instead of *ultraviolet* you can use other supported highlighters:
-*syntax*, *coderay*, *prettify*.
+Remember to include in the layout an appropriate stylesheet 
+(look into `examples/public/stylesheets` directory 
+for sample stylesheets).
 
-Include in the layout one of provided stylesheets.
 
 ## Using with Rails
 
 In order to use include the following in a Rails application
 `config/environment.rb` file:
 
+    # get one of supported highlighters 
+    require 'coderay'
+      
     require 'rack/codehighlighter'
     
     Rails::Initializer.run do |config|  
+      config.gem 'coderay'
       config.gem 'wbzyl-rack-codehighlighter'
-      config.middleware.use Rack::Codehighlighter, :ultraviolet
+        
+      config.middleware.use Rack::Codehighlighter, :coderay
     end  
 
 Check the Rack configuration:
 
     rake middleware
 
-More configuration options: see below.
-
+Remember to include in the layout an appropriate stylesheet 
+(look into `examples/public/stylesheets` directory 
+for sample stylesheets).
 
-[*Ruby tips from me, your idol*](http://www.binarylogic.com/2009/04/19/ruby-tips-from-me-your-idol):
-Think about what you are doing, try to understand it, come up with a
-better solution, etc.
-*Is it Rack a cool feature?*
-
-
-## Configuration options
-
-Markup your code with:
-
-    <pre><code>:::ruby
-    ...
-    </code></pre>
-
-## Quick Sinatra example
-
-Example (incomplete html, needs a layout file with link to css):
-
-    # file example.rb
-
-    require 'rubygems'
-    require 'sinatra'
-
-    gem 'coderay'
-    require 'coderay'
-    
-    gem 'wbzyl-rack-codehighlighter'
-    require 'rack/codehighlighter'
-    
-    use Rack::Codehighlighter, :coderay
-    
-    get "/" do
-      erb :hello
-    end
-    
-    __END__
-    
-    @@ hello
-    ### Fibonacci numbers in Ruby
-    
-    <pre><code>:::ruby
-    def fib(n)
-      if n < 2
-        1
-      else
-        fib(n-2) + fib(n-1)
-      end
-    end
-    </code></pre>
 
-Run the above example with:
+## Configuration examples
 
-    ruby example.rb
+Coderay:
 
+    use Rack::Codehighlighter, :coderay,
+      :element => "pre", :pattern => /\A:::(\w+)\s*\n/, :logging => false
 
-## More Sinatra examples
+Ultraviolet:
 
-The default markup:
+    use Rack::Codehighlighter, :ultraviolet, :theme => "dawn", :lines => false,
+      :element => "pre", :pattern => /\A:::(\w+)\s*\n/, :logging => false
 
-If the first line begins with three colons, the text following
-the colons identifies the language (ruby in the example). 
-The first line is removed from the code block before processing.
+Prettify:
 
-The directory *examples* contains ready to run, simple Sinatra app. Try
+    use Rack::Codehighlighter, :prettify,
+      :element => "pre", :pattern => /\A:::(\w+)\s*\n/, :logging => false
 
-    rackup -p 4567 config.ru
+Syntax:
 
-or better yet (requires the *thin* gem to be installed):
+    use Rack::Codehighlighter, :syntax,
+      :element => "pre", :pattern => /\A:::(\w+)\s*\n/, :logging => false
 
-    thin --rackup config.ru -p 4567 start
+Censor:
 
+    use Rack::Codehighlighter, :censor, :reason => "[[--  ugly code removed  --]]",
+      :element => "pre", :pattern => /\A:::(\w+)\s*\n/, :logging => false
 
-Finally, visit the following url:
+In the above examples, the default value of each option is used.
 
-    http://localhost:4567
+All highlighters use `pre` element to wrap highlighted code.
+In Markdown, Maruku and RDiscount templates code is wrapped with `pre>code`.
+To remove an extra nesting the `:markdown` option should be used:
 
-and contemplate the sheer beauty of the rendered code.
+    use Rack::Codehighlighter, :coderay, :markdown => true
+      :element => "pre>code", :pattern => /\A:::(\w+)\s*\n/, :logging => false
 
 
-## Supported Highlighters
+## Supported highlighters
 
 These currently include: *Syntax* (fast), *Coderay* (very fast), 
 *Ultraviolet* (slow, but highlights almost any language).
 
-The *Codehighlighter* gem provides a thin interface over a bunch of
-exisitng code highlighters to make their usage as generic possible.
-
-What does it mean? Explain.
-
 
 ### [Syntax](http://syntax.rubyforge.org/)
 

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:patch: 0
+:patch: 1
 :major: 0
 :minor: 2

data/examples/config.ru

@@ -5,14 +5,14 @@ use Rack::Lint
 
 # use default options
 
-#use Rack::Codehighlighter, :prettify, :element => "//pre", :pattern => /\A:::(\w+)\s*\n/, :logging => true
+#use Rack::Codehighlighter, :prettify, :element => "pre", :pattern => /\A:::(\w+)\s*\n/, :logging => true
 
-use Rack::Codehighlighter, :coderay,  :element => "//pre", :pattern => /\A:::(\w+)\s*\n/, :logging => true
+use Rack::Codehighlighter, :coderay,  :element => "pre", :pattern => /\A:::(\w+)\s*\n/, :logging => true
 
-#use Rack::Codehighlighter, :syntax,   :element => "//pre", :pattern => /\A:::(\w+)\s*\n/, :logging => true
+#use Rack::Codehighlighter, :syntax,   :element => "pre", :pattern => /\A:::(\w+)\s*\n/, :logging => true
 
 #use Rack::Codehighlighter, :ultraviolet, :theme => 'dawn',
-#                                       :element => "//pre", :pattern => /\A:::(\w+)\s*\n/, :logging => true
+#                                       :element => "pre", :pattern => /\A:::(\w+)\s*\n/, :logging => true
 
 #use Rack::Codehighlighter, :censor, :reason => '[[--  ugly code removed  --]]'
 

data/lib/rack/codehighlighter.rb

@@ -14,7 +14,7 @@ module Rack
       @app = app
       @highlighter = highlighter
       @opts = {
-        :element => "//pre",
+        :element => "pre",
         :pattern => /\A:::(\w+)\s*\n/,
         :reason => "[[--  ugly code removed  --]]"
       }
@@ -37,7 +37,7 @@ module Rack
         nodes = doc.search(@opts[:element])
         nodes.each do |node|
           s = node.inner_html || "[++where is the code?++]"
-          if @opts[:remove_parent_element]
+          if @opts[:maruku]
             node.parent.swap(send(@highlighter, s))  
           else
             node.swap(send(@highlighter, s))            
@@ -91,7 +91,7 @@ module Rack
       if refs
         lang = refs[1]
         convertor = ::Syntax::Convertors::HTML.for_syntax translate[lang]
-        convertor.convert(unescape_html(string.sub(/\A.*\n/, "")) || "[=this can'n happen=]")
+        convertor.convert(unescape_html(string.sub(@opts[:pattern], "")) || "[=this can'n happen=]")        
       else
         "<pre>#{string}</pre>"
       end
@@ -100,6 +100,7 @@ module Rack
     def coderay(string)
       lang = 'unknown'
       refs = @opts[:pattern].match(string)  # extract language name
+      # instead of pre the original/matched tag should be used
       if refs
         lang = refs[1]
         str = unescape_html(string.sub(@opts[:pattern], ""))
@@ -118,6 +119,7 @@ module Rack
       }
       lang = 'unknown'
       refs = @opts[:pattern].match(string)  # extract language name
+      # instead of pre the original/matched tag should be used      
       if refs 
         lang = refs[1]
         str = string.sub(@opts[:pattern], "")
@@ -137,6 +139,7 @@ module Rack
         str = unescape_html(string.sub(@opts[:pattern], ""))
         "#{::Uv.parse(str, 'xhtml', lang, opts[:lines], opts[:theme])}"
       else
+        # instead of pre the original/matched tag should be used        
         "<pre class='#{opts[:theme]}'>#{string}</pre>"
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: wbzyl-rack-codehighlighter
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Wlodek Bzyl
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-06 00:00:00 -07:00
+date: 2009-06-07 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency