html_surgeon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 184ce38f2ca801e35b52003637cdba997487557c
+  data.tar.gz: 23741ef09a0cf4e12150171fcbb93417c86ceef2
+SHA512:
+  metadata.gz: e567d65954530da7c2f33c562f0890813280b7274d68978d6419552aa933fe49e4cac1d5e5110ac454c99c1393381fade85b73d374750e96e92ebc96f7d8cc38
+  data.tar.gz: a25d072d6c15964317a440e5857d24f60ced9ce620b87acfd5f5f48af3b82c507daa8a4edb3c2382fb8078669a6123e2c1d608d3ff34537386ff80ee0a311a25

data/.gitignore

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

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,17 @@
+language: ruby
+rvm:
+  - 2.1.2
+before_install: gem install bundler -v 1.10.3
+
+addons:
+  code_climate:
+    repo_token: ecc7b46e36ad6c2bda5d5b91fc86cbf594b8b5903c72a1fa838e53426093280d
+
+script: 'bundle exec rake spec'
+
+notifications:
+  email:
+    recipients:
+      - eturino@eturino.com
+    on_failure: change
+    on_success: never

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in html_surgeon.gemspec
+gemspec
+
+group :development, :test do
+  gem 'pry'
+  gem 'pry-nav'
+  gem 'pry-stack_explorer'
+  gem 'pry-doc'
+  gem 'pry-rescue'
+end
+
+gem 'codeclimate-test-reporter', :group => :test, :require => nil

data/README.md

@@ -0,0 +1,209 @@
+# HtmlSurgeon
+
+
+[![Gem Version](https://badge.fury.io/rb/html_surgeon.svg)](http://badge.fury.io/rb/html_surgeon)
+[![Build Status](https://travis-ci.org/eturino/html_surgeon.svg?branch=master)](https://travis-ci.org/eturino/html_surgeon)
+[![Code Climate](https://codeclimate.com/github/eturino/html_surgeon.png)](https://codeclimate.com/github/eturino/html_surgeon)
+[![Code Climate Coverage](https://codeclimate.com/github/eturino/html_surgeon/coverage.png)](https://codeclimate.com/github/eturino/html_surgeon)
+
+Make specific changes in a HTML string, optionally adding html attributes with the audit trail of the changes. Uses [Nokogiri](http://www.nokogiri.org/).
+
+## Basic Usage
+
+First, you create a HtmlSurgeon service instance for the given html fragment
+
+```ruby
+GIVEN_HTML = <<-HTML
+<div>
+    <h1>Something</h1>
+    <div id="1" class="lol to-be-changed">1</div>
+    <span>Other</span>
+    <div id="2" class="another to-be-changed">
+        <ul>
+            <li>1</li>
+            <li>2</li>
+        </ul>
+    </div>
+</div>
+HTML
+
+surgeon = HtmlSurgeon.for(GIVEN_HTML) 
+```
+
+if you want to add audit attributes in the HTML tags changed, pass the option in the surgeon service creation
+
+```ruby
+surgeon = HtmlSurgeon.for(GIVEN_HTML, audit: true)
+```
+
+with the surgeon service, you can prepare several change sets. A change set is defined by a node set and a list of changes to be applied on each selected node.
+
+```ruby
+change_set = surgeon.css('div.to-be-changed') # => will return a change_set
+
+change_set.node_set # => will return a Nokogiri's Node Set with the selected nodes (right now it'll get us div ID 1 and div ID 2.
+
+# to prepare a change replace the tag name 'div' for 'article'
+change_set.replace_tag_name('article') 
+    
+# to prepare another change to add a css class in the selected nodes
+change_set.add_css_class('added-class')
+
+# we can add a second one
+change_set.add_css_class('another-added-class') 
+
+```
+
+The changes are not made yet. In order to do it, we call `run` on the change set
+
+```ruby
+change_set.run
+
+surgeon.html # => html with the changes applied
+# =>
+# <div>
+#     <h1>Something</h1>
+#     <article id="1" class="lol to-be-changed added-class another-added-class">1</div>
+#     <span>Other</span>
+#     <article id="2" class="another to-be-changed added-class another-added-class">
+#         <ul>
+#             <li>1</li>
+#             <li>2</li>
+#         </ul>
+#     </div>
+# </div>
+
+
+# original html still in
+surgeon.given_html == GIVEN_HTML # => true
+
+# you can review what was changed in the change set
+change_set.changes
+# =>
+# [
+#   "replace tag name with article",
+#   "add css class added-class",
+#   "add css class another-added-class",
+# ]
+```
+
+We can also chain call the changes in a changeset
+
+```ruby
+surgeon = HtmlService.for(GIVEN_HTML)
+surgeon.css('.lol').replace_tag_name('span').add_css_class('hey').run
+surgeon.html # =>
+# <div>
+#     <h1>Something</h1>
+#     <span id="1" class="lol to-be-changed hey">1</span>
+#     <span>Other</span>
+#     <div id="2" class="another to-be-changed">
+#         <ul>
+#             <li>1</li>
+#             <li>2</li>
+#         </ul>
+#     </div>
+# </div>
+```
+
+If we have enabled audit, we'll get the changes applied to an element in an data attribute.
+It will store, in JSON, an array with all the changes.
+
+```ruby
+surgeon = HtmlService.for(GIVEN_HTML)
+surgeon.css('.lol').replace_tag_name('span').add_css_class('hey').run
+surgeon.html # =>
+# <div>
+#     <h1>Something</h1>
+#     <span id="1" class="lol to-be-changed hey" data-surgeon-audit='[{"change_set":"830e96dc-fa07-40ce-8968-ea5c55ec4b84","changed_at":"2015-07-02T12:52:43.874Z","type":"replace_tag_name","old":"div","new":"span"},{"change_set":"830e96dc-fa07-40ce-8968-ea5c55ec4b84","changed_at":"2015-07-02T12:52:43.874Z","type":"add_css_class","existed_before":false,"class":"hey"}]'>1</span>
+#     <span>Other</span>
+#     <div id="2" class="another to-be-changed">
+#         <ul>
+#             <li>1</li>
+#             <li>2</li>
+#         </ul>
+#     </div>
+# </div># 
+```
+
+the attribute's value (formatted) is:
+
+```json
+[
+  {
+    "change_set":"830e96dc-fa07-40ce-8968-ea5c55ec4b84",
+    "changed_at":"2015-07-02T12:52:43.874Z",
+    "type":"replace_tag_name",
+    "old":"div",
+    "new":"span"
+  },
+  {
+    "change_set":"830e96dc-fa07-40ce-8968-ea5c55ec4b84",
+    "changed_at":"2015-07-02T12:52:43.874Z",
+    "type":"add_css_class",
+    "existed_before":false,
+    "class":"hey"
+  }
+]
+```
+
+it has a `change_set` with the UUID of the change set, `changed_at` with the moment it was applied, and the rest define the change.
+
+## Selecting the Node Set
+
+we use Nokogiri's selections.
+
+### using css
+
+```ruby
+change_set = surgeon.css('div.to-be-changed')
+```
+
+### using xpath
+
+not implemented yet.
+
+
+## Available Changes
+
+### Replace Tag Name
+
+```ruby
+surgeon.css('div.to-be-changed').replace_name_tag('article')
+```
+
+### Add CSS Class
+
+```ruby
+surgeon.css('div.to-be-changed').add_css_class('applied-some-stuff')
+```
+
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'html_surgeon'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install html_surgeon
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake rspec` to run the tests. You can also 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`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/eturino/html_surgeon.
+

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+# Default directory to look in is `/specs`
+# Run with `rake spec`
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.rspec_opts = ['--color']
+end
+
+task :default => :spec
+

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "html_surgeon"
+
+# 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/html_surgeon.gemspec

@@ -0,0 +1,36 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'html_surgeon/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'html_surgeon'
+  spec.version       = HtmlSurgeon::VERSION
+  spec.authors       = ['Eduardo Turiño']
+  spec.email         = ['eturino@eturino.com']
+
+  spec.summary       = %q{Ruby gem for surgical changes in HTML fragment strings, using Nokogiri, with optional audit trail in html attributes}
+  # spec.description   = %q{TODO: Write a longer description or delete this line.}
+  spec.homepage      = 'https://github.com/eturino/html_surgeon'
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+  # else
+  #   raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.'
+  # end
+
+  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.add_dependency 'nokogiri'
+  spec.add_dependency 'activesupport'
+  spec.add_dependency 'oj'
+  spec.add_dependency 'oj_mimic_json'
+  spec.add_development_dependency 'bundler', '~> 1.10'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec'
+end

data/lib/html_surgeon.rb

@@ -0,0 +1,16 @@
+require 'oj_mimic_json'
+require 'nokogiri'
+require 'active_support/all'
+require 'html_surgeon/version'
+require 'html_surgeon/abstract_method_error'
+require 'html_surgeon/service'
+require 'html_surgeon/change_set'
+require 'html_surgeon/change'
+require 'html_surgeon/changes/add_css_class'
+require 'html_surgeon/changes/replace_tag_name'
+
+module HtmlSurgeon
+  def self.for(html_string, **options)
+    Service.new html_string, **options
+  end
+end

data/lib/html_surgeon/abstract_method_error.rb

@@ -0,0 +1,4 @@
+module HtmlSurgeon
+  class AbstractMethodError < StandardError
+  end
+end

data/lib/html_surgeon/change.rb

@@ -0,0 +1,64 @@
+module HtmlSurgeon
+
+  class Change
+    DATA_CHANGE_AUDIT_ATTRIBUTE = 'data-surgeon-audit'.freeze
+
+    attr_reader :change_set
+
+    def initialize(change_set:)
+      @change_set = change_set
+    end
+
+    delegate :audit?, to: :change_set
+    delegate :uuid, :run_time, to: :change_set, prefix: true
+
+    def apply(element)
+      prepare_audit_change(element) if audit?
+
+      apply_in element
+
+      apply_audit_change(element) if audit?
+
+      self
+    end
+
+    def log
+      raise AbstractMethodError, "a lazy developer has not implemented this method in #{self.class}"
+    end
+
+    private
+
+    def prepare_audit_change(element)
+      @audit_data = audit_data(element)
+    end
+
+    def apply_audit_change(element)
+      current = current_audit_data(element)
+      current << @audit_data
+      element[DATA_CHANGE_AUDIT_ATTRIBUTE] = Oj.dump current
+    end
+
+    def current_audit_data(element)
+      current = element[DATA_CHANGE_AUDIT_ATTRIBUTE].presence
+      return [] unless current
+
+      Oj.load current
+    end
+
+    def basic_audit_data
+      {
+        change_set: change_set_uuid,
+        changed_at: change_set_run_time
+      }
+    end
+
+    def audit_data(element)
+      raise AbstractMethodError, "a lazy developer has not implemented this method in #{self.class}"
+    end
+
+    def apply_in(_element)
+      raise AbstractMethodError, "a lazy developer has not implemented this method in #{self.class}"
+    end
+
+  end
+end

data/lib/html_surgeon/change_set.rb

@@ -0,0 +1,52 @@
+module HtmlSurgeon
+
+  class ChangeSet
+    attr_reader :node_set, :base, :change_list, :uuid, :run_time
+
+    def initialize(node_set, base)
+      @node_set    = node_set
+      @base        = base
+      @change_list = []
+      @uuid     = SecureRandom.uuid
+      @run_time = nil
+    end
+
+    delegate :audit?, :html, to: :base
+
+    # TODO: #preview, like run but in another doc, does not change it yet.
+
+    def run
+      @run_time = Time.now.utc
+
+      node_set.each do |element|
+        apply_on_element(element)
+      end
+
+      self
+    end
+
+    def changes
+      change_list.map &:log
+    end
+
+    # CHANGES
+
+    def replace_tag_name(new_tag_name)
+      change_list << Changes::ReplaceTagName.new(change_set: self, new_tag_name: new_tag_name)
+      self
+    end
+
+    def add_css_class(css_class)
+      change_list << Changes::AddCssClass.new(change_set: self, css_class: css_class)
+      self
+    end
+
+    private
+
+    def apply_on_element(element)
+      change_list.each do |change|
+        change.apply(element)
+      end
+    end
+  end
+end

data/lib/html_surgeon/changes/add_css_class.rb

@@ -0,0 +1,40 @@
+module HtmlSurgeon
+  module Changes
+    class AddCssClass < Change
+      attr_reader :css_class
+      CLASS_ATTRIBUTE = 'class'.freeze
+      CLASS_SEPARATOR = ' '.freeze
+
+      def initialize(css_class:, **other)
+        @css_class = css_class
+
+        super **other
+      end
+
+      def log
+        "add css class #{css_class}"
+      end
+
+      private
+      def apply_in(element)
+        classes = element_classes element
+        classes << css_class
+        element.set_attribute(CLASS_ATTRIBUTE, classes.join(CLASS_SEPARATOR))
+      end
+
+      def audit_data(element)
+        basic_audit_data.merge type:           :add_css_class,
+                               existed_before: had_class?(element),
+                               class:          css_class
+      end
+
+      def element_classes(element)
+        element.get_attribute(CLASS_ATTRIBUTE).to_s.split(CLASS_SEPARATOR)
+      end
+
+      def had_class?(element)
+        element_classes(element).include? css_class
+      end
+    end
+  end
+end

data/lib/html_surgeon/changes/replace_tag_name.rb

@@ -0,0 +1,28 @@
+module HtmlSurgeon
+  module Changes
+    class ReplaceTagName < Change
+      attr_reader :new_tag_name
+
+      def initialize(new_tag_name:, **other)
+        @new_tag_name = new_tag_name
+
+        super **other
+      end
+
+      def log
+        "replace tag name with #{new_tag_name}"
+      end
+
+      private
+      def apply_in(element)
+        element.name = new_tag_name
+      end
+
+      def audit_data(element)
+        basic_audit_data.merge type: :replace_tag_name,
+                               old:  element.name,
+                               new:  new_tag_name
+      end
+    end
+  end
+end

data/lib/html_surgeon/service.rb

@@ -0,0 +1,29 @@
+module HtmlSurgeon
+  class Service
+    attr_reader :given_html, :options
+
+    def initialize(html_string, audit: false, **extra_options)
+      @given_html = html_string
+      @audit      = audit
+      @options    = extra_options.merge audit: audit
+    end
+
+    def html
+      @html ||= doc.to_html
+    end
+
+    def audit?
+      !!@audit
+    end
+
+    def css(css_selector)
+      node_set = doc.css(css_selector)
+      ChangeSet.new(node_set, self)
+    end
+
+    private
+    def doc
+      @doc ||= Nokogiri::HTML.fragment @given_html.dup
+    end
+  end
+end

data/lib/html_surgeon/version.rb

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

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification
+name: html_surgeon
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eduardo Turiño
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-07-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: oj_mimic_json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !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: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- eturino@eturino.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- html_surgeon.gemspec
+- lib/html_surgeon.rb
+- lib/html_surgeon/abstract_method_error.rb
+- lib/html_surgeon/change.rb
+- lib/html_surgeon/change_set.rb
+- lib/html_surgeon/changes/add_css_class.rb
+- lib/html_surgeon/changes/replace_tag_name.rb
+- lib/html_surgeon/service.rb
+- lib/html_surgeon/version.rb
+homepage: https://github.com/eturino/html_surgeon
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '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: Ruby gem for surgical changes in HTML fragment strings, using Nokogiri, with
+  optional audit trail in html attributes
+test_files: []
+has_rdoc: