motion-html-pipeline 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 91205fa1d79198a224c28464e12946d1294ac518124dec20b536e86d77d91a49
+  data.tar.gz: 6388828a786942a593664a2759daec71b61582d283a692ffcd0c5d5b1f9f70d3
+SHA512:
+  metadata.gz: 12a542cb6b5380268836031a1cfabde939bd32dc3bdb9b71ace8060a97f9c1e170d49ed88c06f79e64e62350eb09b68ec7e10952a21e2547d6c5d8d7db28a10c
+  data.tar.gz: 86091ee0ccca5c6e97ec59a04aca17e23f66a56ab28c5f696d4fd8f6145a021cb946d5e216d321cd28bede723e6df773565387313c4b274fb607504d661eda8b

data/README.md

@@ -0,0 +1,379 @@
+# motion-html-pipeline
+
+[![Gem Version](https://badge.fury.io/rb/motion-html-pipeline.svg)](http://badge.fury.io/rb/motion-html-pipeline)
+[![Build Status](https://travis-ci.org/digitalmoksha/motion-html-pipeline.svg?branch=master)](https://travis-ci.org/digitalmoksha/motion-html-pipeline)
+
+This gem is a port of the [`html-pipeline` gem](https://github.com/jch/html-pipeline) to RubyMotion, for use on iOS and macOS. Currently synced with `html-pipeline` release [`v.2.11.0`](https://github.com/jch/html-pipeline/releases/tag/v2.11.0)
+
+Several of the standard filters, such as `AutolinkFilter` and `EmojiFilter`, are initially disabled, as they rely on other Ruby gems that don't have RubyMotion equivalents.  Please feel free to submit a pull request that enables any of them.
+
+We use [HTMLKit](https://github.com/iabudiab/HTMLKit) to take the place of Nokogiri.
+
+Below is a copy of the original README file, until I'm able to flesh this one out more.
+
+---
+# 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](#installation)
+- [Usage](#usage)
+  - [Examples](#examples)
+- [Filters](#filters)
+- [Dependencies](#dependencies)
+- [Documentation](#documentation)
+- [Extending](#extending)
+  - [3rd Party Extensions](#3rd-party-extensions)
+- [Instrumenting](#instrumenting)
+- [Contributing](#contributing)
+  - [Contributors](#contributors)
+  - [Releasing A New Version](#releasing-a-new-version)
+
+## 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>
+
+<pre><code>some_code(:first)
+</code></pre>
+```
+
+To generate CSS for HTML formatted code, use the [Rouge CSS Theme](https://github.com/jneen/rouge#css-theme-options) `#css` method. `rouge` is a dependency of the `SyntaxHighlightFilter`.
+
+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 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
+```
+
+### 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 and generate toc list
+  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 [
+  PlainTextInputFilter,
+  ImageMaxWidthFilter
+], {}
+
+# Just emoji.
+EmojiPipeline = Pipeline.new [
+  PlainTextInputFilter,
+  EmojiFilter
+], context
+```
+
+## 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
+* `TextileFilter` - convert textile to html
+* `TableOfContentsFilter` - anchor headings with name attributes and generate Table of Contents html unordered list linking headings
+
+## Dependencies
+
+Filter gem dependencies are not bundled; you must bundle the filter's gem
+dependencies. The below list details filters with dependencies. For example,
+`SyntaxHighlightFilter` uses [rouge](https://github.com/jneen/rouge)
+to detect and highlight languages. For example, to use the `SyntaxHighlightFilter`,
+add the following to your Gemfile:
+
+```ruby
+gem 'rouge'
+```
+
+* `AutolinkFilter` - `rinku`
+* `EmailReplyFilter` - `escape_utils`, `email_reply_parser`
+* `EmojiFilter` - `gemoji`
+* `MarkdownFilter` - `commonmarker`
+* `PlainTextInputFilter` - `escape_utils`
+* `SanitizationFilter` - `sanitize`
+* `SyntaxHighlightFilter` - `rouge`
+* `TableOfContentsFilter` - `escape_utils`
+* `TextileFilter` - `RedCloth`
+
+_Note:_ See [Gemfile](/Gemfile) `:test` block for version requirements.
+
+## Documentation
+
+Full reference documentation can be [found here](http://rubydoc.info/gems/html-pipeline/frames).
+
+## 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' }
+```
+
+### 3rd Party Extensions
+
+If you have an idea for a filter, propose it as
+[an issue](https://github.com/jch/html-pipeline/issues) first. This allows us discuss
+whether the filter is a common enough use case to belong in this gem, or should be
+built as an external gem.
+
+Here are some extensions people have built:
+
+* [html-pipeline-asciidoc_filter](https://github.com/asciidoctor/html-pipeline-asciidoc_filter)
+* [jekyll-html-pipeline](https://github.com/gjtorikian/jekyll-html-pipeline)
+* [nanoc-html-pipeline](https://github.com/burnto/nanoc-html-pipeline)
+* [html-pipeline-bitly](https://github.com/dewski/html-pipeline-bitly)
+* [html-pipeline-cite](https://github.com/lifted-studios/html-pipeline-cite)
+* [tilt-html-pipeline](https://github.com/bradgessler/tilt-html-pipeline)
+* [html-pipeline-wiki-link'](https://github.com/lifted-studios/html-pipeline-wiki-link) - WikiMedia-style wiki links
+* [task_list](https://github.com/github/task_list) - GitHub flavor Markdown Task List
+* [html-pipeline-nico_link](https://github.com/rutan/html-pipeline-nico_link) - An HTML::Pipeline filter for [niconico](http://www.nicovideo.jp) description links
+* [html-pipeline-gitlab](https://gitlab.com/gitlab-org/html-pipeline-gitlab) - This gem implements various filters for html-pipeline used by GitLab
+* [html-pipeline-youtube](https://github.com/st0012/html-pipeline-youtube) - An HTML::Pipeline filter for YouTube links
+* [html-pipeline-flickr](https://github.com/st0012/html-pipeline-flickr) - An HTML::Pipeline filter for Flickr links
+* [html-pipeline-vimeo](https://github.com/dlackty/html-pipeline-vimeo) - An HTML::Pipeline filter for Vimeo links
+* [html-pipeline-hashtag](https://github.com/mr-dxdy/html-pipeline-hashtag) - An HTML::Pipeline filter for hashtags
+* [html-pipeline-linkify_github](https://github.com/jollygoodcode/html-pipeline-linkify_github) - An HTML::Pipeline filter to autolink GitHub urls
+* [html-pipeline-redcarpet_filter](https://github.com/bmikol/html-pipeline-redcarpet_filter) - Render Markdown source text into Markdown HTML using Redcarpet
+* [html-pipeline-typogruby_filter](https://github.com/bmikol/html-pipeline-typogruby_filter) - Add Typogruby text filters to your HTML::Pipeline
+* [korgi](https://github.com/jodeci/korgi) - HTML::Pipeline filters for links to Rails resources
+
+
+## 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
+```
+
+## FAQ
+
+### 1. Why doesn't my pipeline work when there's no root element in the document?
+
+To make a pipeline work on a plain text document, put the `PlainTextInputFilter`
+at the beginning of your pipeline. This will wrap the content in a `div` so the
+filters have a root element to work with. If you're passing in an HTML fragment,
+but it doesn't have a root element, you can wrap the content in a `div`
+yourself. For example:
+
+```ruby
+EmojiPipeline = Pipeline.new [
+  PlainTextInputFilter,  # <- Wraps input in a div and escapes html tags
+  EmojiFilter
+], context
+
+plain_text = "Gutentag! :wave:"
+EmojiPipeline.call(plain_text)
+
+html_fragment = "This is outside of an html element, but <strong>this isn't. :+1:</strong>"
+EmojiPipeline.call("<div>#{html_fragment}</div>") # <- Wrap your own html fragments to avoid escaping
+```
+
+### 2. How do I customize a whitelist for `SanitizationFilter`s?
+
+`SanitizationFilter::WHITELIST` is the default whitelist used if no `:whitelist`
+argument is given in the context. The default is a good starting template for
+you to add additional elements. You can either modify the constant's value, or
+re-define your own constant and pass that in via the context.
+
+## Contributing
+
+Please review the [Contributing Guide](https://github.com/jch/html-pipeline/blob/master/CONTRIBUTING.md).
+
+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)
+
+To see what has changed in recent versions, see the [CHANGELOG](https://github.com/jch/html-pipeline/blob/master/CHANGELOG.md).
+
+### 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/).
+
+### Releasing A New Version
+
+This section is for gem maintainers to cut a new version of the gem.
+
+* create a new branch named `release-x.y.z` where `x.y.z` follows [semver](http://semver.org)
+* update lib/html/pipeline/version.rb to next version number X.X.X
+* update CHANGELOG.md. Prepare a draft with `script/changelog`
+* push branch and create a new pull request
+* after tests are green, merge to master
+* on the master branch, run `script/release`

data/lib/motion-html-pipeline.rb

@@ -0,0 +1,14 @@
+unless defined?(Motion::Project::Config)
+  raise "This file must be required within a RubyMotion project Rakefile."
+end
+
+require 'motion-cocoapods'
+
+lib_dir_path = File.dirname(File.expand_path(__FILE__))
+Motion::Project::App.setup do |app|
+  app.files.unshift(Dir.glob(File.join(lib_dir_path, "motion-html-pipeline/**/*.rb")))
+
+  app.pods do
+    pod 'HTMLKit', '~> 2.1'
+  end
+end

data/lib/motion-html-pipeline/document_fragment.rb

@@ -0,0 +1,27 @@
+# Gives a Nokogiri type of interface, but uses
+# HTMLKit (https://github.com/iabudiab/HTMLKit)
+#
+# Not meant to duplicate Nokogiri completely, just add a similar interface
+#------------------------------------------------------------------------------
+module MotionHTMLPipeline
+  class DocumentFragment < HTMLDocument
+    attr_reader :document
+
+    def self.parse(html)
+      DocumentFragment.new(html)
+    end
+
+    def initialize(html)
+      @document = HTMLDocument.documentWithString(html)
+    end
+
+    def css(query)
+      document.querySelectorAll(query)
+    end
+
+    def to_html
+      document.body.innerHTML
+    end
+    alias :to_s :to_html
+  end
+end

data/lib/motion-html-pipeline/pipeline.rb

@@ -0,0 +1,153 @@
+# require 'nokogiri'
+# require 'active_support/xml_mini/nokogiri' # convert Documents to hashes
+
+module MotionHTMLPipeline
+  # 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.
+  #
+  # See MotionHTMLPipeline::Pipeline::Filter for information on building filters.
+  #
+  # Construct a Pipeline for running multiple HTML filters.  A pipeline is created once
+  # with one to many filters, and it then can be `call`ed many times over the course
+  # of its lifetime with input.
+  #
+  # filters         - Array of Filter objects. Each must respond to call(doc,
+  #                   context) and return the modified DocumentFragment or a
+  #                   String containing HTML markup. Filters are performed in the
+  #                   order provided.
+  # default_context - The default context hash. Values specified here will be merged
+  #                   into values from the each individual pipeline run.  Can NOT be
+  #                   nil.  Default: empty Hash.
+  # result_class    - The default Class of the result object for individual
+  #                   calls.  Default: Hash.  Protip:  Pass in a Struct to get
+  #                   some semblance of type safety.
+  class Pipeline
+    # Parse a String into a DocumentFragment object. When a DocumentFragment is
+    # provided, return it verbatim.
+    def self.parse(document_or_html)
+      document_or_html ||= ''
+      if document_or_html.is_a?(String)
+        DocumentFragment.parse(document_or_html)
+      else
+        document_or_html
+      end
+    end
+
+    # Public: Returns an Array of Filter objects for this Pipeline.
+    attr_reader :filters
+
+    # Public: Instrumentation service for the pipeline.
+    # Set an ActiveSupport::Notifications compatible object to enable.
+    attr_accessor :instrumentation_service
+
+    # Public: String name for this Pipeline. Defaults to Class name.
+    attr_writer :instrumentation_name
+    def instrumentation_name
+      return @instrumentation_name if defined?(@instrumentation_name)
+      @instrumentation_name = self.class.name
+    end
+
+    class << self
+      # Public: Default instrumentation service for new pipeline objects.
+      attr_accessor :default_instrumentation_service
+    end
+
+    def initialize(filters, default_context = {}, result_class = nil)
+      raise ArgumentError, 'default_context cannot be nil' if default_context.nil?
+      @filters = filters.flatten.freeze
+      @default_context = default_context.freeze
+      @result_class = result_class || Hash
+      @instrumentation_service = self.class.default_instrumentation_service
+    end
+
+    # Apply all filters in the pipeline to the given HTML.
+    #
+    # html    - A String containing HTML or a DocumentFragment object.
+    # context - The context hash passed to each filter. See the Filter docs
+    #           for more info on possible values. This object MUST NOT be modified
+    #           in place by filters.  Use the Result for passing state back.
+    # result  - The result Hash passed to each filter for modification.  This
+    #           is where Filters store extracted information from the content.
+    #
+    # Returns the result Hash after being filtered by this Pipeline.  Contains an
+    # :output key with the DocumentFragment or String HTML markup based on the
+    # output of the last filter in the pipeline.
+    def call(html, context = {}, result = nil)
+      context = @default_context.merge(context)
+      context = context.freeze
+      result ||= @result_class.new
+      payload = default_payload filters: @filters.map(&:name),
+                                context: context, result: result
+      instrument 'call_pipeline.html_pipeline', payload do
+        result[:output] =
+          @filters.inject(html) do |doc, filter|
+            perform_filter(filter, doc, context, result)
+          end
+      end
+      result
+    end
+
+    # Internal: Applies a specific filter to the supplied doc.
+    #
+    # The filter is instrumented.
+    #
+    # Returns the result of the filter.
+    def perform_filter(filter, doc, context, result)
+      payload = default_payload filter: filter.name,
+                                context: context, result: result
+      instrument 'call_filter.html_pipeline', payload do
+        filter.call(doc, context, result)
+      end
+    end
+
+    # Like call but guarantee the value returned is a DocumentFragment.
+    # Pipelines may return a DocumentFragment or a String. Callers that need a
+    # DocumentFragment should use this method.
+    def to_document(input, context = {}, result = nil)
+      result = call(input, context, result)
+      MotionHTMLPipeline::Pipeline.parse(result[:output])
+    end
+
+    # Like call but guarantee the value returned is a string of HTML markup.
+    def to_html(input, context = {}, result = nil)
+      result = call(input, context, result = nil)
+      output = result[:output]
+      if output.respond_to?(:to_html)
+        output.to_html
+      else
+        output.to_s
+      end
+    end
+
+    # Public: setup instrumentation for this pipeline.
+    #
+    # Returns nothing.
+    def setup_instrumentation(name = nil, service = nil)
+      self.instrumentation_name = name
+      self.instrumentation_service =
+        service || self.class.default_instrumentation_service
+    end
+
+    # Internal: if the `instrumentation_service` object is set, instruments the
+    # block, otherwise the block is ran without instrumentation.
+    #
+    # Returns the result of the provided block.
+    def instrument(event, payload = nil)
+      payload ||= default_payload
+      return yield(payload) unless instrumentation_service
+      instrumentation_service.instrument event, payload do |payload|
+        yield payload
+      end
+    end
+
+    # Internal: Default payload for instrumentation.
+    #
+    # Accepts a Hash of additional payload data to be merged.
+    #
+    # Returns a Hash.
+    def default_payload(payload = {})
+      { pipeline: instrumentation_name }.merge(payload)
+    end
+  end
+end