article_json 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 14715c8b4542d6737963ab39e16c97a2060454ab
+  data.tar.gz: ae62279949f41500e34cb18bd1642b73c6bbb86a
+SHA512:
+  metadata.gz: 877ad153850744cd40a169240b1151ee09612775eb7bc4e53f5cebc60b0fc9c859e3861ebc4b1c3b119a618c905242945a681d1f749b1fedbfff69281ed5cd9c
+  data.tar.gz: a636ea3a56f54700275e31a38df2b41ed23f1c9d8199e5b5408b078c3e33fc999872406194bddc238bd57352a52f0e22c6ca3bef34ad43942b2a0eb06ed7d6f5

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## ? - WIP
+
+## 0.1.0 - 2017/09/20
+This is the very first release, with the following functionality:
+- article-json format that supports several basic elements; like headings, 
+  paragraphs, images or lists
+- Resolving of embedded elements like videos or tweets via OEmbed standard
+- Conversion from and to JSON (or ruby hashes)
+- Parsing of HTML exports from Google documents
+- Export into plain HTML

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Devex <https://www.devex.com>
+
+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,78 @@
+# article_json
+JSON Format for News Articles & Ruby Gem.
+
+## Status
+[![Gem Version](https://badge.fury.io/rb/article_json.svg)](https://badge.fury.io/rb/article_json)
+[![Build Status](https://travis-ci.org/Devex/article_json.svg)](https://travis-ci.org/Devex/article_json)
+[![Code Climate](https://codeclimate.com/github/Devex/article_json/badges/gpa.svg)](https://codeclimate.com/github/Devex/article_json)
+[![Coverage Status](https://coveralls.io/repos/github/Devex/article_json/badge.svg?branch=master)](https://coveralls.io/github/Devex/article_json?branch=master)
+
+## Usage
+First, install the gem with `gem install article_json` or add it to your Gemfile
+via `gem 'article_json'`.
+
+### Ruby
+```ruby
+require 'article_json'
+
+# parse the HTML export of a Google Document
+article = ArticleJSON::Article.from_google_doc_html(google_doc_html)
+
+# initialize article-json format from storage (JSON string)
+article = ArticleJSON::Article.from_json(json_string)
+
+# initialize article-json format from storage (already parsed JSON)
+article = ArticleJSON::Article.from_hash(parsed_json)
+
+# export article as HTML
+puts article.to_html
+
+# export article as JSON
+puts article.to_json
+```
+
+### CLI
+To load, parse and html-export the latest version of the reference document,
+run the following:
+
+```
+$ export DOC_ID=1E4lncZE2jDkbE34eDyYQmXKA9O26BHUiwguz4S9qyE8
+$ ./bin/article_json_export_google_doc.rb $DOC_ID \
+    | ./bin/article_json_parse_google_doc.rb \
+    | ./bin/article_json_export_html.rb
+```
+
+## Format
+A full example of the format can be found in the test fixtures:
+[Parsed Reference Document](https://github.com/Devex/article_json/blob/master/spec/fixtures/reference_document_parsed.json)
+
+## Import
+### Google Document Parser
+This [Reference Document](https://docs.google.com/document/d/1E4lncZE2jDkbE34eDyYQmXKA9O26BHUiwguz4S9qyE8/edit?usp=sharing)
+lists contains all supported formatting along with some descriptions.
+
+## Export
+### HTML
+The HTML exporter generates a HTML string for a list of elements. An example of
+the HTML export for the parsed reference document can be found 
+[here](https://github.com/Devex/article_json/blob/master/spec/fixtures/reference_document_exported.html).
+
+## Contributing
+- Fork this repository
+- Implement your feature or fix including Tests
+- Update the [change log](CHANGELOG.md)
+- Commit your changes with a meaningful commit message
+- Create a pull request
+
+Thank you!
+
+See the 
+[list of contributors](https://github.com/Devex/article_json/contributors).
+
+### Tests
+For the whole test suite, run `bundle exec rspec`.
+
+For individual tests, run `bundle exec rspec spec/article_json/version_spec.rb`. 
+
+## License
+MIT License, see the [license file](LICENSE).

data/bin/article_json_export_google_doc.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#
+# Simple script to load an HTML export for a Google document by ID.
+#
+# Usage:
+#
+#   ./bin/article_json_export_google_doc.rb $GOOGLE_DOC_ID
+#
+# Note: The document has to be publicly accessible via link. If the docuement is
+#       private, you can use the URL schema below and open it in a browser while
+#       being signed in to Google Drive.
+#
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+require 'net/http'
+require 'uri'
+
+doc_id = ARGV.first
+url = "https://docs.google.com/feeds/download/documents/export/Export?id=#{doc_id}&exportFormat=html"
+puts Net::HTTP.get(URI.parse(url))

data/bin/article_json_export_html.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#
+# Simple script to read a JSON document and export it to HTML.
+#
+# Usage:
+#
+#   ./bin/article_json_export_html.rb < my_document.json
+#
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+require_relative '../lib/article_json'
+puts ArticleJSON::Article.from_json(ARGF.read).to_html

data/bin/article_json_parse_google_doc.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#
+# Simple script to read a Google Doc HTML export from STDIN and parse it.
+#
+# Usage:
+#
+#   ./bin/article_json_parse_google_doc.rb < my_document.html
+#
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+require_relative '../lib/article_json'
+puts ArticleJSON::Article.from_google_doc_html((ARGF.read)).to_json

data/bin/update_reference_document.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env sh
+
+# set google doc id
+DOC_ID="1E4lncZE2jDkbE34eDyYQmXKA9O26BHUiwguz4S9qyE8"
+
+# set file locations
+SOURCE_HTML_FILE="spec/fixtures/reference_document.html"
+JSON_FILE="spec/fixtures/reference_document_parsed.json"
+HTML_EXPORT_FILE="spec/fixtures/reference_document_exported.html"
+
+# export the google doc to HTML
+./bin/article_json_export_google_doc.rb ${DOC_ID} > ${SOURCE_HTML_FILE}
+
+# convert the google doc html export to JSON
+./bin/article_json_parse_google_doc.rb < ${SOURCE_HTML_FILE} | jq . > ${JSON_FILE}
+
+# convert the JSON export to HTML
+./bin/article_json_export_html.rb < ${JSON_FILE} > ${HTML_EXPORT_FILE}

data/lib/article_json/article.rb

@@ -0,0 +1,53 @@
+module ArticleJSON
+  class Article
+    attr_reader :elements
+
+    # @param [Arra[ArticleJSON::Elements::Base]] elements
+    def initialize(elements)
+      @elements = elements
+    end
+
+    # Hash representation of the article
+    # @return [Hash]
+    def to_h
+      {
+        article_json_version: VERSION,
+        content: @elements.map(&:to_h),
+      }
+    end
+
+    # JSON representation of the article
+    # @return [String]
+    def to_json
+      to_h.to_json
+    end
+
+    # HTML export of the article
+    # @return [String]
+    def to_html
+      ArticleJSON::Export::HTML::Exporter.new(@elements).html
+    end
+
+    class << self
+      # Build a new article from hash (like the one generated by #to_h)
+      # @return [ArticleJSON::Article]
+      def from_hash(hash)
+        hash = { content: hash } if hash.is_a?(Array)
+        new(ArticleJSON::Elements::Base.parse_hash_list(hash[:content]))
+      end
+
+      # Build a new article from JSON (like the one generated by #to_json)
+      # @return [ArticleJSON::Article]
+      def from_json(json)
+        from_hash(JSON.parse(json, symbolize_names: true))
+      end
+
+      # Build a new article from a Google Doc HTML export
+      # @return [ArticleJSON::Article]
+      def from_google_doc_html(html)
+        parser = ArticleJSON::Import::GoogleDoc::HTML::Parser.new(html)
+        new(parser.parsed_content)
+      end
+    end
+  end
+end

data/lib/article_json/configuration.rb

@@ -0,0 +1,24 @@
+module ArticleJSON
+  ## Add configuration access and block to main module
+  class << self
+    attr_accessor :configuration
+
+    # @return [ArticleJSON::Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+
+  class Configuration
+    attr_accessor :oembed_user_agent
+
+    def initialize
+      @oembed_user_agent = nil
+    end
+  end
+end
+

data/lib/article_json/elements/base.rb

@@ -0,0 +1,40 @@
+module ArticleJSON
+  module Elements
+    class Base
+      attr_reader :type
+
+      class << self
+        # Create an element from a hash, based on the :type field
+        # @param [Hash] hash
+        # @return [ArticleJSON::Elements::Base]
+        def parse_hash(hash)
+          klass = element_classes[hash[:type].to_sym]
+          klass.parse_hash(hash) unless klass.nil?
+        end
+
+        # Create a list of elements from an array of hashes
+        # @param [Array[Hash]] hash_list
+        # @return [Array[ArticleJSON::Elements::Base]]
+        def parse_hash_list(hash_list)
+          hash_list.map { |hash| Base.parse_hash(hash) }.compact
+        end
+
+        private
+
+        def element_classes
+          {
+            embed: Embed,
+            heading: Heading,
+            image: Image,
+            list: List,
+            paragraph: Paragraph,
+            quote: Quote,
+            text: Text,
+            text_box: TextBox,
+          }
+        end
+      end
+    end
+  end
+end
+

data/lib/article_json/elements/embed.rb

@@ -0,0 +1,58 @@
+module ArticleJSON
+  module Elements
+    class Embed < Base
+      attr_reader :embed_type, :embed_id, :caption, :tags
+
+      # @param [Symbol] embed_type
+      # @param [String] embed_id
+      # @param [Array[ArticleJSON::Elements::Text]] caption
+      # @param [Array] tags
+      def initialize(embed_type:, embed_id:, caption:, tags: [])
+        @type = :embed
+        @embed_type = embed_type
+        @embed_id = embed_id
+        @caption = caption
+        @tags = tags
+      end
+
+      # Hash representation of this embedded element
+      # @return [Hash]
+      def to_h
+        {
+          type: type,
+          embed_type: embed_type,
+          embed_id: embed_id,
+          tags: tags,
+          caption: caption.map(&:to_h),
+        }
+      end
+
+      # Obtain the oembed data for this embed element
+      # @return [Hash]
+      def oembed_data
+        oembed_resolver&.oembed_data
+      end
+
+      private
+
+      # @return [ArticleJSON::Utils::OEmbedResolver::Base]
+      def oembed_resolver
+        @oembed_resolver ||=
+          ArticleJSON::Utils::OEmbedResolver::Base.build(self)
+      end
+
+      class << self
+        # Create an embedded element from Hash
+        # @return [ArticleJSON::Elements::Embed]
+        def parse_hash(hash)
+          new(
+            embed_type: hash[:embed_type],
+            embed_id: hash[:embed_id],
+            caption: parse_hash_list(hash[:caption]),
+            tags: hash[:tags]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/article_json/elements/heading.rb

@@ -0,0 +1,37 @@
+module ArticleJSON
+  module Elements
+    class Heading < Base
+      attr_reader :level, :content
+
+      # @param [String] level
+      # @param [String] content
+      def initialize(level:, content:)
+        @level = level
+        @content = content
+        @type = :heading
+      end
+
+      # Hash representation of this heading element
+      # @return [Hash]
+      def to_h
+        {
+          type: type,
+          level: level,
+          content: content,
+        }
+      end
+
+      class << self
+        # Create a heading element from Hash
+        # @return [ArticleJSON::Elements::Heading]
+        def parse_hash(hash)
+          new(
+            level: hash[:level].to_i,
+            content: hash[:content]
+          )
+        end
+      end
+    end
+  end
+end
+

data/lib/article_json/elements/image.rb

@@ -0,0 +1,41 @@
+module ArticleJSON
+  module Elements
+    class Image < Base
+      attr_reader :source_url, :caption, :float
+
+      # @param [String] source_url
+      # @param [Array[ArticleJSON::Elements::Text]] caption
+      # @param [Symbol] float
+      def initialize(source_url:, caption:, float: nil)
+        @type = :image
+        @source_url = source_url
+        @caption = caption
+        @float = float
+      end
+
+      # Hash representation of this image element
+      # @return [Hash]
+      def to_h
+        {
+          type: type,
+          source_url: source_url,
+          float: float,
+          caption: caption.map(&:to_h),
+        }
+      end
+
+      class << self
+        # Create a image element from Hash
+        # @return [ArticleJSON::Elements::Image]
+        def parse_hash(hash)
+          new(
+            source_url: hash[:source_url],
+            caption: parse_hash_list(hash[:caption]),
+            float: hash[:float]&.to_sym
+          )
+        end
+      end
+    end
+  end
+end
+

data/lib/article_json/elements/list.rb

@@ -0,0 +1,37 @@
+module ArticleJSON
+  module Elements
+    class List < Base
+      attr_reader :content, :list_type
+
+      # @param [Array[ArticleJSON::Elements::Paragraph]] content
+      # @param [Symbol] list_type
+      def initialize(content:, list_type: :unordered)
+        @type = :list
+        @content = content
+        @list_type = list_type
+      end
+
+      # Hash representation of this heading element
+      # @return [Hash]
+      def to_h
+        {
+          type: type,
+          list_type: list_type,
+          content: content.map(&:to_h),
+        }
+      end
+
+      class << self
+        # Create a list element from Hash
+        # @return [ArticleJSON::Elements::List]
+        def parse_hash(hash)
+          new(
+            content: parse_hash_list(hash[:content]),
+            list_type: hash[:list_type].to_sym
+          )
+        end
+      end
+    end
+  end
+end
+

data/lib/article_json/elements/paragraph.rb

@@ -0,0 +1,31 @@
+module ArticleJSON
+  module Elements
+    class Paragraph < Base
+      attr_reader :content
+
+      # @param [Array[ArticleJSON::Elements::Text]] content
+      def initialize(content:)
+        @type = :paragraph
+        @content = content
+      end
+
+      # Hash representation of this heading element
+      # @return [Hash]
+      def to_h
+        {
+          type: type,
+          content: content.map(&:to_h),
+        }
+      end
+
+      class << self
+        # Create a paragraph element from Hash
+        # @return [ArticleJSON::Elements::Paragraph]
+        def parse_hash(hash)
+          new(content: parse_hash_list(hash[:content]))
+        end
+      end
+    end
+  end
+end
+

data/lib/article_json/elements/quote.rb

@@ -0,0 +1,41 @@
+module ArticleJSON
+  module Elements
+    class Quote < Base
+      attr_reader :content, :caption, :float
+
+      # @param [Array[ArticleJSON::Elements::Paragraph]] content
+      # @param [Array[ArticleJSON::Elements::Text]] caption
+      # @param [Symbol] float
+      def initialize(content:, caption:, float: nil)
+        @type = :quote
+        @content = content
+        @caption = caption
+        @float = float
+      end
+
+      # Hash representation of this quote element
+      # @return [Hash]
+      def to_h
+        {
+          type: type,
+          float: float,
+          content: content.map(&:to_h),
+          caption: caption.map(&:to_h),
+        }
+      end
+
+      class << self
+        # Create a quote element from Hash
+        # @return [ArticleJSON::Elements::Quote]
+        def parse_hash(hash)
+          new(
+            content: parse_hash_list(hash[:content]),
+            caption: parse_hash_list(hash[:caption]),
+            float: hash[:float]&.to_sym
+          )
+        end
+      end
+    end
+  end
+end
+

data/lib/article_json/elements/text.rb

@@ -0,0 +1,45 @@
+module ArticleJSON
+  module Elements
+    class Text < Base
+      attr_reader :content, :bold, :italic, :href
+
+      # @param [String] content
+      # @param [Boolean] bold
+      # @param [Boolean] italic
+      # @param [String] href
+      def initialize(content:, bold: false, italic: false, href: nil)
+        @type = :text
+        @content = content
+        @bold = bold
+        @italic = italic
+        @href = href
+      end
+
+      # Hash representation of this text node
+      # @return [Hash]
+      def to_h
+        {
+          type: type,
+          content: content,
+          bold: bold,
+          italic: italic,
+          href: href,
+        }
+      end
+
+      class << self
+        # Create a text element from Hash
+        # @return [ArticleJSON::Elements::Text]
+        def parse_hash(hash)
+          new(
+            content: hash[:content],
+            bold: hash[:bold],
+            italic: hash[:italic],
+            href: hash[:href]
+          )
+        end
+      end
+    end
+  end
+end
+

data/lib/article_json/elements/text_box.rb

@@ -0,0 +1,37 @@
+module ArticleJSON
+  module Elements
+    class TextBox < Base
+      attr_reader :content, :float
+
+      # @param [Array[Paragraph|Heading|List]] content
+      # @param [Symbol] float
+      def initialize(content:, float: nil)
+        @type = :text_box
+        @content = content
+        @float = float
+      end
+
+      # Hash representation of this text box element
+      # @return [Hash]
+      def to_h
+        {
+          type: type,
+          float: float,
+          content: content.map(&:to_h),
+        }
+      end
+
+      class << self
+        # Create a text box element from Hash
+        # @return [ArticleJSON::Elements::TextBox]
+        def parse_hash(hash)
+          new(
+            content: parse_hash_list(hash[:content]),
+            float: hash[:float]&.to_sym
+          )
+        end
+      end
+    end
+  end
+end
+