mbrao 1.4.4 → 1.5.0

data/lib/mbrao/parser_interface.rb

@@ -0,0 +1,143 @@
+# encoding: utf-8
+#
+# This file is part of the mbrao gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# 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
+  # Methods to allow class level access.
+  module ParserInterface
+    extend ActiveSupport::Concern
+
+    # Class methods.
+    #
+    # @attribute locale
+    #   @return [String] The mbrao default locale.
+    # @attribute parsing_engine
+    #   @return [String] The default parsing engine.
+    # @attribute rendering_engine
+    #   @return [String] The default rendering engine.
+    module ClassMethods
+      attr_accessor :locale
+      attr_accessor :parsing_engine
+      attr_accessor :rendering_engine
+
+      # Gets the default locale for mbrao.
+      #
+      # @return [String] The default locale.
+      def locale
+        attribute_or_default(@locale, "en")
+      end
+
+      # Gets the default parsing engine.
+      #
+      # @return [String] The default parsing engine.
+      def parsing_engine
+        attribute_or_default(@parsing_engine, :plain_text, :to_sym)
+      end
+
+      # Gets the default rendering engine.
+      #
+      # @return [String] The default rendering engine.
+      def rendering_engine
+        attribute_or_default(@rendering_engine, :html_pipeline, :to_sym)
+      end
+
+      # Parses a source text.
+      #
+      # @param content [Object] The content to parse.
+      # @param options [Hash] A list of options for parsing.
+      # @return [Content] The parsed data.
+      def parse(content, options = {})
+        instance.parse(content, options)
+      end
+
+      # Renders a content.
+      #
+      # @param content [Content] The content to parse.
+      # @param options [Hash] A list of options for renderer.
+      # @param context [Hash] A context for rendering.
+      # @return [String] The rendered content.
+      def render(content, options = {}, context = {})
+        instance.render(content, options, context)
+      end
+
+      # Returns an object as a JSON compatible hash
+      #
+      # @param target [Object] The target to serialize.
+      # @param keys [Array] The attributes to include in the serialization.
+      # @param options [Hash] Options to modify behavior of the serialization.
+      #   The only supported value are:
+      #
+      #   * `:exclude`, an array of attributes to skip.
+      #   * `:exclude_empty`, if to exclude nil values. Default is `false`.
+      # @return [Hash] An hash with all attributes.
+      def as_json(target, keys, options = {})
+        include_empty = !options[:exclude_empty].to_boolean
+        exclude = options[:exclude].ensure_array(nil, true, true, true, :ensure_string)
+        keys = keys.ensure_array(nil, true, true, true, :ensure_string)
+
+        map_to_json(target, (keys - exclude), include_empty)
+      end
+
+      # Instantiates a new engine for rendering or parsing.
+      #
+      # @param cls [String|Symbol|Object] If a `String` or a `Symbol`, then it will be the class of the engine.
+      # @param type [Symbol] The type or engine. Can be `:parsing` or `:rendering`.
+      # @return [Object] A new engine.
+      def create_engine(cls, type = :parsing)
+        type = :parsing if type != :rendering
+        ::Lazier.find_class(cls, "::Mbrao::#{type.to_s.classify}Engines::%CLASS%").new
+      rescue NameError
+        raise Mbrao::Exceptions::UnknownEngine
+      end
+
+      # Returns a unique (singleton) instance of the parser.
+      #
+      # @param force [Boolean] If to force recreation of the instance.
+      # @return [Parser] The unique (singleton) instance of the parser.
+      def instance(force = false)
+        @instance = nil if force
+        @instance ||= Mbrao::Parser.new
+      end
+
+      private
+
+      # Returns an attribute or a default value.
+      #
+      # @param attr [Object ]The attribute to return.
+      # @param default_value [Object] The value to return if `attr` is blank.
+      # @param sanitizer [Symbol] An optional method to sanitize the returned value.
+      def attribute_or_default(attr, default_value = nil, sanitizer = :ensure_string)
+        rv = attr.present? ? attr : default_value
+        rv = rv.send(sanitizer) if sanitizer
+        rv
+      end
+
+      # Perform the mapping to JSON.
+      #
+      # @param target [Object] The target to serialize.
+      # @param keys [Array] The attributes to include in the serialization.
+      # @param include_empty [Boolean], if to include nil values.
+      # @return [Hash] An hash with all attributes.
+      def map_to_json(target, keys, include_empty)
+        keys.reduce({}) { |rv, key|
+          value = get_json_field(target, key)
+          rv[key] = value if include_empty || value.present?
+          rv
+        }.deep_stringify_keys
+      end
+
+      # Get a field as JSON.
+      #
+      # @param target [Object] The object containing the value.
+      # @param method [Symbol] The method containing the value.
+      def get_json_field(target, method)
+        value = target.send(method)
+        value = value.as_json if value && value.respond_to?(:as_json) && !value.is_a?(Symbol)
+        value
+      end
+    end
+  end
+end

data/lib/mbrao/parser_validations.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+#
+# This file is part of the mbrao gem. Copyright (C) 2013 and above Shogun <shogun@cowtech.it>.
+# 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
+  # Methods to perform validations.
+  module ParserValidations
+    extend ActiveSupport::Concern
+
+    # Class methods.
+    module ClassMethods
+      # Checks if the text is a valid email.
+      #
+      # @param text [String] The text to check.
+      # @return [Boolean] `true` if the string is valid email, `false` otherwise.
+      def email?(text)
+        /^([a-z0-9_\.\-\+]+)@([\da-z\.\-]+)\.([a-z\.]{2,6})$/i.match(text.ensure_string.strip)
+      end
+
+      # Checks if the text is a valid URL.
+      #
+      # @param text [String] The text to check.
+      # @return [Boolean] `true` if the string is valid URL, `false` otherwise.
+      def url?(text)
+        %r{
+          ^(
+            ([a-z0-9\-]+:\/\/) #PROTOCOL
+            (([\w-]+\.)?) # LOWEST TLD
+            ([\w-]+) # 2nd LEVEL TLD
+            (\.[a-z]+) # TOP TLD
+            ((:\d+)?) # PORT
+            ([\S|\?]*) # PATH, QUERYSTRING AND FRAGMENT
+          )$
+        }ix.match(text.ensure_string.strip)
+      end
+    end
+  end
+end

data/lib/mbrao/parsing_engines/base.rb

@@ -15,7 +15,7 @@ module Mbrao
       # @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
+        raise Mbrao::Exceptions::Unimplemented
       end
 
       # Parses metadata part and returns all valid metadata.
@@ -24,7 +24,7 @@ module Mbrao
       # @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
+        raise Mbrao::Exceptions::Unimplemented
       end
 
       # Filters content of a post by locale.
@@ -35,7 +35,7 @@ module Mbrao
       # @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
+        raise Mbrao::Exceptions::Unimplemented
       end
 
       # Parses a content and return a {Content Content} object.
@@ -49,4 +49,4 @@ module Mbrao
       end
     end
   end
-end
+end

data/lib/mbrao/parsing_engines/plain_text.rb

@@ -17,10 +17,10 @@ module Mbrao
       def separate_components(content, options = {})
         metadata, content, scanner, start_tag, end_tag = prepare_for_separation(content, options)
 
-        if scanner.scan_until(start_tag) then
+        if scanner.scan_until(start_tag)
           metadata = scanner.scan_until(end_tag)
 
-          if metadata then
+          if metadata
             metadata = metadata.partition(end_tag).first
             content = scanner.rest.strip
           end
@@ -35,10 +35,15 @@ module Mbrao
       # @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))
+        rv = YAML.load(content)
+        rv ||= {}
+        raise ArgumentError unless rv.is_a?(Hash)
+        rv
+      rescue => e
+        if options[:default]
+          options[:default]
+        else
+          raise ::Mbrao::Exceptions::InvalidMetadata, e.to_s
         end
       end
 
@@ -62,132 +67,142 @@ module Mbrao
       end
 
       private
-        # Prepare arguments for separation.
-        #
-        # @param content [String] The content to separate.
-        # @param options [Hash] The options to sanitize.
-        # @return [Array] The sanitized arguments.
-        def prepare_for_separation(content, options)
-          content = content.ensure_string.strip
-          meta_tags = sanitize_tags(options[:meta_tags], ["{{metadata}}", "{{/metadata}}"])
-
-          [nil, content.ensure_string.strip, StringScanner.new(content), meta_tags.first, meta_tags.last]
-        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*/).map(&:strip) if tag && !tag.is_a?(Array)
-          (tag.present? ? tag : default).slice(0, 2).map {|t| /#{Regexp.quote(t).gsub("%ARGS%", "\\s*(?<args>[^\\n\\}]+,?)*")}/ }
-        end
+      # Prepare arguments for separation.
+      #
+      # @param content [String] The content to separate.
+      # @param options [Hash] The options to sanitize.
+      # @return [Array] The sanitized arguments.
+      def prepare_for_separation(content, options)
+        content = content.ensure_string.strip
+        meta_tags = sanitize_tags(options[:meta_tags], ["{{metadata}}", "{{/metadata}}"])
+
+        [nil, content.ensure_string.strip, StringScanner.new(content), meta_tags.first, meta_tags.last]
+      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
+      # 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*/).map(&:strip) if tag && !tag.is_a?(Array)
+        (tag.present? ? tag : default).slice(0, 2).map { |t| /#{Regexp.quote(t).gsub("%ARGS%", "\\s*(?<args>[^\\n\\}]+,?)*")}/ }
+      end
 
-          rv
-        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.
+      # @return [String] The result of the scan.
+      def scan_content(content, start_tag, end_tag)
+        rv = []
+        scanner = StringScanner.new(content)
+
+        # Begin scanning the string
+        perform_scan(rv, scanner, start_tag, end_tag) until scanner.eos?
+
+        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, "*"]
+      # Perform a scan on the text and content.
+      #
+      # @param rv [String] The string where to put the results.
+      # @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.
+      def perform_scan(rv, scanner, start_tag, end_tag)
+        if scanner.exist?(start_tag) # 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 and then append results
+          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
 
-        # 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
-          embedded_part = scanner.scan_until(end_tag)
-
-          while balance > 0 && embedded_part 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
-            embedded_part = scanner.scan_until(end_tag) if balance > 0
-          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
 
-          rv
+      # 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
+        embedded_part = scanner.scan_until(end_tag)
+
+        while balance > 0 && embedded_part
+          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
+          embedded_part = scanner.scan_until(end_tag) if balance > 0
         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.map { |part|
-            part_content = part[0]
-            part_locales = parse_locales(part[1])
-
-            if locales_valid?(locales, part_locales) then
-              part_content.is_a?(Array) ? perform_filter_content(part_content, locales) : part_content
-            else
-              nil
-            end
-          }.compact.join("")
-        end
+        rv
+      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*/).map(&:strip).group_by {|l| l !~ /^!/ ? "valid" : "invalid" }
-          types["valid"] ||= []
-          types["invalid"] = types.fetch("invalid", []).reject {|l| l == "!*" }.map {|l| l.gsub(/^!/, "") }
-          types
-        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.map { |part|
+          part_content = part[0]
+          part_locales = parse_locales(part[1])
+
+          if locales_valid?(locales, part_locales)
+            part_content.is_a?(Array) ? perform_filter_content(part_content, locales) : part_content
+          else
+            nil
+          end
+        }.compact.join("")
+      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)
-          valid = part_locales["valid"]
-          invalid = part_locales["invalid"]
+      # 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*/).map(&:strip).group_by { |l| l !~ /^!/ ? "valid" : "invalid" }
+        types["valid"] ||= []
+        types["invalid"] = types.fetch("invalid", []).reject { |l| l == "!*" }.map { |l| l.gsub(/^!/, "") }
+        types
+      end
 
-          locales.include?("*") || valid.include?("*") || ((valid.empty? || (locales & valid).present?) && (locales & invalid).blank?)
-        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)
+        valid = part_locales["valid"]
+        invalid = part_locales["invalid"]
+
+        locales.include?("*") || valid.include?("*") || ((valid.empty? || (locales & valid).present?) && (locales & invalid).blank?)
+      end
     end
   end
-end
+end