mbrao 1.4.4 → 1.5.0

data/lib/mbrao/content_interface.rb

@@ -0,0 +1,146 @@
+# 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.
+#
+
+module Mbrao
+  # Miscellaneous {Content Content} class methods.
+  module ContentInterface
+    extend ActiveSupport::Concern
+
+    # The allowed string format for a datetime.
+    ALLOWED_DATETIME_FORMATS = [
+      "%Y%m%dT%H%M%S%z", "%Y%m%dT%H%M%S%Z",
+      "%FT%T.%L%z", "%FT%T.%L%Z",
+      "%FT%T%z", "%FT%T%Z",
+      "%F %T %z", "%F %T %Z",
+      "%F %T.%L %z", "%F %T.%L %Z",
+
+      "%F %T.%L", "%F %T", "%F %H:%M", "%F",
+      "%d/%m/%Y %T.%L", "%d/%m/%Y %T", "%d/%m/%Y %H:%M", "%d/%m/%Y"
+    ]
+
+    # Class methods.
+    module ClassMethods
+      # Validates locales for attribute retrieval.
+      #
+      # @param locales [Array] A list of desired locales for an attribute. Can include `*` to match all. If none are specified, the default mbrao locale will be
+      #   used.
+      # @param content [Content|nil] An optional content to check for availability
+      # @return [Array] The validated list of locales.
+      def validate_locales(locales, content = nil)
+        locales = locales.ensure_array(nil, true, true, true) { |l| l.ensure_string.strip }
+        locales = (locales.empty? ? [Mbrao::Parser.locale] : locales)
+        raise Mbrao::Exceptions::UnavailableLocalization if content && !content.enabled_for_locales?(locales)
+        locales
+      end
+
+      # Creates a content with metadata and body.
+      #
+      # @param metadata [Hash] The metadata.
+      # @param body [String] The body of the content.
+      # @return [Content] A new content.
+      def create(metadata, body)
+        rv = Mbrao::Content.new
+        rv.body = body.ensure_string.strip
+        assign_metadata(rv, metadata.symbolize_keys) if metadata.is_a?(Hash)
+        rv
+      end
+    end
+
+    # Checks if the content is available for at least one of the provided locales.
+    #
+    # @param locales [Array] The desired locales. Can include `*` to match all. If none are specified, the default mbrao locale will be used.
+    # @return [Boolean] `true` if the content is available for at least one of the desired locales, `false` otherwise.
+    def enabled_for_locales?(*locales)
+      locales = locales.flatten.ensure_array(nil, false, false, true) { |l| l.ensure_string.strip }.reject { |l| l == "*" }
+      @locales.blank? || locales.blank? || (@locales & locales).present?
+    end
+
+    # Gets the title of the content in the desired locales.
+    #
+    # @param locales [String|Array] The desired locales. Can include `*` to match all. If none are specified, the default mbrao locale will be used.
+    # @return [String|HashWithIndifferentAccess] Return the title of the content in the desired locales. If only one locale is required, then a `String`
+    #   is returned, else a `HashWithIndifferentAccess` with locales as keys.
+    def get_title(locales = [])
+      filter_attribute_for_locales(@title, locales)
+    end
+
+    # Gets the body returning only the portion which are available for the given locales.
+    #
+    # @param locales [String|Array] The desired locales. Can include `*` to match all. If none are specified, the default mbrao locale will be used.
+    # @param engine [String|Symbol|Object] The engine to use to filter contents.
+    # @return [String|HashWithIndifferentAccess] Return the body of the content in the desired locales. If only one locale is required, then a `String`
+    #   is returned, else a `HashWithIndifferentAccess` with locales as keys.
+    def get_body(locales = [], engine = :plain_text)
+      Mbrao::Parser.create_engine(engine).filter_content(self, locales)
+    end
+
+    # Gets the tags of the content in the desired locales.
+    #
+    # @param locales [String|Array] The desired locales. Can include `*` to match all. If none are specified, the default mbrao locale will be used.
+    # @return [Array|HashWithIndifferentAccess] Return the title of the content in the desired locales. If only one locale is required, then a `Array`
+    #   is returned, else a `HashWithIndifferentAccess` with locales as keys.
+    def get_tags(locales = [])
+      filter_attribute_for_locales(@tags, locales)
+    end
+
+    # Gets the "more link" text of the content in the desired locales.
+    #
+    # @param locales [String|Array] The desired locales. Can include `*` to match all. If none are specified, the default mbrao locale will be used.
+    # @return [String|HashWithIndifferentAccess] Return the label of the "more link" of the content in the desired locales. If only one locale is required,
+    #   then a `String` is returned, else a `HashWithIndifferentAccess` with locales as keys.
+    def get_more(locales = [])
+      filter_attribute_for_locales(@more, locales)
+    end
+
+    # Returns the content as an Hash.
+    #
+    # @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(options = {})
+      keys = [:uid, :locales, :title, :summary, :body, :tags, :more, :author, :created_at, :updated_at, :metadata]
+      ::Mbrao::Parser.as_json(self, keys, options)
+    end
+
+    private
+
+    # Filters an attribute basing a set of locales.
+    #
+    # @param attribute [Object|HashWithIndifferentAccess] The desired attribute.
+    # @param locales [String|Array] The desired locales. Can include `*` to match all. If none are specified, the default mbrao locale will be used.
+    # @return [String|HashWithIndifferentAccess] Return the object for desired locales. If only one locale is available, then only a object is returned,
+    #   else a `HashWithIndifferentAccess` with locales as keys.
+    def filter_attribute_for_locales(attribute, locales)
+      locales = ::Mbrao::Content.validate_locales(locales, self)
+
+      if attribute.is_a?(HashWithIndifferentAccess)
+        rv = attribute.reduce(HashWithIndifferentAccess.new) { |a, e| append_value_for_locale(a, e[0], locales, e[1]) }
+        rv.keys.length == 1 ? rv.values.first : rv
+      else
+        attribute
+      end
+    end
+
+    # Adds an value on a hash if enable for requested locales.
+    #
+    # @param hash [Hash] The hash to handle.
+    # @param locale [String] The list of locale (separated by commas) for which the value is available.
+    # @param locales [Array] The list of locale for which this value is requested. Can include `*` to match all. If none are specified, the default mbrao
+    #   locale will be used.
+    # @param value [Object] The value to add.
+    # @return [Hash] Return the original hash.
+    def append_value_for_locale(hash, locale, locales, value)
+      locale.split(/\s*,\s*/).map(&:strip).each do |l|
+        hash[l] = value if locales.include?("*") || locales.include?(l)
+      end
+
+      hash
+    end
+  end
+end

data/lib/mbrao/exceptions.rb

@@ -35,4 +35,4 @@ module Mbrao
     class Unimplemented < RuntimeError
     end
   end
-end
+end

data/lib/mbrao/integrations/rails.rb

@@ -4,55 +4,61 @@
 # Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
 #
 
-# Generic interface to multiple Ruby template engines.
-module ActionView::Template::Handlers
-  # Class for rendering mbrao contents in Rails.
-  class MbraoTemplate
-    # Returns a unique (singleton) instance of the template handler.
-    #
-    # @param force [Boolean] If to force recreation of the instance.
-    # @return [MbraoTemplate] The unique (singleton) instance of the template handler.
-    def self.instance(force = false)
-      @instance = nil if force
-      @instance ||= ActionView::Template::Handlers::MbraoTemplate.new
-    end
+# :nodoc:
+module ActionView
+  # :nodoc:
+  class Template
+    # :nodoc:
+    module Handlers
+      # Class for rendering mbrao contents in Rails.
+      class MbraoTemplate
+        # Returns a unique (singleton) instance of the template handler.
+        #
+        # @param force [Boolean] If to force recreation of the instance.
+        # @return [MbraoTemplate] The unique (singleton) instance of the template handler.
+        def self.instance(force = false)
+          @instance = nil if force
+          @instance ||= ActionView::Template::Handlers::MbraoTemplate.new
+        end
 
-    # Register Mbrao into Rails.
-    def self.register
-      ActionView::Template.register_template_handler("emt", instance) if defined?(ActionView) && defined?(Rails) && Rails.version =~ /^[34]/
-    end
+        # Register Mbrao into Rails.
+        def self.register
+          ActionView::Template.register_template_handler("emt", instance) if defined?(ActionView) && defined?(Rails) && Rails.version =~ /^[34]/
+        end
 
-    # Renders a template into a renderer context.
-    #
-    # @param renderer [Object] The renderer context.
-    # @param template [String] The template to render.
-    # @return [String] The rendered template.
-    def render(renderer, template)
-      content = ::Mbrao::Parser.parse(template)
-      controller = renderer.controller
+        # Renders a template into a renderer context.
+        #
+        # @param renderer [Object] The renderer context.
+        # @param template [String] The template to render.
+        # @return [String] The rendered template.
+        def render(renderer, template)
+          content = ::Mbrao::Parser.parse(template)
+          controller = renderer.controller
 
-      controller.instance_variable_set(:@mbrao_content, content)
-      controller.define_singleton_method(:mbrao_content) { @mbrao_content }
-      controller.class.send(:helper_method, :mbrao_content)
+          controller.instance_variable_set(:@mbrao_content, content)
+          controller.define_singleton_method(:mbrao_content) { @mbrao_content }
+          controller.class.send(:helper_method, :mbrao_content)
 
-      ::Mbrao::Parser.render(content, {engine: content.metadata[:engine], locale: controller.params[:locale]})
-    end
+          ::Mbrao::Parser.render(content, {engine: content.metadata[:engine], locale: controller.params[:locale]})
+        end
 
-    # Declares support for streaming.
-    #
-    # @return [TrueClass] Declares support for streaming.
-    def supports_streaming?
-      true
-    end
+        # Declares support for streaming.
+        #
+        # @return [TrueClass] Declares support for streaming.
+        def supports_streaming?
+          true
+        end
 
-    # Method called to render a template.
-    #
-    # @param template [ActionView::Template] The template to render.
-    # @return [String] A Ruby snippet to execute to render the template.
-    def call(template)
-      "ActionView::Template::Handlers::MbraoTemplate.instance.render(self, #{template.source.to_json})"
+        # Method called to render a template.
+        #
+        # @param template [ActionView::Template] The template to render.
+        # @return [String] A Ruby snippet to execute to render the template.
+        def call(template)
+          "ActionView::Template::Handlers::MbraoTemplate.instance.render(self, #{template.source.to_json})"
+        end
+      end
     end
   end
 end
 
-ActionView::Template::Handlers::MbraoTemplate.register
+ActionView::Template::Handlers::MbraoTemplate.register

data/lib/mbrao/parser.rb

@@ -6,164 +6,11 @@
 
 # A content parser and renderer with embedded metadata support.
 module Mbrao
-  # Methods to allow class level access.
-  module PublicInterface
-    extend ActiveSupport::Concern
-
-    # Class methods.
-    #
-    # @attribute default_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)
-
-        (keys - exclude).reduce({}) {|rv, key|
-          value = target.send(key)
-          value = value.as_json if value && value.respond_to?(:as_json) && !value.is_a?(Symbol)
-          rv[key] = value if include_empty || value.present?
-          rv
-        }.deep_stringify_keys
-      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)
-        begin
-          type = :parsing if type != :rendering
-          ::Lazier.find_class(cls, "::Mbrao::#{type.to_s.classify}Engines::%CLASS%").new
-        rescue NameError
-          raise Mbrao::Exceptions::UnknownEngine.new
-        end
-      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
-    end
-  end
-
-  # Methods to perform validations.
-  module Validations
-    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 is_email?(text)
-        regex = /^([a-z0-9_\.\-\+]+)@([\da-z\.\-]+)\.([a-z\.]{2,6})$/i
-        text.ensure_string.strip =~ regex
-      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 is_url?(text)
-        regex = /
-          ^(
-            ([a-z0-9\-]+:\/\/) #PROTOCOL
-            (([\w-]+\.)?) # LOWEST TLD
-            ([\w-]+) # 2nd LEVEL TLD
-            (\.[a-z]+) # TOP TLD
-            ((:\d+)?) # PORT
-            ([\S|\?]*) # PATH, QUERYSTRING AND FRAGMENT
-          )$
-        /ix
-
-        text.ensure_string.strip =~ regex
-      end
-    end
-  end
-
   # A parser to handle pipelined content.
   #
   class Parser
-    include Mbrao::PublicInterface
-    include Mbrao::Validations
+    include Mbrao::ParserInterface
+    include Mbrao::ParserValidations
 
     # Parses a source text.
     #
@@ -187,30 +34,31 @@ module Mbrao
     end
 
     private
-      # Sanitizes options for parsing.
-      #
-      # @param options [Hash] The options to sanitize.
-      # @return [HashWithIndifferentAccess] The sanitized options.
-      def sanitize_parsing_options(options)
-        options = options.ensure_hash(:symbols)
 
-        options[:engine] ||= Mbrao::Parser.parsing_engine
-        options[:metadata] = options.fetch(:metadata, true).to_boolean
-        options[:content] = options.fetch(:content, true).to_boolean
+    # Sanitizes options for parsing.
+    #
+    # @param options [Hash] The options to sanitize.
+    # @return [HashWithIndifferentAccess] The sanitized options.
+    def sanitize_parsing_options(options)
+      options = options.ensure_hash(:symbols)
+
+      options[:engine] ||= Mbrao::Parser.parsing_engine
+      options[:metadata] = options.fetch(:metadata, true).to_boolean
+      options[:content] = options.fetch(:content, true).to_boolean
 
-        HashWithIndifferentAccess.new(options)
-      end
+      HashWithIndifferentAccess.new(options)
+    end
 
-      # Sanitizes options for rendering.
-      #
-      # @param options [Hash] The options to sanitize.
-      # @return [HashWithIndifferentAccess] The sanitized options.
-      def sanitize_rendering_options(options)
-        options = options.ensure_hash(:symbols)
+    # Sanitizes options for rendering.
+    #
+    # @param options [Hash] The options to sanitize.
+    # @return [HashWithIndifferentAccess] The sanitized options.
+    def sanitize_rendering_options(options)
+      options = options.ensure_hash(:symbols)
 
-        options[:engine] ||= Mbrao::Parser.rendering_engine
+      options[:engine] ||= Mbrao::Parser.rendering_engine
 
-        HashWithIndifferentAccess.new(options)
-      end
+      HashWithIndifferentAccess.new(options)
+    end
   end
-end
+end