base_parser.rb in eco-helpers-0.7.1

- old
+ new
@@ -1,15 +1,45 @@
 module Eco
   module API
     module Common
       module People
+
+        # @example Example of usage:
+        #  class ExampleParser < Eco::API::Common::People::BaseParser
+        #    def process
+        #      @parsers.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
+        #    end
+        #  end
+        #  pparser = Eco::API::Common::People::PersonParser.new
+        #  ExampleParser.new(pparser)
+        #  pparser.parse("example","3") # out: 3
+        #  pparser.parse("example","3", deps: {sum_5: true}) # out: 8
+        #  pparser.serialise("example, 8) # out: "8"
+        #
+        # Helper class to inherit from to ease the definition of attribute parsers in a `PersonParser` object,
+        # mostly used in for configuration loading.
         class BaseParser
+
+          # @param parsers [Eco::API::Common::People::PersonParser] set of attribute parsers/serialisers.
+          # @param options [Hash] keyword arguments to be used in the `process` method of the child class.
           def initialize(parsers, **options)
             @parsers = parsers
             @options = options
           end
 
-          def process; end
+          # Method to be overriden by the child class.
+          # @note this method is called to load the definition of the attribute parser/serializer.
+          def process
+            raise "Method needs to be overriden in the child class #{self.class}"
+          end
         end
       end
     end
   end
 end