occi-core 4.3.6 → 5.0.0.alpha.1

data/lib/occi/core/attribute_definition.rb

@@ -0,0 +1,269 @@
+module Occi
+  module Core
+    # Contains an attribute definition information.
+    # This definition does not carry the name of the
+    # attribute or its value. These should be associated
+    # with the definition by other means, e.g. in a hash
+    # `{ name: definition }` or by using instances of
+    # the `Occi::Core::Attribute` class.
+    #
+    # @attr type [Class] Ruby class of the desired value
+    # @attr required [TrueClass, FalseClass] required flag
+    # @attr mutable [TrueClass, FalseClass] mutable flag
+    # @attr default [Object] default value, optional
+    # @attr description [String, NilClass] attribute description, optional
+    # @attr pattern [Regexp, NilClass] value pattern, only for type `String`
+    #
+    # @author Boris Parak <parak@cesnet.cz>
+    class AttributeDefinition
+      include Yell::Loggable
+      include Helpers::ArgumentValidator
+      extend Helpers::YamlSummoner
+
+      attr_accessor :type, :required, :mutable,
+                    :default, :description, :pattern
+
+      # Constructs an instance with sensible defaults. The default
+      # definition is for a String-based optional attribute without
+      # a pattern.
+      #
+      # @example
+      #   AttributeDefinition.new type: Integer, required: true
+      #   AttributeDefinition.new
+      #
+      # @param args [Hash] arguments with definition information
+      # @option args [Class] :type (String) class of the desired value
+      # @option args [TrueClass, FalseClass] :required (false) required flag
+      # @option args [TrueClass, FalseClass] :mutable (true) mutable flag
+      # @option args [Object] :default (nil) default value
+      # @option args [String, NilClass] :description (nil) attribute description
+      # @option args [Regexp, NilClass] :pattern (nil) value pattern
+      def initialize(args = {})
+        default_args! args
+
+        @type = args.fetch(:type)
+        @required = args.fetch(:required)
+        @mutable = args.fetch(:mutable)
+        @default = args.fetch(:default)
+        @description = args.fetch(:description)
+        @pattern = args.fetch(:pattern)
+      end
+
+      # Alias with a question mark
+      alias required? required
+      alias mutable? mutable
+
+      # Changes the value of `required` to `true`, in case
+      # `required` is `nil` or `false`.
+      #
+      # @example
+      #   attr_def.required? # => false
+      #   attr_def.required!
+      #   attr_def.required? # => true
+      def required!
+        self.required = true
+      end
+
+      # Shorthand for getting the negated value of `required`.
+      #
+      # @example
+      #   attr_def.required? # => false
+      #   attr_def.optional? # => true
+      #
+      # @return [TrueClass, FalseClass] negated value of `required`
+      def optional?
+        !required?
+      end
+
+      # Changes the value of `required` to `false`, in case
+      # `required` is `nil` or `true`.
+      #
+      # @example
+      #   attr_def.required? # => true
+      #   attr_def.optional!
+      #   attr_def.required? # => false
+      def optional!
+        self.required = false
+      end
+
+      # Changes the value of `mutable` to `true`, in case
+      # `mutable` is `nil` or `false`.
+      #
+      # @example
+      #   attr_def.mutable? # => false
+      #   attr_def.mutable!
+      #   attr_def.mutable? # => true
+      def mutable!
+        self.mutable = true
+      end
+
+      # Shorthand for getting the negated value of `mutable`.
+      #
+      # @example
+      #   attr_def.mutable?   # => true
+      #   attr_def.immutable? # => false
+      #
+      # @return [TrueClass, FalseClass] negated value of `mutable`
+      def immutable?
+        !mutable?
+      end
+
+      # Changes the value of `mutable` to `false`, in case
+      # `mutable` is `nil` or `true`.
+      #
+      # @example
+      #   attr_def.mutable?   # => true
+      #   attr_def.immutable!
+      #   attr_def.mutable?   # => false
+      def immutable!
+        self.mutable = false
+      end
+
+      # Indicates the presence of a default value.
+      #
+      # @example
+      #   attr_def.default  # => nil
+      #   attr_def.default? # => false
+      #
+      # @return [TrueClass, FalseClass] default value indicator
+      def default?
+        !default.nil?
+      end
+
+      # Indicates the presence of a pattern for value.
+      #
+      # @example
+      #   attr_def.pattern  # => /.*/
+      #   attr_def.pattern? # => true
+      #
+      # @return [TrueClass, FalseClass] pattern indicator
+      def pattern?
+        !pattern.nil?
+      end
+
+      # Indicates whether the given value is an acceptable
+      # value for an attribute with this definition.
+      #
+      # @example
+      #   attr_def.type       # => String
+      #   attr_def.value? 5.0 # => false
+      #
+      # @param value [Object] candidate value
+      # @return [TrueClass, FalseClass] validation result
+      def valid?(value)
+        begin
+          valid! value
+        rescue Occi::Core::Errors::AttributeValidationError => ex
+          logger.debug "AttributeValidation: #{ex.message}"
+          return false
+        end
+
+        true
+      end
+
+      # Indicates whether the given value is an acceptable
+      # value for an attribute with this definition. This
+      # method will raise an error if the given value is
+      # not acceptable.
+      #
+      # @example
+      #   attr_def.type       # => String
+      #   attr_def.value! 0.5 # => Occi::Core::Errors::AttributeValidationError
+      #
+      # @param value [Object] candidate value
+      def valid!(value)
+        valid_type!
+        valid_value! value
+      end
+
+      private
+
+      # :nodoc:
+      def valid_type!
+        return if type
+        raise Occi::Core::Errors::AttributeValidationError,
+              'No type has been defined'
+      end
+
+      # :nodoc:
+      def valid_value!(value)
+        if value.nil? && required?
+          raise Occi::Core::Errors::AttributeValidationError,
+                'Value is required but not provided'
+        end
+        return if value.nil? && optional?
+
+        unless value_ancestors(value).include?(type)
+          raise Occi::Core::Errors::AttributeValidationError,
+                "Type #{value.class} is incompatible with " \
+                "defined type #{type}"
+        end
+
+        match_pattern! value
+      end
+
+      # :nodoc:
+      def match_pattern!(value)
+        return unless type_ancestors.include?(String)
+        return unless pattern?
+        return if pattern.match(value)
+
+        raise Occi::Core::Errors::AttributeValidationError,
+              "#{value.inspect} does not match pattern #{pattern.inspect}"
+      end
+
+      # :nodoc:
+      def type_ancestors
+        type.ancestors
+      end
+
+      # :nodoc:
+      def value_ancestors(value)
+        value.class.ancestors
+      end
+
+      # :nodoc:
+      def sufficient_args!(args)
+        sufficient_type! args[:type]
+
+        %i[required mutable].each do |attr|
+          next unless args[attr].nil?
+          raise Occi::Core::Errors::MandatoryArgumentError,
+                "#{attr} is a mandatory argument"
+        end
+      end
+
+      # :nodoc:
+      def sufficient_type!(type)
+        if type.nil?
+          raise Occi::Core::Errors::MandatoryArgumentError,
+                'type is a mandatory argument'
+        end
+
+        return if type.is_a?(Class) || type.is_a?(Module)
+        raise Occi::Core::Errors::MandatoryArgumentError,
+              'type must be a class or module'
+      end
+
+      # :nodoc:
+      def defaults
+        {
+          type: String,
+          required: false,
+          mutable: true,
+          default: nil,
+          description: nil,
+          pattern: nil
+        }
+      end
+
+      class << self
+        # :nodoc:
+        def allowed_yaml_classes
+          [String, Regexp, URI, IPAddr, Integer, Float, Boolean, Array, Hash].freeze
+        end
+        private :allowed_yaml_classes
+      end
+    end
+  end
+end

data/lib/occi/core/category.rb

@@ -1,111 +1,138 @@
 module Occi
   module Core
+    # Implements the base class for all OCCI categories, including
+    # `Kind`, `Action`, and `Mixin`.
+    #
+    # @attr term [String] category term
+    # @attr schema [String] category schema, ending with '#'
+    # @attr title [String] category title
+    # @attr attributes [Hash] category attributes
+    #
+    # @attr_reader identifier [String] full identifier constructed from term and schema
+    #
+    # @abstract The base class itself is not renderable and should be
+    #           used as an abstract starting point.
+    # @author Boris Parak <parak@cesnet.cz>
     class Category
-
-      include Occi::Helpers::Inspect
-      include Occi::Helpers::Comparators::Category
-
-      attr_accessor :scheme, :term, :title, :attributes, :model
-
-      # @param scheme [String] The categorisation scheme.
-      # @param term [String] Unique identifier of the Category instance within the categorisation scheme.
-      # @param title [String] The display name of an instance.
-      # @param attributes [Occi::Core::Attributes,Hash] Set of Attribute instances.
-      def initialize(scheme='http://schemas.ogf.org/occi/core#',
-          term='category',
-          title=nil,
-          attributes=nil)
-        raise ArgumentError, 'Scheme and term cannot be empty' if scheme.blank? || term.blank?
-        attributes ||= Occi::Core::Attributes.new
-
-        scheme << '#' unless scheme.end_with? '#'
-        @scheme = scheme
-        @term = term
-        @title = title
-
-        case attributes
-          when Occi::Core::Attributes
-            @attributes = Occi::Core::Attributes.new(attributes)
-          else
-            @attributes = Occi::Core::Attributes.parse_properties attributes
-        end
+      include Yell::Loggable
+      include Helpers::Renderable
+      extend Helpers::IdentifierValidator
+      include Helpers::AttributesAccessor
+      include Helpers::ArgumentValidator
+      extend Helpers::YamlSummoner
+
+      attr_accessor :term, :schema, :title, :attributes
+
+      # Constructs an instance with the given category information.
+      # Both `term` and `schema` are mandatory arguments. `schema` must
+      # be terminated with '#'.
+      #
+      # @example
+      #   Category.new term: 'gnr', schema: 'http://example.org/test#'
+      #
+      # @param args [Hash] arguments with category information
+      # @option args [String] :term category term
+      # @option args [String] :schema category schema, ending with '#'
+      # @option args [String] :title (nil) category title
+      # @option args [Hash] :attributes (Hash) category attributes
+      def initialize(args = {})
+        pre_initialize(args)
+        default_args! args
+
+        @term = args.fetch(:term)
+        @schema = args.fetch(:schema)
+        @title = args.fetch(:title)
+        @attributes = args.fetch(:attributes)
+
+        post_initialize(args)
       end
 
-      # @return [String] Type identifier of the Category.
-      def type_identifier
-        "#{self.scheme}#{self.term}"
+      # Returns a full category identifier constructed from
+      # `term` and `schema`.
+      #
+      # @example
+      #   category.identifier  # => 'http://example.org/test#gnr'
+      #
+      # @return [String] category identifier
+      def identifier
+        "#{schema}#{term}"
       end
 
-      # @param options [Hash]
-      # @return [Hashie::Mash] JSON representation of Category.
-      def as_json(options={})
-        category = Hashie::Mash.new
-        category.scheme = self.scheme
-        category.term = self.term
-        category.title = self.title if self.title
-        category.attributes = self.attributes.any? ? self.attributes.as_json : Occi::Core::Attributes.new.as_json
-        category
+      # Performs internal validation of the category. Returns
+      # `true` or `false` depending on the result. Currently, only
+      # the category identifier is used in this process.
+      #
+      # @example
+      #   category.valid?  # => true
+      #
+      # @return [TrueClass] when valid
+      # @return [FalseClass] when invalid
+      def valid?
+        # TODO: validate attribute definitions?
+        self.class.valid_identifier? identifier
       end
 
-      # @return [String] Short text representation of the Category.
-      def to_string_short
-        "#{self.term};scheme=#{self.scheme.inspect};class=#{self.class.name.demodulize.downcase.inspect}"
+      # Performs internal validation of the category. Raises error
+      # depending on the result. Currently, only the category
+      # identifier is used in this process.
+      #
+      # @example
+      #   category.valid!
+      #
+      # @raise [Occi::Core::Errors::CategoryValidationError] when invalid
+      def valid!
+        # TODO: validate attribute definitions?
+        self.class.valid_identifier! identifier
       end
 
-      # @return [String] Full text representation of the Category.
-      def to_string
-        string = self.to_string_short
-        string << ";title=#{self.title.inspect}" if self.title
-        string
+      # :nodoc:
+      def to_s
+        identifier
       end
 
-      # @return [String] Text representation of the Category.
-      def to_text
-        "Category: #{self.to_string}"
+      # :nodoc:
+      def ==(other)
+        return false unless other && other.respond_to?(:identifier)
+        identifier == other.identifier
       end
 
-      # @return [Hash] Hash containing the HTTP headers of the text/occi rendering.
-      def to_header
-        {:Category => self.to_string}
+      # :nodoc:
+      def eql?(other)
+        self == other
       end
 
-      # @return [NilClass] Returns nil as Category itself does not have a location.
-      def location
-        nil # not implemented
+      # :nodoc:
+      def hash
+        identifier.hash
       end
 
-      # @return [String] Type Identififier of the Category.
-      def to_s
-        self.type_identifier
-      end
+      protected
 
-      # @return [Boolean] Indicating whether this category is "empty", i.e. required attributes are blank
-      def empty?
-        term.blank? || scheme.blank?
+      # :nodoc:
+      def sufficient_args!(args)
+        %i[term schema].each do |attr|
+          unless self.class.send("valid_#{attr}?", args[attr])
+            raise Occi::Core::Errors::MandatoryArgumentError, "#{attr} is a mandatory " \
+                  "argument for #{self.class}"
+          end
+        end
       end
 
-      # Checks this category against the model
-      # @param check_attributes [Boolean] attribute definitions must match
-      # @param check_title [Boolean] titles must match
-      # @return [Boolean]
-      def check(check_attributes = false, check_title = false)
-        raise ArgumentError, 'No model has been assigned to this category' unless @model
-
-        cat = @model.get_by_id(type_identifier, true)
-        raise Occi::Errors::CategoryNotDefinedError,
-              "Category #{self.class.name}[#{type_identifier.inspect}] not found in the model!" unless cat
-
-        # TODO: impl. check_attributes and check_title for strict matching
-
-        true
+      # :nodoc:
+      def defaults
+        {
+          term: nil,
+          schema: nil,
+          title: nil,
+          attributes: {}
+        }
       end
 
-      # @param term [String] Term to check.
-      # @return [Boolean] Indicating whether term consists exclusively of valid characters.
-      def self.valid_term?(term)
-        term =~ /^[a-z][a-z0-9_-]*$/
-      end
+      # :nodoc:
+      def pre_initialize(args); end
 
+      # :nodoc:
+      def post_initialize(args); end
     end
   end
 end