mbrao 1.0.0

data/lib/mbrao/parsing_engines/base.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+#
+# This file is part of the mbrao gem. Copyright (C) 2013 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Mbrao
+  # Engines used to parse contents with metadata.
+  module ParsingEngines
+    # A base class for all parsers.
+    class Base
+      # Parses a whole post content and return its metadata and content parts.
+      #
+      # @param content [Object] The content to parse.
+      # @param options [Hash] Options to customize parsing.
+      # @return [Array] An array of metadata and contents parts.
+      def separate_components(content, options = {})
+        raise Mbrao::Exceptions::Unimplemented.new
+      end
+
+      # Parses metadata part and returns all valid metadata.
+      #
+      # @param content [Object] The content to parse.
+      # @param options [Hash] Options to customize parsing.
+      # @return [Hash] All valid metadata for the content.
+      def parse_metadata(content, options = {})
+        raise Mbrao::Exceptions::Unimplemented.new
+      end
+
+      # Filters content of a post by locale.
+      #
+      # @param content [Content] The content to filter.
+      # @param locales [String|Array] The desired locales. Can include `*` to match all.
+      # @param options [Hash] Options to customize parsing.
+      # @return [String|HashWithIndifferentAccess] Return the filtered content in the desired locales. If only one locale is required, then a `String` is returned, else a `HashWithIndifferentAccess` with locales as keys.
+      def filter_content(content, locales = [], options = {})
+        raise Mbrao::Exceptions::Unimplemented.new
+      end
+
+      # Parses a content and return a {Content Content} object.
+      #
+      # @param content [Object] The content to parse.
+      # @param options [Hash] Options to customize parsing.
+      def parse(content, options = {})
+        metadata, body = separate_components(content, options)
+        metadata = parse_metadata(metadata, options)
+        Mbrao::Content.create(metadata, body)
+      end
+    end
+  end
+end

data/lib/mbrao/parsing_engines/plain_text.rb

@@ -0,0 +1,187 @@
+# encoding: utf-8
+#
+# This file is part of the mbrao gem. Copyright (C) 2013 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Mbrao
+  # Engines used to parse contents with metadata.
+  module ParsingEngines
+    # A class for parsing plain text files.
+    class PlainText < Mbrao::ParsingEngines::Base
+      # Parses a whole post content and return its metadata and content parts.
+      #
+      # @param content [String] The content to parse.
+      # @param options [Hash] Options to customize parsing.
+      # @return [Array] An array of metadata and contents parts.
+      def separate_components(content, options = {})
+        metadata = nil
+        content = content.ensure_string.strip
+        options = sanitize_options(options)
+        scanner = StringScanner.new(content)
+        end_tag = options[:meta_tags].last
+
+        if scanner.scan_until(options[:meta_tags].first) && (metadata = scanner.scan_until(end_tag)) then
+          metadata = metadata.partition(end_tag).first
+          content = scanner.rest.strip
+        end
+
+        [metadata.ensure_string.strip, content]
+      end
+
+      # Parses metadata part and returns all valid metadata.
+      #
+      # @param content [String] The content to parse.
+      # @param options [Hash] Options to customize parsing.
+      # @return [Hash] All valid metadata for the content.
+      def parse_metadata(content, options = {})
+        begin
+          YAML.load(content)
+        rescue Exception => e
+          options[:default] ? options[:default] : (raise ::Mbrao::Exceptions::InvalidMetadata.new(e.to_s))
+        end
+      end
+
+      # Filters content of a post by locale.
+      #
+      # @param content [Content] The content to filter.
+      # @param locales [String|Array] The desired locales. Can include `*` to match all. If none are specified, the default Mbrao locale will be requested.
+      # @param options [Hash] Options to customize parsing.
+      # @return [String|HashWithIndifferentAccess] Return the filtered content in the desired locales. If only one locale is required, then a `String` is returned, else a `HashWithIndifferentAccess` with locales as keys.
+      def filter_content(content, locales = [], options = {})
+        body = content.body.ensure_string.strip
+        options = sanitize_options(options)
+        locales = ::Mbrao::Content.validate_locales(locales, content)
+
+        # Split the content
+        result = scan_content(body, options[:content_tags].first, options[:content_tags].last)
+
+        # Now filter results
+        perform_filter_content(result, locales)
+      end
+
+      private
+        # Sanitizes options.
+        #
+        # @param options [Hash] The options to sanitize.
+        # @return [HashWithIndifferentAccess] The sanitized options.
+        def sanitize_options(options)
+          # Tags
+          options[:meta_tags] = sanitize_tags(options[:meta_tags], ["{{metadata}}", "{{/metadata}}"])
+          options[:content_tags] = sanitize_tags(options[:content_tags], ["{{content: %ARGS%}}", "{{/content}}"])
+
+          options
+        end
+
+        # Sanitizes tag markers.
+        #
+        # @param tag [Array|String] The tag to sanitize.
+        # @return [Array] Sanitized tags.
+        def sanitize_tags(tag, default = ["---"])
+          tag = tag.ensure_string.split(/\s*,\s*/).collect(&:strip) if tag && !tag.is_a?(Array)
+          (tag.present? ? tag : default).slice(0, 2).collect {|t| /#{Regexp.quote(t).gsub("%ARGS%", "\\s*(?<args>[^\\n\\}]+,?)*")}/ }
+        end
+
+        # Scans a text and content section.
+        #
+        # @param content [String] The string to scan
+        # @param start_tag [Regexp] The tag to match for starting section.
+        # @param end_tag [Regexp] The tag to match for ending section.
+        def scan_content(content, start_tag, end_tag)
+          rv = []
+          scanner = StringScanner.new(content)
+
+          # Begin scanning the string
+          while !scanner.eos? do
+            if scanner.exist?(start_tag) then # It may start an embedded content
+              # Scan until the start tag, remove the tag from the match and then store to results.
+              rv << [scanner.scan_until(start_tag).partition(start_tag).first, "*"]
+
+              # Keep a reference to the start tag
+              starting = scanner.matched
+
+              # Now try to match the rightmost occurring closing tag
+              embedded = parse_embedded_content(scanner, start_tag, end_tag)
+
+              # Append results
+              rv << get_embedded_content(starting, embedded, start_tag, end_tag)
+            else # Append the rest to the result.
+              rv << [scanner.rest, "*"]
+              scanner.terminate
+            end
+          end
+
+          rv
+        end
+
+        # Gets results for an embedded content.
+        #
+        # @param [String] starting The match starting expression.
+        # @param [String] embedded The embedded contents.
+        # @param start_tag [Regexp] The tag to match for starting section.
+        # @param end_tag [Regexp] The tag to match for ending section.
+        # @return [Array] An array which the first element is the list of valid contents and second is the list of valid locales.
+        def get_embedded_content(starting, embedded, start_tag, end_tag)
+          # Either we have some content or the content was not closed and therefore we ignore this tag.
+          embedded.present? ? [scan_content(embedded, start_tag, end_tag), starting.match(start_tag)["args"]] : [starting, "*"]
+        end
+
+        # Parses embedded content of a tag
+        #
+        # @param scanner [StringScanner] The scanner to use.
+        # @param start_tag [Regexp] The tag to match for starting section.
+        # @param end_tag [Regexp] The tag to match for ending section.
+        # @return [String] The embedded content or `nil`, if the content was never closed.
+        def parse_embedded_content(scanner, start_tag, end_tag)
+          rv = ""
+          balance = 1
+
+          while (embedded_part = scanner.scan_until(end_tag)) do
+            balance += embedded_part.scan(start_tag).count - 1 # -1 Because there is a closure
+            embedded_part = embedded_part.partition(end_tag).first if balance == 0 || !scanner.exist?(end_tag) # This is the last occurrence.
+            rv << embedded_part
+            break if balance == 0
+          end
+
+          rv
+        end
+
+        # Filters content by locale.
+        #
+        # @param content [Array] The content to filter. @see #scan_content.
+        # @param locales [Array] The desired locales. Can include `*` to match all.
+        # @return [String|nil] Return the filtered content or `nil` if the content must be hidden.
+        def perform_filter_content(content, locales)
+          content.collect { |part|
+            part_locales = parse_locales(part[1])
+
+            if locales_valid?(locales, part_locales) then
+              part[0].is_a?(Array) ? perform_filter_content(part[0], locales) : part[0]
+            else
+              nil
+            end
+          }.compact.join("")
+        end
+
+        # Parses locales of a content.
+        #
+        # @param locales [String] The desired locales. Can include `*` to match all. Note that `!*` is ignored.
+        # @return [Hash] An hash with valid and invalid locales.
+        def parse_locales(locales)
+          types = locales.split(/\s*,\s*/).collect(&:strip).group_by {|l| l !~ /^!/ ? "valid" : "invalid" }
+          types["valid"] ||= []
+          types["invalid"] = types.fetch("invalid", []).reject {|l| l == "!*" }.collect {|l| l.gsub(/^!/, "") }
+          types
+        end
+
+        # Checks if all locales in a list are valid for a part.
+        #
+        # @param locales [Array] The desired locales. Can include `*` to match all.
+        # @param part_locales[Hash] An hash with valid and invalid locales.
+        # @return [Boolean] `true` if the locales are valid, `false` otherwise.
+        def locales_valid?(locales, part_locales)
+          locales.include?("*") || part_locales["valid"].include?("*") || ((part_locales["valid"].empty? || (locales & part_locales["valid"]).present?) && (locales & part_locales["invalid"]).blank?)
+        end
+    end
+  end
+end

data/lib/mbrao/rendering_engines/base.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+#
+# This file is part of the mbrao gem. Copyright (C) 2013 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+module Mbrao
+  # Engines used to render contents with metadata.
+  module RenderingEngines
+    # A base class for all renderers.
+    class Base
+      # Renders a content.
+      #
+      # @param content [Content|String] The content to parse.
+      # @param options [Hash] A list of options for renderer.
+      # @param context [Hash] A context for rendering.
+      def render(content, options = {}, context = {})
+        raise Mbrao::Exceptions::Unimplemented.new
+      end
+    end
+  end
+end

data/lib/mbrao/rendering_engines/html_pipeline.rb

@@ -0,0 +1,147 @@
+# encoding: utf-8
+#
+# This file is part of the mbrao gem. Copyright (C) 2013 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+# Main module of the [html-pipeline](https://github.com/jch/html-pipeline) gem.
+module HTML
+  # A [html-pipeline](https://github.com/jch/html-pipeline) gem Pipeline.
+  class Pipeline
+    # A filter to compile Markdown contents.
+    class KramdownFilter < TextFilter
+      # Creates a new filter.
+      #
+      # @param text [String] The string to convert.
+      # @param context [Hash] The context of the conversion.
+      # @param result [Hash] A result hash.
+      def initialize(text, context = nil, result = nil)
+        super(text, context, result)
+        @text = @text.gsub("\r", "")
+      end
+
+      # Converts Markdown to HTML using Kramdown and converts into a DocumentFragment.
+      #
+      # @return [DocumentFragment] The converted fragment.
+      def call
+        Kramdown::Document.new(@text, @context).to_html
+      end
+    end
+  end
+end
+
+module Mbrao
+  # Engines used to render contents with metadata.
+  module RenderingEngines
+    # A renders which use the [html-pipeline](https://github.com/jch/html-pipeline) gem.
+    #
+    # @attribute default_pipeline
+    #   @return [Array] The default pipeline to use. It should be an array of pairs of `Symbol`, which the first element is the filter (in underscored version and without the filter suffix) and the second is a shortcut to disable the pipeline via options. You can also specify a single element to disable shortcuts.
+    # @attribute default_options
+    #   @return [Hash] The default options for the renderer.
+    class HtmlPipeline < Mbrao::RenderingEngines::Base
+      attr_accessor :default_pipeline
+      attr_accessor :default_options
+
+      # Renders a content.
+      #
+      # @param content [Content|String] The content to parse.
+      # @param options [Hash] A list of options for renderer.
+      # @param context [Hash] A context for rendering.
+      def render(content, options = {}, context = {})
+        options = sanitize_options(options)
+        context = context.is_a?(Hash) ? context.symbolize_keys : {}
+
+        begin
+          create_pipeline(options, context).call(get_body(content, options))[:output].to_s
+        rescue Mbrao::Exceptions::UnavailableLocalization => le
+          raise le
+        rescue Exception => e
+          raise ::Mbrao::Exceptions::Rendering.new(e.to_s)
+        end
+      end
+
+      # Gets the default pipeline.
+      #
+      # @return [Array] The default pipeline.
+      def default_pipeline
+        @default_pipeline || [[:kramdown], [:table_of_contents, :toc], [:autolink, :links], [:emoji], [:image_max_width]]
+      end
+
+      # Sets the default pipeline.
+      #
+      # @return [Array] The default pipeline.
+      def default_pipeline=(value)
+        @default_pipeline = value.ensure_array.collect {|v| v.ensure_array.flatten.compact.collect { |p| p.ensure_string.to_sym } }
+      end
+
+      # Gets the default options.
+      #
+      # @return [Hash] The default options.
+      def default_options
+        @default_options || {gfm: true, asset_root: "/"}
+      end
+
+      # Sets the default options.
+      #
+      # @param value [Object] The new default options.
+      def default_options=(value)
+        @default_options = value.is_a?(Hash) ? value : {}
+      end
+
+      private
+        # Sanitizes options.
+        #
+        # @param options [Hash] The options to sanitize.
+        # @return [Hash] The sanitized options.
+        def sanitize_options(options)
+          options = options.is_a?(Hash) ? options.symbolize_keys : {}
+          options = filter_filters(options)
+          options[:pipeline_options] = self.default_options.merge((options[:pipeline_options].is_a?(Hash) ? options[:pipeline_options] : {}).symbolize_keys)
+
+          options
+        end
+
+        # Get body of a content.
+        #
+        # @param content [Content|String] The content to sanitize.
+        # @param options [Hash] A list of options for renderer.
+        # @return [Array] The body to parse.
+        def get_body(content, options)
+          content = ::Mbrao::Content.create(nil, content.ensure_string) if !content.is_a?(::Mbrao::Content)
+          content.get_body(options.fetch(:locale, ::Mbrao::Parser.locale).ensure_string)
+        end
+
+        # Creates the pipeline for rendering.
+        #
+        # @param options [Hash] A list of options for renderer.
+        # @param context [Hash] A context for rendering.
+        # @return [HTML::Pipeline] The pipeline
+        def create_pipeline(options, context)
+          ::HTML::Pipeline.new(options[:pipeline].collect {|f| ::Mbrao::Parser.find_class(f, "::HTML::Pipeline::%CLASS%Filter", true) }, options[:pipeline_options].merge(context))
+        end
+
+        # Filters pipeline filters basing on the options provided.
+        #
+        # @param options [Hash] The original options.
+        # @return [Hash] The options with the new set of filters.
+        def filter_filters(options)
+          options[:pipeline] = get_pipeline(options)
+
+          self.default_pipeline.each do |f|
+            options[:pipeline].delete(f.first) if !options.fetch(f.last, true)
+          end
+
+          options
+        end
+
+        # Gets the pipeline for the current options.
+        #
+        # @param options [Hash] The options to parse.
+        # @return [Array] The pipeline to process.
+        def get_pipeline(options)
+          options.fetch(:pipeline, self.default_pipeline.collect(&:first)).collect(&:to_sym)
+        end
+    end
+  end
+end

data/lib/mbrao/version.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+#
+# This file is part of the mbrao gem. Copyright (C) 2013 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+# A content parser and renderer with embedded metadata support.
+module Mbrao
+  # The current version of mbrao, according to semantic versioning.
+  #
+  # @see http://semver.org
+  module Version
+    # The major version.
+    MAJOR = 1
+
+    # The minor version.
+    MINOR = 0
+
+    # The patch version.
+    PATCH = 0
+
+    # The current version of mbrao.
+    STRING = [MAJOR, MINOR, PATCH].compact.join(".")
+  end
+end

data/lib/mbrao.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+#
+# This file is part of the mbrao gem. Copyright (C) 2013 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+require "lazier"
+require "html/pipeline"
+require "slim"
+require "kramdown"
+require "yaml"
+
+require "mbrao/version" if !defined?(Mbrao::Version)
+require "mbrao/exceptions"
+require "mbrao/content"
+require "mbrao/author"
+require "mbrao/parser"
+require "mbrao/parsing_engines/base"
+require "mbrao/parsing_engines/plain_text"
+require "mbrao/rendering_engines/base"
+require "mbrao/rendering_engines/html_pipeline"
+require "mbrao/integrations/rails" if defined?(ActionView)
+
+Lazier.load!(:object)

data/mbrao.gemspec

@@ -0,0 +1,31 @@
+# encoding: utf-8
+#
+# This file is part of the mbrao gem. Copyright (C) 2013 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+require File.expand_path('../lib/mbrao/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name = "mbrao"
+  gem.version = Mbrao::Version::STRING
+  gem.homepage = "http://github.com/ShogunPanda/mbrao"
+  gem.summary = "A content parser and renderer with embedded metadata support."
+  gem.description = "A content parser and renderer with embedded metadata support."
+  gem.rubyforge_project = "mbrao"
+
+  gem.authors = ["Shogun"]
+  gem.email = ["shogun_panda@me.com"]
+
+  gem.files = `git ls-files`.split($\)
+  gem.executables = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.required_ruby_version = ">= 1.9.3"
+
+  gem.add_dependency("lazier", "~> 2.7.0")
+  gem.add_dependency("html-pipeline", "~> 0.0.8")
+  gem.add_dependency("slim", "~> 1.3.6")
+  gem.add_dependency("kramdown", "~> 0.14.2")
+end

data/spec/coverage_helper.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+#
+# This file is part of the mbrao gem. Copyright (C) 2013 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+require "pathname"
+require "simplecov"  
+
+SimpleCov.start do
+  root = Pathname.new(File.dirname(__FILE__)) + ".."
+
+  add_filter do |src_file|
+    path = Pathname.new(src_file.filename).relative_path_from(root).to_s
+    path !~ /^(lib)/
+  end
+end

data/spec/mbrao/author_spec.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+#
+# This file is part of the mbrao gem. Copyright (C) 2013 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+
+require "spec_helper"
+
+describe Mbrao::Author do
+  describe ".create" do
+    it "creates a author from a non-hash" do
+      Mbrao::Author.should_receive(:new).with("NAME")
+      Mbrao::Author.create("NAME")
+
+      Mbrao::Author.should_receive(:new).with(nil)
+      Mbrao::Author.create(nil)
+
+      Mbrao::Author.should_receive(:new).with([])
+      Mbrao::Author.create([])
+
+      Mbrao::Author.should_receive(:new).with(["NAME"])
+      Mbrao::Author.create(["NAME"])
+    end
+
+    it "creates a author from a hash" do
+      Mbrao::Author.should_receive(:new).with("NAME", "EMAIL", "WEBSITE", "IMAGE", {"other" => "OTHER"}, "UID")
+      Mbrao::Author.create({name: "NAME", email: "EMAIL", website: "WEBSITE", image: "IMAGE", other: "OTHER", uid: "UID"})
+    end
+  end
+
+  describe "#initialize" do
+    it "create a new object" do
+      reference = Mbrao::Author.new("NAME", "name@example.com", "http://example.com", "http://example.com/image.jpg", {a: {b: :c}})
+      expect(reference.name).to eq("NAME")
+      expect(reference.email).to eq("name@example.com")
+      expect(reference.website).to eq("http://example.com")
+      expect(reference.image).to eq("http://example.com/image.jpg")
+      expect(reference.metadata).to eq({"a" => {"b" => :c}})
+    end
+
+    it "make sure that email is valid" do
+      reference = Mbrao::Author.new("NAME", "INVALID", "http://example.com", "http://example.com/image.jpg", {a: {b: :c}})
+      expect(reference.email).to be_nil
+    end
+
+    it "make sure that website is a valid URL" do
+      reference = Mbrao::Author.new("NAME", "name@example.com", "INVALID", "http://example.com/image.jpg", {a: {b: :c}})
+      expect(reference.website).to be_nil
+    end
+
+    it "make sure that image is a valid URL" do
+      reference = Mbrao::Author.new("NAME", "name@example.com", "http://example.com", "INVALID", {a: {b: :c}})
+      expect(reference.image).to be_nil
+    end
+
+    it "make sure that hash is a recursively a HashWithIndifferentAccess" do
+      reference = Mbrao::Author.new("NAME", "name@example.com", "http://example.com", "http://example.com/image.jpg", {a: {b: :c}})
+      expect(reference.metadata).to be_a(HashWithIndifferentAccess)
+      expect(reference.metadata["a"]).to be_a(HashWithIndifferentAccess)
+    end
+  end
+end