angus-sdoc 0.0.1 → 0.0.2

data/lib/angus/base.rb

@@ -0,0 +1,11 @@
+module Angus
+  module SDoc
+  end
+end
+
+require_relative 'definitions/base'
+require_relative 'exceptions/base'
+require_relative 'definitions_reader'
+require_relative 'definitions_utils'
+require_relative 'sdoc/json_formatter'
+require_relative 'sdoc/html_formatter'

data/lib/angus/definitions/base.rb

@@ -0,0 +1,18 @@
+module Angus
+  module SDoc
+    module Definitions
+    end
+  end
+end
+
+require_relative 'service'
+require_relative 'proxy_operation'
+require_relative 'representation'
+require_relative 'representation_field'
+require_relative 'request_element'
+require_relative 'response_element'
+require_relative 'uri_element'
+require_relative 'operation'
+require_relative 'message'
+require_relative 'glossary'
+require_relative 'glossary_term'

data/lib/angus/definitions/glossary.rb

@@ -0,0 +1,52 @@
+module Angus
+  module SDoc
+    class Definitions::Glossary
+
+      # @!attribute [rw] terms
+      #   @return [GlossaryTerm] The terms of the glossary.
+      attr_accessor :terms
+
+      # Initializes a new Glossary and its terms.
+      #
+      # @param [Hash<String, Hash>] terms_hash The hash contains GlossaryTerm#short_name as the key
+      #   and a hash containing GlossaryTerm#long_name and GlossaryTerm#description as a value.
+      #
+      # @example
+      #
+      #   {'Glossary Term Name' =>
+      #     {
+      #       'long_name'   => 'Long name of the glossary term',
+      #       'description' => 'Description of the glossary term'
+      #     }
+      #   }
+      def initialize(terms_hash = {})
+        @terms = Angus::SDoc::Definitions::GlossaryTerm.build_from_hash(terms_hash)
+      end
+
+      # Returns a hash with short name as key and the term as the value.
+      #
+      # @return [Hash<String, GlossaryTerm>]
+      def terms_hash
+        hash = {}
+
+        @terms.each do |term|
+          hash[term.short_name] = term
+        end
+
+        hash
+      end
+
+      # Returns a hash with long name as key and the term as the value.
+      #
+      # @return [Hash<String, GlossaryTerm>]
+      def terms_hash_with_long_names
+        hash = {}
+        @terms.each do |term|
+          hash[term.long_name] = term
+        end
+        hash
+      end
+
+    end
+  end
+end

data/lib/angus/definitions/glossary_term.rb

@@ -0,0 +1,37 @@
+module Angus
+  module SDoc
+    # @attr [String] short_name The short name of the glossary term.
+    # @attr [String] long_name The long name of the glossary term.
+    # @attr [String] description The description of the glossary term.
+    class Definitions::GlossaryTerm < Struct.new(:short_name, :long_name, :description)
+
+      class << self
+
+        # Initialize multiple GlossaryTerm using the information in the hash parameter.
+        #
+        # @param [Hash] hash The Hash contains GlossaryTerm#short_name
+        #   as key and other Hash with the other attributes of the GlossaryTerm as a value.
+        #
+        # @return [Array<GlossaryTerm>] The list of glossary terms.
+        def build_from_hash(hash = {})
+          hash.map do |sort_name, gt|
+            self.new(sort_name, gt['long_name'], gt['description'])
+          end
+        end
+
+      end
+
+      # Check if an object is equals to the current instance.
+      #
+      # @param [GlossaryTerm] other The object to be compared.
+      #
+      # @return [Boolean] true if all the attributes are equal and false otherwise.
+      def == (other)
+        other.kind_of?(Definitions::GlossaryTerm) &&
+          self.short_name == other.short_name && self.long_name == other.long_name &&
+          self.description == other.description
+      end
+
+    end
+  end
+end

data/lib/angus/definitions/message.rb

@@ -0,0 +1,31 @@
+module Angus
+  module SDoc
+    class Definitions::Message
+
+      ERROR_LEVEL = 'error'
+      INFO_LEVEL = 'info'
+      WARNING_LEVEL = 'warning'
+
+      # @!attribute [rw] level
+      #   @return [String] the level of the message. Possible values are the *_LEVEL constants.
+      attr_accessor :level
+
+      # @!attribute [rw] key
+      #   @return [String] the key of the message. It is a human readable unique identifier.
+      #     It has to start with Mayus and it has to be camelcase.
+      attr_accessor :key
+
+      # @!attribute [rw] description
+      #   @return [String] the description of the message.
+      attr_accessor :description
+
+      # @!attribute [rw] status_code
+      #   @return [String] the HTTP status code of the message.
+      attr_accessor :status_code
+
+      # @!attribute [rw] text
+      #   @return [String] when set this text overrides all others and is set as the message description.
+      attr_accessor :text
+    end
+  end
+end

data/lib/angus/definitions/operation.rb

@@ -0,0 +1,62 @@
+module Angus
+  module SDoc
+    class Definitions::Operation
+
+      # @!attribute [rw] name
+      #   @return [String] the name of the operation.
+      attr_accessor :name
+
+      # @!attribute [rw] code_name
+      #   @return [String] the code name of the message. It is a human readable unique identifier.
+      #     It has to start with Mayus and it has to be camelcase.
+      attr_accessor :code_name
+
+      # @!attribute [rw] description
+      #   @return [String] the description of the operation.
+      attr_accessor :description
+
+      # @!attribute [rw] path
+      #   @return [String] the path of the operation.
+      attr_accessor :path
+
+      # @!attribute [rw] method
+      #   @return [String] the HTTP method of the operation.
+      attr_accessor :method
+
+      # @!attribute [rw] messages
+      #   @return [Hash<String, Message>] the messages associated with the operation.
+      attr_accessor :messages
+
+      # @!attribute [rw] uri_elements
+      #   @return [Set<UriElement>] the uri elements of the operation.
+      attr_accessor :uri_elements
+
+      # @!attribute [rw] request_elements
+      #   @return [Set<RequestElement>] the request elements of the operation.
+      attr_accessor :request_elements
+
+      # @!attribute [rw] response_elements
+      #   @return [Set<ResponseElement>] the response elements of the operation.
+      attr_accessor :response_elements
+
+      def code_name
+        @code_name.split('.')[-1]
+      end
+
+      # Returns the first message that matches the given key and level.
+      #
+      # @param [String] key The key of the message.
+      # @param [String] level The level of the message.
+      #   Possible values are the *_LEVEL constants from {Message}.
+      #
+      # @return [Message] the message or nil if no one matches.
+      def message(key, level)
+        return nil if self.messages.nil?
+
+        level &&= level.downcase
+        self.messages.find { |message| message.key == key && message.level.downcase == level }
+      end
+
+    end
+  end
+end

data/lib/angus/definitions/proxy_operation.rb

@@ -0,0 +1,24 @@
+module Angus
+  module SDoc
+    class Definitions::ProxyOperation
+
+      # @!attribute [rw] code_name
+      #   @return [String] the code name of the message. It is a human readable unique identifier.
+      #     It has to start with Mayus and it has to be camelcase.
+      attr_accessor :code_name
+
+      # @!attribute [rw] path
+      #   @return [String] the path of the operation.
+      attr_accessor :path
+
+      # @!attribute [rw] method
+      #   @return [String] the HTTP method of the operation.
+      attr_accessor :method
+
+      # @!attribute [rw] service_name
+      #   @return [String] the service name of the operation.
+      attr_accessor :service_name
+
+    end
+  end
+end

data/lib/angus/definitions/representation.rb

@@ -0,0 +1,15 @@
+module Angus
+  module SDoc
+    class Definitions::Representation
+
+      # @!attribute [rw] name
+      #   @return [String] the name of the representation.
+      attr_accessor :name
+
+      # @!attribute [rw] fields
+      #   @return [Array<RepresentationField>] the fields of the representation.
+      attr_accessor :fields
+
+    end
+  end
+end

data/lib/angus/definitions/representation_field.rb

@@ -0,0 +1,51 @@
+module Angus
+  module SDoc
+    class Definitions::RepresentationField
+
+      # @!attribute [rw] name
+      #   @return [String] the name of the representation field.
+      attr_accessor :name
+
+      # @!attribute [rw] description
+      #   @return [String] the description of the representation field.
+      attr_accessor :description
+
+      # @!attribute [rw] required
+      #   @return [Boolean] indicates if the representation field is required or not.
+      attr_accessor :required
+
+      # @!attribute [rw] type
+      #   @return [String] the type of the representation field.
+      #     This attribute is used when the representation is a single object.
+      attr_accessor :type
+
+      # @!attribute [rw] elements_type
+      #   @return [String] the elements type of the representation field.
+      #     This attribute is used when the representation is a list of objects.
+      attr_accessor :elements_type
+
+      # @note if the elements_type attribute is different from nil, it means that the
+      #   representation field is a list of objects. In that case, the type parameter
+      #   is not considered.
+      def initialize(name = nil, description = nil, required = nil, type = nil, elements_type = nil)
+        self.name= name
+        self.description= description
+        self.required= required
+        self.type= type
+        self.elements_type= elements_type
+      end
+
+      # Check if an object is equals to the current instance.
+      #
+      # @param [RepresentationField] other The object to be compared.
+      #
+      # @return [Boolean] true if all the attributes are equal and false otherwise.
+      def == (other)
+        other.kind_of?(Definitions::RepresentationField) &&
+          self.name == other.name && self.description == other.description &&
+          self.required == other.required && self.type == other.type && self.elements_type == other.elements_type
+      end
+
+    end
+  end
+end

data/lib/angus/definitions/request_element.rb

@@ -0,0 +1,61 @@
+module Angus
+  module SDoc
+    class Definitions::RequestElement
+
+      # @!attribute [rw] name
+      #   @return [String] the name of the request element.
+      attr_accessor :name
+
+      # @!attribute [rw] description
+      #   @return [String] the description of the request element.
+      attr_accessor :description
+
+      # @!attribute [rw] required
+      #   @return [Boolean] indicates if the request element is required or not.
+      attr_accessor :required
+
+      # @!attribute [rw] type
+      #   @return [String] the type of the request element.
+      attr_accessor :type
+
+      # @!attribute [rw] constraints
+      #   @return [Array<String>] the constraints of the request element.
+      attr_accessor :constraints
+
+      # @!attribute [rw] valid_values
+      #   @return [Array<String>] the valid values of the request element.
+      attr_accessor :valid_values
+
+      # @!attribute [rw] elements_type
+      #   @return [String] the elements type of the request element.
+      attr_accessor :elements_type
+
+
+      def initialize(name = nil, description = nil, required = nil, type = nil,
+                     constraints = nil, valid_values = nil, elements_type = nil)
+        self.name= name if name
+        self.description= description if description
+        self.required= required if required
+        self.type= type if type
+        self.constraints= constraints if constraints
+        self.valid_values= valid_values if valid_values
+        self.elements_type= elements_type if elements_type
+      end
+
+      # Check if an object is equals to the current instance.
+      #
+      # @param [RequestElement] other The object to be compared.
+      #
+      # @return [Boolean] true if all the attributes are equal and false otherwise.
+      def == (other)
+        other.instance_of?(Definitions::RequestElement) &&
+          self.name == other.name && self.description == other.description &&
+          self.required == other.required && self.type == other.type &&
+          self.constraints == other.constraints &&
+          self.valid_values == other.valid_values &&
+          self.elements_type == other.elements_type
+      end
+
+    end
+  end
+end

data/lib/angus/definitions/response_element.rb

@@ -0,0 +1,41 @@
+module Angus
+  module SDoc
+    class Definitions::ResponseElement
+
+      # @!attribute [rw] name
+      #   @return [String] the name of the response element.
+      attr_accessor :name
+
+      # @!attribute [rw] description
+      #   @return [String] the description of the response element.
+      attr_accessor :description
+
+      # @!attribute [rw] required
+      #   @return [Boolean] indicates if the response element is required or not.
+      attr_accessor :required
+
+      # @!attribute [rw] type
+      #   @return [String] the type of the response element.
+      attr_accessor :type
+
+      # @!attribute [rw] default
+      #   @return [String] the default value of the response element.
+      attr_accessor :default
+
+      # @!attribute [rw] elements_type
+      #   @return [String] the elements type of the response element.
+      attr_accessor :elements_type
+
+      def initialize(name = nil, description = nil, required = nil, type = nil, default = nil,
+                     elements_type = nil)
+        @name = name
+        @description = description
+        @required = required
+        @type = type
+        @default = default
+        @elements_type = elements_type
+      end
+
+    end
+  end
+end

data/lib/angus/definitions/service.rb

@@ -0,0 +1,118 @@
+module Angus
+  module SDoc
+    class Definitions::Service
+
+      # @!attribute [rw] name
+      #   @return [String] the name of the sevice.
+      attr_accessor :name
+
+      # @!attribute [rw] code_name
+      #   @return [String] the service code name is a unique identifier.
+      #     It has to be human-readable and a valid literal identifier.
+      attr_accessor :code_name
+
+      # @!attribute [rw] version
+      #   @return [String] the version of the sevice.
+      attr_accessor :version
+
+      # @!attribute [rw] messages
+      #   @return [Hash<String, Message>] the messages associated with the service.
+      attr_accessor :messages
+
+      # @!attribute [rw] operations
+      #   @return [Set<Operation>] the operations of the service.
+      attr_accessor :operations
+
+      # @!attribute [rw] proxy_operations
+      #   @return [Set<ProxyOperation>] the proxy operations of the service.
+      attr_accessor :proxy_operations
+
+      # @!attribute [rw] representations
+      #   @return [Set<Representation>] the representations of the service.
+      attr_accessor :representations
+
+      # @!attribute [rw] glossary
+      #   @return [Glossary] the glossary of the service.
+      attr_accessor :glossary
+
+      def initialize
+        @messages = {}
+        @operations = Set.new
+        @representations = Set.new
+        @glossary = Angus::SDoc::Definitions::Glossary.new
+      end
+
+      # Returns the message that matches the given key and level.
+      #
+      # This method searches for messages in all the operations and returns
+      # the first message that matches.
+      #
+      # @param [#to_s] key The key of the message.
+      # @param [String] level The level of the message
+      #   Possible values are the *_LEVEL constants from {Message}
+      #
+      # @return [Message] the message or nil if no one matches.
+      def message(key, level)
+        msg = nil
+
+        @operations.find do |operation|
+          msg = operation.message(key.to_s, level)
+        end
+
+        msg
+      end
+
+      # Merge the following definitions:
+      #  - Operations.
+      #  - Representations.
+      #  - Messages.
+      #
+      # @note This method does not merge glossary terms.
+      #
+      # @param [Service] other The service to be merged.
+      def merge(other)
+        self.operations.merge!(other.operations)
+        self.representations += other.representations
+
+        self.messages.merge!(other.messages)
+      end
+
+      # Returns the operation definition that matches with the given operation name.
+      #
+      # @param operation_code_name The operation code name.
+      #
+      # @return [Operation] The operation.
+      def operation_definition(namespace, operation_code_name)
+        @operations[namespace].find { |operation| operation.code_name == operation_code_name }
+      end
+
+      # Returns the proxy operations for a given service.
+      # @todo Does it receives the service or the service name?
+      # @todo Verify if this method is being called by remote-client and if it receives
+      #   the service name.
+      # @param service The service name.
+      # @return [Array<ProxyOperation>] The proxy operations.
+      def proxy_operations_for(service)
+        self.proxy_operations.select do |op|
+          op.service_name == service
+        end
+      end
+
+      # Returns a hash with the representations.
+      # @example
+      #  {
+      #    key => rollback_payment_multi,
+      #    value => {representation}
+      #  }
+      # @return [Hash<String, Representation>] The representation hash.
+      def representations_hash
+        hash = {}
+        @representations.each do |representation|
+          hash[representation.name] = representation
+        end
+        hash
+      end
+
+    end
+  end
+end

data/lib/angus/definitions/uri_element.rb

@@ -0,0 +1,20 @@
+module Angus
+  module SDoc
+    class Definitions::UriElement
+
+      # @!attribute [rw] name
+      #   @return [String] the name of the uri element.
+      attr_accessor :name
+
+      # @!attribute [rw] description
+      #   @return [String] the description of the uri element.
+      attr_accessor :description
+
+      def initialize(name = nil, description = nil)
+        @name = name
+        @description = description
+      end
+
+    end
+  end
+end