occi-core 4.3.6 → 5.0.0.alpha.1

data/lib/occi/core/renderers/text/category.rb

@@ -0,0 +1,183 @@
+require 'occi/core/renderers/text/base'
+
+module Occi
+  module Core
+    module Renderers
+      module Text
+        # Implements routines required to render `Occi::Core::Category` and
+        # its subclasses to a text-based representation. Supports rendering
+        # to plain and header-like formats. Internally, the rendering itself
+        # is done via ERB templates.
+        #
+        # @author Boris Parak <parak@cesnet.cz>
+        class Category < Base
+          # Category key constants
+          CATEGORY_KEY_PLAIN = 'Category'.freeze
+          CATEGORY_KEY_HEADERS = 'X-OCCI-Category'.freeze
+
+          # Renders `object` into plain text and returns the result
+          # as `String`.
+          #
+          # @return [String] textual representation of Object
+          def render_plain
+            obj_data = object_data
+            "#{CATEGORY_KEY_PLAIN}: #{erb_render(obj_data)}"
+          end
+
+          # Renders `object` into text for headers and returns the result
+          # as `Hash`.
+          #
+          # @return [Hash] textual representation of Object for headers
+          def render_headers
+            obj_data = object_data
+            { CATEGORY_KEY_HEADERS => [erb_render(obj_data)] }
+          end
+
+          # Returns keyword used to prefix all categories rendered to plain text.
+          #
+          # @return [String] category keyword
+          def category_key_plain
+            CATEGORY_KEY_PLAIN
+          end
+
+          # Returns word used to key all categories rendered to headers.
+          #
+          # @return [String] category key
+          def category_key_headers
+            CATEGORY_KEY_HEADERS
+          end
+
+          class << self
+            # Returns keyword used to prefix all categories rendered to plain text.
+            #
+            # @return [String] category keyword
+            def category_key_plain
+              CATEGORY_KEY_PLAIN
+            end
+
+            # Returns word used to key all categories rendered to headers.
+            #
+            # @return [String] category key
+            def category_key_headers
+              CATEGORY_KEY_HEADERS
+            end
+          end
+
+          private
+
+          # :nodoc:
+          def short?
+            options[:type] == 'short'
+          end
+
+          # :nodoc:
+          def long?
+            !short?
+          end
+
+          # :nodoc:
+          def object_data
+            {
+              term: object.term, schema: object.schema,
+              subclass: prepare_subclass, title: object.title,
+              rel: prepare_parent, location: prepare_location,
+              attributes: prepare_attributes, actions: prepare_actions
+            }
+          end
+
+          # :nodoc:
+          def prepare_parent
+            cand = if object.respond_to?(:directly_related)
+                     prepare_kind_rel
+                   elsif object.respond_to?(:depends) && object.respond_to?(:applies)
+                     prepare_mixin_rel.to_a
+                   end
+            cand.compact! if cand
+
+            cand.blank? ? nil : cand.collect(&:identifier).join(' ')
+          end
+
+          # :nodoc:
+          def prepare_kind_rel
+            [object.directly_related.first]
+          end
+
+          # :nodoc:
+          def prepare_mixin_rel
+            return Set.new if object.depends.blank?
+            object.depends + object.applies
+          end
+
+          # :nodoc:
+          def prepare_subclass
+            kancest = object.class.ancestors
+
+            if kancest.include? Occi::Core::Action
+              'action'
+            elsif kancest.include? Occi::Core::Mixin
+              'mixin'
+            elsif kancest.include? Occi::Core::Kind
+              'kind'
+            else
+              raise Occi::Core::Errors::RenderingError,
+                    "Could not find known parent for #{object.inspect}"
+            end
+          end
+
+          # :nodoc:
+          def prepare_location
+            object.respond_to?(:location) ? object.location : nil
+          end
+
+          # :nodoc:
+          def prepare_attributes
+            return unless object.respond_to?(:attributes)
+            attrs = object.attributes.collect do |key, attr_def|
+              key + prepare_attribute_def(attr_def)
+            end
+
+            attrs.empty? ? nil : attrs.join(' ')
+          end
+
+          # :nodoc:
+          def prepare_attribute_def(attr_def)
+            return '' unless attr_def.required? || attr_def.immutable?
+            defs = []
+            defs << 'required' if attr_def.required?
+            defs << 'immutable' if attr_def.immutable?
+            "{#{defs.join(' ')}}"
+          end
+
+          # :nodoc:
+          def prepare_actions
+            return unless object.respond_to?(:actions)
+            acts = object.actions.collect(&:identifier)
+            acts.empty? ? nil : acts.join(' ')
+          end
+
+          # :nodoc:
+          def erb_render(obj_data)
+            ERB.new(self.class.template, render_safe).result(binding)
+          end
+
+          class << self
+            # Returns a static ERB template used to render `Category`-like
+            # instances to plain text.
+            #
+            # @return [String] ERB template
+            def template
+              '<%= obj_data[:term] %>; ' \
+              'scheme="<%= obj_data[:schema] %>"; ' \
+              'class="<%= obj_data[:subclass] %>"' \
+              '<% if long? && obj_data[:title] %>; title="<%= obj_data[:title] %>"<% end %>' \
+              '<% if long? && obj_data[:rel] %>; rel="<%= obj_data[:rel] %>"<% end %>' \
+              '<% if long? && obj_data[:location] %>; location="<%= obj_data[:location] %>"<% end %>' \
+              '<% if long? && obj_data[:attributes] %>; attributes="<%= obj_data[:attributes] %>"<% end %>' \
+              '<% if long? && obj_data[:actions] %>; actions="<%= obj_data[:actions] %>"<% end %>'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/occi/core/renderers/text/collection.rb

@@ -0,0 +1,65 @@
+require 'occi/core/renderers/text/model'
+
+module Occi
+  module Core
+    module Renderers
+      module Text
+        # Implements methods needed to render collection instances to text-based
+        # renderings. This class (its instances) is usually called directly from
+        # the "outside". It utilizes `Model` from this module to render kinds,
+        # actions, and mixins. As well as `Resource`, `Link`, and `ActionInstance`.
+        #
+        # @author Boris Parak <parak@cesnet.cz>
+        class Collection < Model
+          # Renders `object` into plain text and returns the result
+          # as `String`.
+          #
+          # @return [String] textual representation of Object
+          def render_plain
+            return '' if object.empty?
+            return super if object.only_categories?
+
+            if object.only_entities?
+              prepare_instances 'entities'
+            elsif object.only_action_instances?
+              prepare_instances 'action_instances'
+            else
+              raise Occi::Core::Errors::RenderingError,
+                    'Cannot render mixed collection to plain text'
+            end
+          end
+
+          # Renders `object` into text for headers and returns the result
+          # as `Hash`.
+          #
+          # @return [Hash] textual representation of Object for headers
+          def render_headers
+            return {} if object.empty?
+            return super if object.only_categories?
+
+            if object.only_entities?
+              prepare_instances 'entities'
+            elsif object.only_action_instances?
+              prepare_instances 'action_instances'
+            else
+              raise Occi::Core::Errors::RenderingError,
+                    'Cannot render mixed collection to text headers'
+            end
+          end
+
+          private
+
+          # :nodoc:
+          def prepare_instances(type)
+            if object.send(type).count > 1
+              raise Occi::Core::Errors::RenderingError,
+                    "Cannot render collection with multiple #{type.tr('_', ' ')} to text"
+            end
+
+            Occi::Core::Renderers::TextRenderer.render object.send(type).first, options
+          end
+        end
+      end
+    end
+  end
+end

data/lib/occi/core/renderers/text/instance.rb

@@ -0,0 +1,44 @@
+require 'occi/core/renderers/text/category'
+require 'occi/core/renderers/text/attributes'
+
+module Occi
+  module Core
+    module Renderers
+      module Text
+        # Implements methods needed to render multiple instance types to text-based
+        # renderings.
+        #
+        # @author Boris Parak <parak@cesnet.cz>
+        module Instance
+          # :nodoc:
+          def instance_attributes
+            Attributes.new(
+              object.attributes, options
+            ).render
+          end
+
+          # :nodoc:
+          def short_category(category)
+            Category.new(
+              category, options.merge(type: 'short')
+            ).render
+          end
+
+          # :nodoc:
+          def short_mixins_plain
+            object.mixins.collect { |mxn| short_category(mxn) }
+          end
+
+          # :nodoc:
+          def short_mixins_headers
+            object.mixins.collect do |mxn|
+              short_category(mxn)[Category.category_key_headers]
+            end.flatten
+          end
+
+          protected :instance_attributes, :short_category, :short_mixins_plain, :short_mixins_headers
+        end
+      end
+    end
+  end
+end

data/lib/occi/core/renderers/text/link.rb

@@ -0,0 +1,40 @@
+require 'occi/core/renderers/text/base'
+require 'occi/core/renderers/text/instance'
+
+module Occi
+  module Core
+    module Renderers
+      module Text
+        # Implements methods needed to render link instances to text-based
+        # renderings. This class (its instances) is usually called directly from
+        # the "outside". It utilizes `Category` and `Attributes` from this module
+        # to render kind, mixins, and instance attributes.
+        #
+        # @author Boris Parak <parak@cesnet.cz>
+        class Link < Base
+          include Instance
+
+          # Renders `object` into plain text and returns the result
+          # as `String`.
+          #
+          # @return [String] textual representation of Object
+          def render_plain
+            [short_category(object.kind), short_mixins_plain, instance_attributes].flatten.join("\n")
+          end
+
+          # Renders `object` into text for headers and returns the result
+          # as `Hash`.
+          #
+          # @return [Hash] textual representation of Object for headers
+          def render_headers
+            headers = short_category(object.kind)
+            headers[Category.category_key_headers].concat(
+              short_mixins_headers
+            )
+            headers.merge(instance_attributes)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/occi/core/renderers/text/model.rb

@@ -0,0 +1,41 @@
+require 'occi/core/renderers/text/base'
+require 'occi/core/renderers/text/category'
+
+module Occi
+  module Core
+    module Renderers
+      module Text
+        # Implements methods needed to render model instances to text-based
+        # renderings. This class (its instances) is usually called directly from
+        # the "outside". It utilizes `Category` from this module to render kinds,
+        # actions, and mixins.
+        #
+        # @author Boris Parak <parak@cesnet.cz>
+        class Model < Base
+          # Renders `object` into plain text and returns the result
+          # as `String`.
+          #
+          # @return [String] textual representation of Object
+          def render_plain
+            rcats = object.categories.collect { |cat| Category.new(cat, options).render }
+            rcats.join("\n")
+          end
+
+          # Renders `object` into text for headers and returns the result
+          # as `Hash`.
+          #
+          # @return [Hash] textual representation of Object for headers
+          def render_headers
+            rcats = { Category.category_key_headers => [] }
+            object.categories.each do |cat|
+              rcats[Category.category_key_headers].concat(
+                Category.new(cat, options).render[Category.category_key_headers]
+              )
+            end
+            rcats
+          end
+        end
+      end
+    end
+  end
+end

data/lib/occi/core/renderers/text/resource.rb

@@ -0,0 +1,109 @@
+require 'occi/core/renderers/text/base'
+require 'occi/core/renderers/text/instance'
+
+module Occi
+  module Core
+    module Renderers
+      module Text
+        # Implements methods needed to render resource instances to text-based
+        # renderings. This class (its instances) is usually called directly from
+        # the "outside". It utilizes `Category` and `Attributes` from this module
+        # to render kind, mixins, and instance attributes.
+        #
+        # @author Boris Parak <parak@cesnet.cz>
+        class Resource < Base
+          include Instance
+
+          # Link key constant
+          LINK_KEY = 'Link'.freeze
+          LINK_KEY_HEADERS = 'X-OCCI-Link'.freeze
+
+          # Renders `object` into plain text and returns the result
+          # as `String`.
+          #
+          # @return [String] textual representation of Object
+          def render_plain
+            [
+              short_category(object.kind), short_mixins_plain, instance_attributes,
+              instance_links, instance_actions
+            ].flatten.join("\n")
+          end
+
+          # Renders `object` into text for headers and returns the result
+          # as `Hash`.
+          #
+          # @return [Hash] textual representation of Object for headers
+          def render_headers
+            headers = short_category(object.kind)
+            headers[Category.category_key_headers].concat(
+              short_mixins_headers
+            )
+            headers.merge!(instance_attributes)
+            headers.merge!(header_links)
+
+            headers
+          end
+
+          protected
+
+          # :nodoc:
+          def header_links
+            { LINK_KEY_HEADERS => instance_links(false).concat(instance_actions(false)) }
+          end
+
+          # :nodoc:
+          def instance_links(plain = true)
+            links = object.links.collect { |link| instance_link(link) }
+            plain ? links.map { |link| "#{LINK_KEY}: #{link}" } : links
+          end
+
+          # :nodoc:
+          def instance_link(link)
+            link_categories = instance_link_categories(link)
+            link_attributes = instance_link_attributes(link)
+
+            ERB.new(self.class.link_template, render_safe).result(binding)
+          end
+
+          # :nodoc:
+          def instance_link_categories(link)
+            [link.kind.identifier, *link.mixins.collect(&:identifier)].join(' ')
+          end
+
+          # :nodoc:
+          def instance_link_attributes(link)
+            attr_hash = Attributes.new(link.attributes, format: 'headers').render
+            attr_hash.values.flatten.join('; ')
+          end
+
+          # :nodoc:
+          def instance_actions(plain = true)
+            actions = object.actions.collect { |action| instance_action(action) }
+            plain ? actions.map { |action| "#{LINK_KEY}: #{action}" } : actions
+          end
+
+          # :nodoc:
+          def instance_action(action)
+            ERB.new(self.class.action_template, render_safe).result(binding)
+          end
+
+          class << self
+            # :nodoc:
+            def action_template
+              '<<%= object.location %>?action=<%= action.term %>>; rel="<%= action %>"'
+            end
+
+            # :nodoc:
+            def link_template
+              '<<%= link.target %>>; ' \
+              'rel="<%= link.rel %>"; ' \
+              'self="<%= link.location %>"; ' \
+              'category="<%= link_categories %>"; ' \
+              '<%= link_attributes %>'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/occi/core/renderers/text_renderer.rb

@@ -0,0 +1,72 @@
+module Occi
+  module Core
+    module Renderers
+      # Contains all text-related classes and modules. This
+      # module houses functionality transforming various internal
+      # instances to a basic text-based rendering. In most
+      # cases, it is not intended to be called explicitly. Its
+      # instrumentation will be used automatically by selected
+      # instances when calling `render` or `to_text`/`to_headers`.
+      #
+      # This is also the place where additional supported instance types
+      # should be added. Please, refer to internal documentation
+      # for details on how to add a new instance type.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      module Text; end
+    end
+  end
+end
+
+# Load class-specific rendering primitives
+Dir[File.join(File.dirname(__FILE__), 'text', '*.rb')].each { |file| require file.gsub('.rb', '') }
+
+module Occi
+  module Core
+    module Renderers
+      # Implementes components necessary to render all required instance types
+      # to `text` or `text`-like format. Currently supported instance types
+      # can be queried via `::known_types`. Actual serialization happens in
+      # type-specific serializer classes which can be found in `Occi::Core::Renderers::Text`.
+      #
+      # @author Boris Parak <parak@cesnet.cz>
+      class TextRenderer < BaseRenderer
+        # Supported formats
+        TEXT_FORMATS = %w[text text_plain text_occi headers].freeze
+
+        class << self
+          # Indicates whether this class is a renderer candidate.
+          #
+          # @return [TrueClass, FalseClass] renderer flag
+          def renderer?
+            true
+          end
+
+          # Returns a list of formats supported by this renderer.
+          # Formats are compliant with method naming restrictions
+          # and String-like.
+          #
+          # @return [Array] list of formats
+          def formats
+            TEXT_FORMATS
+          end
+
+          # Returns a frozen Hash providing mapping information between
+          # supported types and supported serializers.
+          #
+          # @return [Array] list of known type->serializer mappings
+          def known
+            {
+              'Occi::Core::Category'       => Occi::Core::Renderers::Text::Category,
+              'Occi::Core::ActionInstance' => Occi::Core::Renderers::Text::ActionInstance,
+              'Occi::Core::Collection'     => Occi::Core::Renderers::Text::Collection,
+              'Occi::Core::Model'          => Occi::Core::Renderers::Text::Model,
+              'Occi::Core::Resource'       => Occi::Core::Renderers::Text::Resource,
+              'Occi::Core::Link'           => Occi::Core::Renderers::Text::Link
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/occi/core/renderers.rb

@@ -0,0 +1,20 @@
+module Occi
+  module Core
+    # Contains all rendering-related classes and modules. This
+    # module houses functionality transforming various internal
+    # instances to standardized over-the-wire renderings. In most
+    # cases, it is not intended to be called explicitly. Its
+    # instrumentation will be used automatically by selected
+    # instances when calling `render` or `to_<format>`.
+    #
+    # This is also the place where additional rendering formats
+    # should be added. Please, refer to internal documentation
+    # for details on how to add a new rendering format.
+    #
+    # @author Boris Parak <parak@cesnet.cz>
+    module Renderers; end
+  end
+end
+
+require File.join(File.dirname(__FILE__), 'renderers', 'base_renderer')
+Dir[File.join(File.dirname(__FILE__), 'renderers', '*.rb')].each { |file| require file.gsub('.rb', '') }