escapement 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7756a2e57d00b9d7842a0f09fb4396755144b620
+  data.tar.gz: e04508786e9c91d6778f4f1e97a4386c79025f33
+SHA512:
+  metadata.gz: 65e3b2b84fb12da56c5f979764776b65aac28e992246b4ff601603fe51624d9623dc0287ffeb94f8993ecc531f2a2974bc41bbabf2f0538aa8e5cd9c1e753d2b
+  data.tar.gz: 744c837d2c0477c353fe604e0b192f31df63894ee2403b70a6e28323d7253699bc02613fb841e4700457dc02c4e2b0e11102957f163986181533c7542cfdaee3

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format progress
+--color

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in escapement.gemspec
+gemspec

data/README.md

@@ -0,0 +1,52 @@
+# Escapement
+
+Given a HTML formatted string, escapement will extract descendant tags into a device agnostic attributes array that can be used for formatting the text anywhere.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'escapement'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install escapement
+
+## Usage
+
+Basic usage is very straightforward. Escapement will consider all root-level tags as separate paragraphs.
+
+The position values are 0-based and are relative to the plain text result. The first value is the start of the attributed text, and the second is the end of the attributed text.
+
+``` ruby
+body = "<p>Isn't <i>Tourbillon</i> a <a href=\"http://google.com\">great</a> word?</p>"
+
+html = Escapement::HTML.new(body)
+html.extract!
+html.results
+# => [{:text=>"Isn't Tourbillon a great word?", :entities=>[{:type=>"italic", :html_tag=>"i", :position=>[6, 16], :attributes=>{}}, {:type=>"link", :html_tag=>"a", :position=>[19, 24], :attributes=>{"href"=>"http://google.com"}}]}] 
+```
+
+## How It Works
+
+From a high level, Escapement uses [Nokogiri](https://github.com/sparklemotion/nokogiri) to recursively traverse the DOM tree. As it traverses, it keeps track of the current position of the node relative to the text content in order to determine entity position. There are no regular expression hacks involved.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/escapement/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "escapement"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/escapement.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'escapement/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "escapement"
+  spec.version       = Escapement::VERSION
+  spec.authors       = ["Ryan LeFevre"]
+  spec.email         = ["ryan@hodinkee.com"]
+
+  spec.summary       = %q{Extract child entities from an HTML string.}
+  spec.description   = %q{Given a HTML formatted string, escapement will extract descendant tags into a device agnostic attributes array that can be used for formatting the text anywhere.}
+  spec.homepage      = "https://github.com/hodinkee/escapement"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.0.0"
+
+  spec.add_dependency "nokogiri", "~> 1.6"
+
+  spec.add_development_dependency "bundler", "~> 1.9"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3"
+end

data/lib/escapement/attributes.rb

@@ -0,0 +1,19 @@
+module Escapement
+  # These methods filter the allowed attributes on entities in order to cut
+  # down on the noise returned with the results.
+  module Attributes extend self
+    # By default we allow no attributes in order to cut down on noise as
+    # much as possible. Attributes can be whitelisted on a per-tag basis.
+    def default(key, value)
+      false
+    end
+
+    def a(key, value)
+      true if key == "href"
+    end
+
+    def img(key, value)
+      true if ['src', 'width', 'height'].include?(key)
+    end
+  end
+end

data/lib/escapement/block.rb

@@ -0,0 +1,25 @@
+module Escapement
+  # A block represents a paragraph, which is a root-level element in the
+  # given HTML string. Each paragraph has it's own text value and array of entities.
+  class Block
+    include Traversal
+
+    attr_reader :node, :result
+
+    def initialize(node)
+      @node = node
+      @entities = []
+      @result = nil
+      @current_position = 0
+    end
+
+    def process!
+      process_children
+
+      @result = {
+        text: node.text,
+        entities: @entities
+      }
+    end
+  end
+end

data/lib/escapement/html.rb

@@ -0,0 +1,20 @@
+module Escapement
+  # Wrapper around the entire document, which contains an array of
+  # results. Each result is the text value and entities for a single
+  # paragraph/block.
+  class HTML
+    attr_reader :doc, :blocks, :results
+
+    def initialize(html)
+      @doc = Nokogiri::HTML(html)
+      @blocks = []
+      @results = nil
+    end
+
+    # Extracts all of the entities for each paragraph/block.
+    def extract!
+      @blocks = doc.css('body').children.map { |child| Block.new(child).tap(&:process!) }
+      @results = @blocks.map(&:result)
+    end
+  end
+end

data/lib/escapement/tag.rb

@@ -0,0 +1,51 @@
+module Escapement
+  # A tag represents an entity that may or may not have child elements.
+  # Once we extract the data about this DOM node, we recursively continue
+  # the traversal until we reach the leaf text node.
+  class Tag
+    include Traversal
+
+    attr_reader :node, :entities
+
+    def initialize(node, start_position)
+      @node = node
+      @start_position = @current_position = start_position
+      @entities = []
+    end
+
+    def process
+      @entities << {
+        type: node_to_type,
+        html_tag: node.name,
+        position: [@current_position, @current_position + node.text.length],
+        attributes: Hash[filtered_attributes.map { |k, v| [k, v.value] }]
+      }
+      
+      process_children
+    end
+
+    private
+
+    def node_to_type
+      case node.name
+      when 'p' then 'paragraph'
+      when 'a' then 'link'
+      when 'i', 'em' then 'italic'
+      when 'u' then 'underline'
+      when 'strong', 'b' then 'bold'
+      when 'abbr' then 'abbreviation'
+      when 'q' then 'quote'
+      when 'pre' then 'preformatted'
+      when 'img' then 'image'
+      when 'li' then 'list_item'
+      when /h\d/ then 'header'
+      else node.name
+      end
+    end
+
+    def filtered_attributes
+      method_name = Attributes.respond_to?(node.name) ? node.name : :default
+      node.attributes.select(&Attributes.method(method_name))
+    end
+  end
+end

data/lib/escapement/traversal.rb

@@ -0,0 +1,24 @@
+module Escapement
+  module Traversal
+    # Processes all child nodes of the current node. As the recursion unwinds, we
+    # update the entities array such that we're left with a full result set at
+    # the root, which is the Block object.
+    def process_children
+      node.children.each do |child|
+        if child.text?
+          # If the child node is a text node, we know there are no entities. We simply
+          # increase the current position and continue.
+          @current_position += child.content.length
+        else
+          # The node is not a text node, so it must be an entity of some kind. Continue
+          # the recursion.
+          tag = Escapement::Tag.new(child, @current_position)
+          tag.process
+
+          @current_position += child.content.length
+          @entities.concat tag.entities
+        end
+      end
+    end
+  end
+end

data/lib/escapement/version.rb

@@ -0,0 +1,3 @@
+module Escapement
+  VERSION = "0.1.0"
+end

data/lib/escapement.rb

@@ -0,0 +1,7 @@
+require "nokogiri"
+require "escapement/traversal"
+require "escapement/attributes"
+require "escapement/block"
+require "escapement/html"
+require "escapement/tag"
+require "escapement/version"

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: escapement
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ryan LeFevre
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-07-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: Given a HTML formatted string, escapement will extract descendant tags
+  into a device agnostic attributes array that can be used for formatting the text
+  anywhere.
+email:
+- ryan@hodinkee.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- escapement.gemspec
+- lib/escapement.rb
+- lib/escapement/attributes.rb
+- lib/escapement/block.rb
+- lib/escapement/html.rb
+- lib/escapement/tag.rb
+- lib/escapement/traversal.rb
+- lib/escapement/version.rb
+homepage: https://github.com/hodinkee/escapement
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Extract child entities from an HTML string.
+test_files: []