geothird-html-pipeline 0.0.12

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5345ec14f85df8e82bc3aca081c65e4b94aa7878
+  data.tar.gz: d6bdcd46d8baad4c6bda04d5f1ecedaedde72aa0
+SHA512:
+  metadata.gz: f5d4cf9bc9dca29a4330cc8000889f64e9ea1fffb0fef0fec01f50d20f8870f60961f0e1bb997d210f71c6a4619cc915b993de6689e2b9ab4741192ebfaf9f41
+  data.tar.gz: 6688675d57544c1004330867842bd3062970c74322e5fe4800bb37f30466c83d5d06588c859418503520dfc18b3ab0f8146e9d3904dce4a4d7b6a65c8c04dbf0

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+exec/*
+vendor/gems

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+
+before_install:
+  - sudo apt-get update -qq
+  - sudo apt-get install -qq libicu-dev
+
+script: "bundle exec rake"
+
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - ree

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# CHANGELOG
+
+## 0.0.12
+
+  * add additional payload information for instrumentation mtodd #46
+  * generate and link to gem docs in README
+
+## 0.0.11
+
+  * add instrumentation support. readme cleanup mtodd #45
+
+## 0.0.10
+
+  * add bin/html-pipeline util indirect #44
+  * add result[:mentioned_usernames] for MentionFilter fachen #42
+
+## 0.0.9
+
+  * bump escape_utils ~> 0.3, github-linguist ~> 2.6.2 brianmario #41
+  * remove nokogiri monkey patch for ruby >= 1.9 defunkt #40
+
+## 0.0.8
+
+  * raise LoadError instead of printing to stderr if linguist is missing. gjtorikian #36
+
+## 0.0.7
+
+  * optionally require github-linguist chrislloyd #33
+
+## 0.0.6
+
+  * don't mutate markdown strings: jakedouglas #32
+
+## 0.0.5
+
+  * fix li xss vulnerability in sanitization filter: vmg #31
+  * gemspec cleanup: nbibler #23, jbarnette #24
+  * doc updates: jch #16, pborreli #17, wickedshimmy #18, benubois #19, blackerby #21
+  * loosen gemoji dependency: josh #15
+
+## 0.0.4
+
+  * initial public release

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in html-pipeline.gemspec
+gemspec
+
+group :development do
+  gem 'bundler'
+  gem 'rake'
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 GitHub Inc. and Jerry Cheung
+
+MIT License
+
+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.md

@@ -0,0 +1,274 @@
+# HTML::Pipeline [![Build Status](https://secure.travis-ci.org/jch/html-pipeline.png)](http://travis-ci.org/jch/html-pipeline)
+
+GitHub HTML processing filters and utilities. This module includes a small
+framework for defining DOM based content filters and applying them to user
+provided content. Read an introduction about this project in
+[this blog post](https://github.com/blog/1311-html-pipeline-chainable-content-filters).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'html-pipeline'
+```
+
+And then execute:
+
+```sh
+$ bundle
+```
+
+Or install it yourself as:
+
+```sh
+$ gem install html-pipeline
+```
+
+## Usage
+
+This library provides a handful of chainable HTML filters to transform user
+content into markup. A filter takes an HTML string or
+`Nokogiri::HTML::DocumentFragment`, optionally manipulates it, and then
+outputs the result.
+
+For example, to transform Markdown source into Markdown HTML:
+
+```ruby
+require 'html/pipeline'
+
+filter = HTML::Pipeline::MarkdownFilter.new("Hi **world**!")
+filter.call
+```
+
+Filters can be combined into a pipeline which causes each filter to hand its
+output to the next filter's input. So if you wanted to have content be
+filtered through Markdown and be syntax highlighted, you can create the
+following pipeline:
+
+```ruby
+pipeline = HTML::Pipeline.new [
+  HTML::Pipeline::MarkdownFilter,
+  HTML::Pipeline::SyntaxHighlightFilter
+]
+result = pipeline.call <<-CODE
+This is *great*:
+
+    some_code(:first)
+
+CODE
+result[:output].to_s
+```
+
+Prints:
+
+```html
+<p>This is <em>great</em>:</p>
+
+<div class="highlight">
+<pre><span class="n">some_code</span><span class="p">(</span><span class="ss">:first</span><span class="p">)</span>
+</pre>
+</div>
+```
+
+Some filters take an optional **context** and/or **result** hash. These are
+used to pass around arguments and metadata between filters in a pipeline. For
+example, if you want don't want to use GitHub formatted Markdown, you can
+pass an option in the context hash:
+
+```ruby
+filter = HTML::Pipeline::MarkdownFilter.new("Hi **world**!", :gfm => false)
+filter.call
+```
+
+## Filters
+
+* `MentionFilter` - replace `@user` mentions with links
+* `AbsoluteSourceFilter` - replace relative image urls with fully qualified versions
+* `AutoLinkFilter` - auto_linking urls in HTML
+* `CamoFilter` - replace http image urls with [camo-fied](https://github.com/atmos/camo) https versions
+* `EmailReplyFilter` - util filter for working with emails
+* `EmojiFilter` - everyone loves [emoji](http://www.emoji-cheat-sheet.com/)!
+* `HttpsFilter` - HTML Filter for replacing http github urls with https versions.
+* `ImageMaxWidthFilter` - link to full size image for large images
+* `MarkdownFilter` - convert markdown to html
+* `PlainTextInputFilter` - html escape text and wrap the result in a div
+* `SanitizationFilter` - whitelist sanitize user markup
+* `SyntaxHighlightFilter` - [code syntax highlighter](#syntax-highlighting)
+* `TextileFilter` - convert textile to html
+* `TableOfContentsFilter` - anchor headings with name attributes
+
+## Syntax highlighting
+
+`SyntaxHighlightFilter` uses [github-linguist](https://github.com/github/linguist)
+to detect and highlight languages. It isn't included as a dependency by default
+because it's a large dependency and
+[a hassle to build on heroku](https://github.com/jch/html-pipeline/issues/33).
+To use the filter, add the following to your Gemfile:
+
+```ruby
+gem 'github-linguist'
+```
+
+## Examples
+
+We define different pipelines for different parts of our app. Here are a few
+paraphrased snippets to get you started:
+
+```ruby
+# The context hash is how you pass options between different filters.
+# See individual filter source for explanation of options.
+context = {
+  :asset_root => "http://your-domain.com/where/your/images/live/icons",
+  :base_url   => "http://your-domain.com"
+}
+
+# Pipeline providing sanitization and image hijacking but no mention
+# related features.
+SimplePipeline = Pipeline.new [
+  SanitizationFilter,
+  TableOfContentsFilter, # add 'name' anchors to all headers
+  CamoFilter,
+  ImageMaxWidthFilter,
+  SyntaxHighlightFilter,
+  EmojiFilter,
+  AutolinkFilter
+], context
+
+# Pipeline used for user provided content on the web
+MarkdownPipeline = Pipeline.new [
+  MarkdownFilter,
+  SanitizationFilter,
+  CamoFilter,
+  ImageMaxWidthFilter,
+  HttpsFilter,
+  MentionFilter,
+  EmojiFilter,
+  SyntaxHighlightFilter
+], context.merge(:gfm => true) # enable github formatted markdown
+
+
+# Define a pipeline based on another pipeline's filters
+NonGFMMarkdownPipeline = Pipeline.new(MarkdownPipeline.filters,
+  context.merge(:gfm => false))
+
+# Pipelines aren't limited to the web. You can use them for email
+# processing also.
+HtmlEmailPipeline = Pipeline.new [
+  ImageMaxWidthFilter
+], {}
+
+# Just emoji.
+EmojiPipeline = Pipeline.new [
+  HTMLInputFilter,
+  EmojiFilter
+], context
+```
+
+## Extending
+To write a custom filter, you need a class with a `call` method that inherits
+from `HTML::Pipeline::Filter`.
+
+For example this filter adds a base url to images that are root relative:
+
+```ruby
+require 'uri'
+
+class RootRelativeFilter < HTML::Pipeline::Filter
+
+  def call
+    doc.search("img").each do |img|
+      next if img['src'].nil?
+      src = img['src'].strip
+      if src.start_with? '/'
+        img["src"] = URI.join(context[:base_url], src).to_s
+      end
+    end
+    doc
+  end
+
+end
+```
+
+Now this filter can be used in a pipeline:
+
+```ruby
+Pipeline.new [ RootRelativeFilter ], { :base_url => 'http://somehost.com' }
+```
+
+## Instrumenting
+
+Filters and Pipelines can be set up to be instrumented when called. The pipeline
+must be setup with an [ActiveSupport::Notifications]
+(http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html)
+compatible service object and a name. New pipeline objects will default to the
+`HTML::Pipeline.default_instrumentation_service` object.
+
+``` ruby
+# the AS::Notifications-compatible service object
+service = ActiveSupport::Notifications
+
+# instrument a specific pipeline
+pipeline = HTML::Pipeline.new [MarkdownFilter], context
+pipeline.setup_instrumentation "MarkdownPipeline", service
+
+# or set default instrumentation service for all new pipelines
+HTML::Pipeline.default_instrumentation_service = service
+pipeline = HTML::Pipeline.new [MarkdownFilter], context
+pipeline.setup_instrumentation "MarkdownPipeline"
+```
+
+Filters are instrumented when they are run through the pipeline. A
+`call_filter.html_pipeline` event is published once the filter finishes. The
+`payload` should include the `filter` name. Each filter will trigger its own
+instrumentation call.
+
+``` ruby
+service.subscribe "call_filter.html_pipeline" do |event, start, ending, transaction_id, payload|
+  payload[:pipeline] #=> "MarkdownPipeline", set with `setup_instrumentation`
+  payload[:filter] #=> "MarkdownFilter"
+  payload[:context] #=> context Hash
+  payload[:result] #=> instance of result class
+  payload[:result][:output] #=> output HTML String or Nokogiri::DocumentFragment
+end
+```
+
+The full pipeline is also instrumented:
+
+``` ruby
+service.subscribe "call_pipeline.html_pipeline" do |event, start, ending, transaction_id, payload|
+  payload[:pipeline] #=> "MarkdownPipeline", set with `setup_instrumentation`
+  payload[:filters] #=> ["MarkdownFilter"]
+  payload[:doc] #=> HTML String or Nokogiri::DocumentFragment
+  payload[:context] #=> context Hash
+  payload[:result] #=> instance of result class
+  payload[:result][:output] #=> output HTML String or Nokogiri::DocumentFragment
+end
+```
+
+## Documentation
+
+Full reference documentation can be [found here](http://rubydoc.info/gems/html-pipeline/frames).
+
+## Development
+
+To see what has changed in recent versions, see the [CHANGELOG](https://github.com/jch/html-pipeline/blob/master/CHANGELOG.md).
+
+```sh
+bundle
+rake test
+```
+
+## Contributing
+
+1. [Fork it](https://help.github.com/articles/fork-a-repo)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new [Pull Request](https://help.github.com/articles/using-pull-requests)
+
+## Contributors
+
+Thanks to all of [these contributors](https://github.com/jch/html-pipeline/graphs/contributors).
+
+Project is a member of the [OSS Manifesto](http://ossmanifesto.org/).

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/bin/html-pipeline

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+require 'html/pipeline'
+
+require 'optparse'
+
+# Accept "help", too
+ARGV.map!{|a| a == "help" ? "--help" : a }
+
+OptionParser.new do |opts|
+  opts.banner = <<-HELP.gsub(/^    /, '')
+    Usage: html-pipeline [-h] [-f]
+           html-pipeline [FILTER [FILTER [...]]] < file.md
+           cat file.md | html-pipeline [FILTER [FILTER [...]]]
+  HELP
+
+  opts.separator "Options:"
+
+  opts.on("-f", "--filters", "List the available filters") do
+    filters = HTML::Pipeline.constants.grep(/\w+Filter$/).
+      map{|f| f.to_s.gsub(/Filter$/,'') }
+
+    # Text filter doesn't work, no call method
+    filters -= ["Text"]
+
+    abort <<-HELP.gsub(/^      /, '')
+      Available filters:
+        #{filters.join("\n        ")}
+    HELP
+  end
+end.parse!
+
+# Default to a GitHub-ish pipeline
+if ARGV.empty?
+
+  filters = [
+    HTML::Pipeline::MarkdownFilter,
+    HTML::Pipeline::SanitizationFilter,
+    HTML::Pipeline::ImageMaxWidthFilter,
+    HTML::Pipeline::EmojiFilter,
+    HTML::Pipeline::AutolinkFilter,
+    HTML::Pipeline::TableOfContentsFilter,
+  ]
+
+  # Add syntax highlighting if linguist is present
+  begin
+    require 'linguist'
+    filters << HTML::Pipeline::SyntaxHighlightFilter
+  rescue LoadError
+  end
+
+else
+
+  def filter_named(name)
+    case name
+    when "Text"
+      raise NameError # Text filter doesn't work, no call method
+    when "Textile"
+      require "RedCloth" # Textile filter doesn't require RedCloth
+    end
+
+    HTML::Pipeline.const_get("#{name}Filter")
+  rescue NameError => e
+    abort "Unknown filter '#{name}'. List filters with the -f option."
+  end
+
+  filters = []
+  until ARGV.empty?
+    name = ARGV.shift
+    filters << filter_named(name)
+  end
+
+end
+
+context = {
+  :asset_root => "/assets",
+  :base_url   => "/",
+  :gfm        => true
+}
+
+puts HTML::Pipeline.new(filters, context).call(ARGF.read)[:output]