eco-helpers 0.6.17 → 0.7.1

data/lib/eco/api/common/people/person_entry_attribute_mapper.rb

@@ -0,0 +1,212 @@
+module Eco
+  module API
+    module Common
+      module People
+
+        # @attr_reader core_attrs [Array<String>] core attributes that are present in the person entry.
+        # @attr_reader details_attrs [Array<String>] schema details attributes that are present in the person entry.
+        # @attr_reader account_attrs [Array<String>] account attributes that are present in the person entry.
+        # @attr_reader all_attrs [Array<String>] all the attrs that are present in the person entry.        
+        # @attr_reader internal_attrs [Array<String>] all the internally named attributes that the person entry has.
+        # @attr_reader aliased_attrs [Array<String>] only those internal attributes present in the person entry that have an internal/external name mapping.
+        # @attr_reader direct_attrs [Array<String>] only those internal attributes present in the person entry that do **not** have an internal/external name mapping.
+        class PersonEntryAttributeMapper
+          @@cached_warnings = {}
+
+          attr_reader :core_attrs, :details_attrs, :account_attrs, :all_attrs
+          attr_reader :internal_attrs, :aliased_attrs, :direct_attrs
+
+          # Helper class tied to `PersonEntry` that allows to track which attributes of a person entry are present
+          # and how they should be mapped between internal and external names if applicable.
+          # This class is meant to help in providing a common interface to access entries of source data that come in different formats.
+          # @note
+          #   - if `data` is a `Person` object, its behaviour is `serialise`.
+          #   - if `data` is **not** a `Person` object, it does a `parse`.
+          #   - currently **in rework**, so there may be subtle differences that make it temporarily unstable (yet it is reliable).
+          # @param data [Hash, Person] `Person` object to be serialized or hashed entry (`CSV::Row` is accepted).
+          # @param person_parser [Common::People::PersonParser]  parser/serializer of person attributes (it contains a set of attribute parsers).
+          # @param attr_map [Eco::Data::Mapper] mapper to translate attribute names from _external_ to _internal_ names and _vice versa_.
+          # @param logger [Common::Session::Logger, ::Logger] object to manage logs.
+          def initialize(data, person_parser:, attr_map:, logger: ::Logger.new(IO::NULL))
+            raise "Constructor needs a PersonParser. Given: #{parser}" if !person_parser.is_a?(Eco::API::Common::People::PersonParser)
+            raise "Expecting Mapper object. Given: #{attr_map}" if attr_map && !attr_map.is_a?(Eco::Data::Mapper)
+
+            @source   = data
+            @person_parser  = person_parser
+            @attr_map = attr_map
+            @logger   = logger
+
+            if parsing?
+              @external_entry   = data
+              init_attr_trackers
+            else  # SERIALIZING
+              @person          = data
+              @internal_attrs  = @person_parser.all_attrs
+            end
+
+            @core_attrs    = @person_parser.target_attrs_core(@internal_attrs)
+            @details_attrs = @person_parser.target_attrs_details(@internal_attrs)
+            @account_attrs = @person_parser.target_attrs_account(@internal_attrs)
+            @all_attrs     = @core_attrs | @account_attrs | @details_attrs
+          end
+
+          # To know if currently the object is in parse or serialize mode.
+          # @return [Boolean] returns `true` if we are **parsing**, `false` otherwise.
+          def parsing?
+            !@source.is_a?(Ecoportal::API::Internal::Person)
+          end
+
+          # To know if currently the object is in parse or serialize mode.
+          # @return [Boolean] returns `true` if we are **serializing**, `false` otherwise.
+          def serializing?
+            !parsing?
+          end
+
+          # If there **no** `mapper` defined for the object, it mirrors `value`.
+          # If there is a `mapper` defined for the object:
+          #  1. if the `value` exists as external, translates it into an internal one.
+          #  2. if it doesn't exist, returns `nil`.
+          # @note
+          #  1. the **scope of attributes** is based on all the attributes recognized by the person parser.
+          #  2. the attributes recognized by the person parser are those of of the `Person` model (where details attributes depend on the `schema`).
+          # @param value [String, Array<String>] value(s) to be translated into internal names.
+          # @return [String, nil, Array<String] the internal name(s) of `value`.
+          def to_internal(value)
+            return value if !@attr_map
+            attr = value
+            case value
+            when Array
+              return value.map do |v|
+                to_internal(v)
+              end.compact
+            when String
+              case
+              when @attr_map.external?(value)
+                attr = @attr_map.to_internal(value)
+              when @attr_map.external?(value.strip)
+                unless cached_warning("external", "spaces", value)
+                  logger.warn("The external person field name '#{value}' contains additional spaces in the reference file")
+                end
+                attr = @attr_map.to_internal(value.strip)
+              when @attr_map.internal?(value) || @attr_map.internal?(value.strip) || @attr_map.internal?(value.strip.downcase)
+                unless cached_warning("external", "reversed", value)
+                  logger.warn("The mapper [external, internal] attribute names may be declared reversedly for EXTERNAL attribute: '#{value}'")
+                end
+              end
+            end
+
+            return nil unless @person_parser.all_attrs.include?(attr)
+          end
+
+          # Serializing helper also used to do a reverse mapping when parsing:
+          #  - as there could be _internal attributes_ that shared _external attributes_,
+          #  - when parsing, you use this helper to recognize the source _external attribute_ of each _internal_ one.
+          # If there **no** `mapper` defined for the object, it mirrors `value`.
+          # If there is a `mapper` defined for the object:
+          #  1. if the `value` exists as _internal-, translates it into an _external_ one.
+          #  2. if it doesn't exist, returns `nil`.
+          # @note
+          #  1. the **scope of attributes** is based on all the attributes defined in the current entry.
+          #  2. the attributes recognized by the person parser are those of of the `Person` model (where details attributes depend on the `schema`).
+          # @param value [String, Array<String>] value(s) to be translated or aliased into external ones.
+          # @return [String, nil, Array<String] the external name(s) of `value`.
+          def to_external(value)
+            return value if !@attr_map
+            attr = value
+            case value
+            when Array
+              return value.map do |v|
+                to_external(v)
+              end.compact
+            when String
+              case
+              when @attr_map.internal?(value)
+                attr = @attr_map.to_external(value)
+              when @attr_map.internal?(value.strip)
+                unless cached_warning("internal", "spaces", value)
+                  logger.warn("The internal person field name '#{value}' contains additional spaces in the reference file")
+                end
+                attr = @attr_map.to_external(value.strip)
+              when @attr_map.external?(value) || @attr_map.external?(value.strip) || @attr_map.external?(value.strip.downcase)
+                unless cached_warning("internal", "reversed", value)
+                  logger.warn("The mapper [external, internal] attribute names may be declared reversedly for INTERNAL attribute: '#{value}'")
+                end
+              end
+            end
+
+            return nil unless !@external_entry || attributes(@external_entry).include?(attr)
+            attr
+          end
+
+          private
+
+          # when parsing:
+          def init_attr_trackers
+            # internal <-> external attributes
+            int_aliased     = @person_parser.all_attrs.select  { |attr| to_external(attr) }
+            ext_alias       = int_aliased.map { |attr| to_external(attr) }
+
+            # virtual attrs (non native internal attr that require aliasing):
+            ext_vi_aliased  = attributes(@external_entry).select do |attr|
+              !ext_alias.include?(attr) && @attr_map&.external?(attr)
+            end
+
+            # internal name of external attrs that are not native internal attrs
+            int_vi_aliased  = ext_vi_aliased.map do |attr|
+              # to_internal(attr) can't be used here, becauase virtual fields would get filtered out,
+              # as they are not recognized by @parser.all_attrs.include?(attr)
+              @attr_map.to_internal(attr)
+            end.compact
+
+            @aliased_attrs  = int_aliased + int_vi_aliased
+
+            int_unlinked    = @person_parser.undefined_attrs.select { |attr| !to_external(attr) }
+            # those with parser or alias:
+            int_linked      = @person_parser.all_attrs - int_unlinked
+
+            ext_aliased     = ext_alias + ext_vi_aliased
+            # those that are direct external to internal:
+            ext_direct      = attributes(@external_entry) - ext_aliased
+            # to avoid collisions between internal names:
+            @direct_attrs   = ext_direct - int_linked
+            @internal_attrs = @aliased_attrs | @direct_attrs
+          end
+
+          def attributes(value)
+            case value
+            when CSV::Row
+              value&.headers
+            when Hash
+              value&.keys
+            when PersonEntry
+              @person_parser.target_attrs_core
+            else
+              []
+            end
+          end
+
+          # LOGGER
+          def logger
+            @logger || ::Logger.new(IO::NULL)
+          end
+
+          def cached_warning(*args)
+            unless exists = !!@@cached_warnings.dig(*args)
+              args.reduce(@@cached_warnings) do |cache, level|
+                cache[level] = {} if !cache.key?(level)
+                cache[level]
+              end
+            end
+            exists
+          end
+
+          def fatal(msg)
+            logger.fatal(msg)
+            exit
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/common/people/person_factory.rb

@@ -4,8 +4,6 @@ module Eco
       module People
         class PersonFactory
 
-          include Common::People
-
           attr_reader :schema_attrs
 
           def initialize(person: {}, schema: {}, account: {}, modifier: Common::People::PersonModifier.new)
@@ -43,9 +41,9 @@ module Eco
 
           def klass
             if @modifier.external?
-              EXTERNAL::Person
+              Ecoportal::API::V1::Person
             else
-              INTERNAL::Person
+              Ecoportal::API::Internal::Person
             end
           end
 
@@ -69,10 +67,10 @@ module Eco
           end
 
           def person_hash(person)
-            case
-            when is_person?(person)
+            case person
+            when Ecoportal::API::V1::Person
               JSON.parse(person.doc.to_json)
-            when person.is_a?(Hash)
+            when Hash
               JSON.parse(person.to_json)
             else
               {}
@@ -80,12 +78,12 @@ module Eco
           end
 
           def details_hash(details)
-            case
-            when details.is_a?(EXTERNAL::PersonDetails)
+            case details
+            when Ecoportal::API::V1::PersonDetails
               doc = JSON.parse(details.doc.to_json)
-            when details.is_a?(EXTERNAL::PersonSchema)
+            when Ecoportal::API::V1::PersonSchema
               doc =JSON.parse(details.doc.to_json)
-            when details.is_a?(Hash)
+            when Hash
               doc = JSON.parse(details.to_json)
               doc = doc["details"] if doc.key?("details")
             else
@@ -97,7 +95,7 @@ module Eco
 
           def account_hash(account)
             case
-            when account.is_a?(INTERNAL::Account)
+            when account.is_a?(Ecoportal::API::Internal::Account)
               JSON.parse(account.doc.to_json)
             when account.is_a?(Hash)
               doc = JSON.parse(account.to_json)

data/lib/eco/api/common/people/person_parser.rb

@@ -2,17 +2,35 @@ module Eco
   module API
     module Common
       module People
+
+        # Class to define/group a set of parsers/serializers.
+        #
+        # @attr_reader schema [Ecoportal::API::V1::PersonSchema, nil] schema of person details that this parser will be based upon.
+        # @attr_reader details_attrs [Array<String>] internal names of schema details attributes.
+        # @attr_reader all_attrs [Array<String>] all the internal name attributes, including _core_, _account_ and _details_.
         class PersonParser
           CORE_ATTRS    = ["id", "external_id", "email", "name", "supervisor_id"]
           ACCOUNT_ATTRS = ["policy_group_ids", "filter_tags", "default_tag"]
           TYPE          = [:select, :text, :date, :number, :phone_number, :boolean, :multiple]
+          FORMAT        = [:csv, :xml, :json]
 
           attr_reader :schema
           attr_reader :details_attrs, :all_attrs
           attr_reader :defined_attrs
 
-          def initialize(schema: nil) #), logger: nil)
-            #self.schema = schema
+          # @example Example of usage:
+          #  person_parser = PersonParser.new(schema: schema)
+          #  person_parser.define_attribute("example") do |parser|
+          #    parser.def_parser  do |str, deps|
+          #      i = value.to_i rescue 0
+          #      i +=5 if deps.dig(:sum_5)
+          #      i
+          #    end.def_serializer do |value|
+          #      value.to_s
+          #    end
+          #  end
+          # @param schema [Ecoportal::API::V1::PersonSchema, nil] schema of person details that this parser will be based upon.
+          def initialize(schema: nil)
             raise "Constructor needs a PersonSchema. Given: #{schema}" if schema && !schema.is_a?(Ecoportal::API::V1::PersonSchema)
             @details_attrs = []
             @parsers = {}
@@ -23,49 +41,66 @@ module Eco
             end
 
             @all_attrs = CORE_ATTRS + ACCOUNT_ATTRS + @details_attrs
-            #init_default_parsers if @schema
           end
 
+          # Lists all defined attributes, types and formats.
+          # @return [Array<String>] the list of defined parsers/serializers.
+          def list_defined
+            @parsers.keys
+          end
+
+          # Scopes `source_attrs` using the _**core** attributes_.
+          # @note use this helper to know which among your attributes are **core** ones.
+          # @param source_attrs [Array<String>]
+          # @return [Array<String>] the scoped **core** attributes, if `source_attrs` is not `nil`. All the _core attributes_, otherwise.
           def target_attrs_core(source_attrs = nil)
             return CORE_ATTRS if !source_attrs
             scoped_attrs(source_attrs, CORE_ATTRS)
           end
 
+          # Scopes `source_attrs` using the schema _**details** attributes_.
+          # @note use this helper to know which among your attributes are schema **details** ones.
+          # @param source_attrs [Array<String>]
+          # @return [Array<String>] the scoped **details** attributes, if `source_attrs` is not `nil`. All the _details attributes_, otherwise.
           def target_attrs_details(source_attrs = nil)
             return @details_attrs if ! source_attrs
             scoped_attrs(source_attrs, @details_attrs)
           end
 
+          # Scopes `source_attrs` using the schema _**account** attributes_.
+          # @note use this helper to know which among your attributes are **account** ones.
+          # @param source_attrs [Array<String>]
+          # @return [Array<String>] the scoped **account** attributes, if `source_attrs` is not `nil`. All the _account attributes_, otherwise.
           def target_attrs_account(source_attrs = nil)
             return ACCOUNT_ATTRS if !source_attrs
             scoped_attrs(source_attrs, ACCOUNT_ATTRS)
           end
 
-          def defined
-            @parsers.keys
-          end
-
-          def list
-            @parsers.keys
-          end
-
+          # Returns a list of all the internal attributes of the model that have a parser defined.
+          # @note it excludes any parser that is not in the model, such as type parsers (i.e. ``:boolean`, ``:multiple`)
+          # @return [Array<String>] list of all attribute defined parsers.
           def defined_attrs
+            defined = @parsers.keys
             defined - (defined - all_attrs)
           end
 
+          # Returns a list of all the internal attributes of the model that do **not** have a parser defined.
+          # @note it excludes any parser that is **not** in the model, such as type parsers (i.e. :boolean, :multiple)
+          # @return [Array<String>] list of all attributes without a defined parser.
           def undefined_attrs
             all_attrs - defined_attrs
           end
 
+          # @param attr [String] internal name of an attribute.
+          # @return [Boolean] `true` if the attribute `attr` has parser defined, and `false` otherwise.
           def defined?(attr)
-            !!@parsers[attr]
+            @parsers.key?(attr)
           end
 
-          #def append(attr, dependencies: {}, &bloc)
-          #  @parsers[attr] = into_a(parsers[attr]).push(define_parser(attr, dependencies, &bloc))
-          #end
-
-          # merges parser overriding self for exisint parsers
+          # Helper to **merge** a set of parsers of another `PersonParser` into the current object.
+          # @note if there are parsers with same name, it **overrides** the ones of the current object with them.
+          # @param parser [Eco::API::Common::People::PersonParser] a `PersonParser` containing defined parsers.
+          # @return [Eco::API::Common::People::PersonParser] the current object (to ease chainig).
           def merge(parser)
             return self if !parser
             raise "Expected a PersonParser object. Given #{parser}" if !parser.is_a?(PersonParser)
@@ -73,16 +108,51 @@ module Eco
             self
           end
 
-          def define_attribute(attr, dependencies: {}, &bloc)
-            @parsers[attr] = define_parser(attr, dependencies, &bloc)
+
+          # Helper to define and associate a parser/serializer to a type or attribute.
+          # @raise [Exception] if trying to define a parser/serializer for:
+          #   - an unkown attribute (`String`)
+          #   - an unrecognized type or format (`Symbol`)
+          # @param attr [String] type (`Symbol`) or attribute (`String`) to define the parser/serializer to.
+          # @param dependencies [Hash] dependencies to be used when calling the parser/serializer.
+          # @yield [parser] the definition of the parser.
+          # @yieldparam parser [Eco::Language::Models::ParserSerializer] parser to define.
+          # @return [Eco::API::Common::People::PersonParser] the current object (to ease chainig).
+          def define_attribute(attr, dependencies: {}, &definition)
+            if !valid?(attr)
+              msg = "The attribute '#{attr_to_str(attr)}' is not part of core, account or target schema, or does not match any type: #{@details_attrs}"
+              raise msg
+            end
+
+            Eco::Language::Models::ParserSerializer.new(attr, dependencies: dependencies).tap do |parser|
+              @parsers[attr] = parser
+              definition.call(parser)
+            end
+
             self
           end
 
+          # Call to parser `source` value of attribute or type `attr` into an internal valid value.
+          # @note dependencies introduced on `parse` call will be merged with those defined during the
+          #  initialization of the parser `attr`.
+          # @raise [Exception] if there is **no** parser for attribute or type `attr`.
+          # @param attr [String] target attribute or type to **parse**.
+          # @param source [Any] source value to be parsed.
+          # @param deps [Hash] key-value pairs of call dependencies.
+          # @return [Any] a valid internal value.
           def parse(attr, source, deps: {})
             raise "There is no parser for attribute '#{attr}'" if !self.defined?(attr)
             @parsers[attr].parse(source, dependencies: deps)
           end
 
+          # Call to serialise `object` value of attribute or type `attr` into an external valid value.
+          # @note dependencies introduced on `serialise` call will be merged with those defined during the
+          #  initialization of the parser/serialiser `attr`.
+          # @raise [Exception] if there is **no** serialiser for attribute or type `attr`.
+          # @param attr [String] target attribute or type to **serialize**.
+          # @param object [Any] object value to be serialized.
+          # @param deps [Hash] key-value pairs of call dependencies.
+          # @return a valid external value.
           def serialize(attr, object, deps: {})
             raise "There is no parser for attribute '#{attr}'" if !self.defined?(attr)
             @parsers[attr].serialize(object, dependencies: deps)
@@ -90,6 +160,7 @@ module Eco
 
           protected
 
+          # @return [Hash] attr-parser pairs with all the defined type and attribute parsers/serializers.
           def hash
             @parsers
           end
@@ -102,35 +173,24 @@ module Eco
             (source_attrs + parsed_attrs) & (direct_attrs + parsed_attrs)
           end
 
-          def define_parser(attr, dependencies = {}, &definition)
-            if !valid?(attr)
-              str_attr = (attr.is_a?(Symbol) ? ":" : "") + attr.to_s
-              msg = "The attribute '#{str_attr}' is not part of core, account or target schema, or does not match any type: #{@details_attrs}"
-              raise msg
-            end
-            parser = Eco::Language::Models::AttributeParser.new(attr, dependencies: dependencies)
-            #yield(parser)
-            definition.call(parser)
-            parser
+          def attr_to_str(attr)
+            attr.is_a?(Symbol)? ":#{attr.to_s}" : "#{attr.to_s}"
           end
 
           def valid?(attr)
-            (attr.is_a?(Symbol) && valid_type?(attr)) ||
-            (attr.is_a?(String) && (!@schema || valid_attr?(attr)))
+            valid_attr?(attr) || valid_type?(attr) || valid_format?(attr)
           end
 
           def valid_attr?(attr)
-            @all_attrs.include?(attr)
+            attr.is_a?(String) && (!@schema || @all_attrs.include?(attr))
           end
 
           def valid_type?(attr)
-            TYPE.include?(attr)
+            attr.is_a?(Symbol) && TYPE.include?(attr)
           end
 
-          def into_a(value)
-            value = [] if value == nil
-            value = [].push(value) unless value.is_a?(Array)
-            value
+          def valid_format?(attr)
+            attr.is_a?(Symbol) && FORMAT.include?(attr)
           end
 
         end