<commit_before>require 'rom/initializer'
require 'rom/relation/materializable'

require 'rom/repository/relation_proxy/combine'
require 'rom/repository/relation_proxy/wrap'

module ROM
  class Repository
    # RelationProxy decorates a relation and automatically generates mappers that
    # will map raw tuples into rom structs
    #
    # Relation proxies are being registered within repositories so typically there's
    # no need to instantiate them manually.
    #
    # @api public
    class RelationProxy
      extend Initializer
      include Relation::Materializable

      include RelationProxy::Combine
      include RelationProxy::Wrap

      RelationRegistryType = Types.Definition(RelationRegistry).constrained(type: RelationRegistry)

      # @!attribute [r] relation
      #   @return [Relation, Relation::Composite, Relation::Graph, Relation::Curried] The decorated relation object
      param :relation

      option :name, type:  Types::Strict::Symbol
      option :mappers, reader: true, default: proc { MapperBuilder.new }
      option :meta, reader: true, default: proc { EMPTY_HASH }
      option :registry, type: RelationRegistryType, default: proc { RelationRegistry.new }, reader: true
      option :auto_struct, optional: true

      # Relation name
      #
      # @return [ROM::Relation::Name]
      #
      # @api public
      def name
        @name == Dry::Initializer::UNDEFINED ? relation.name : relation.name.with(@name)
      end

      # Materializes wrapped relation and sends it through a mapper
      #
      # For performance reasons a combined relation will skip mapping since
      # we only care about extracting key values for combining
      #
      # @api public
      def call(*args)
        ((combine? || composite?) ? relation : (relation >> mapper)).call(*args)
      end

      # Maps the wrapped relation with other mappers available in the registry
      #
      # @overload map_with(model)
      #   Map tuples to the provided custom model class
      #
      #   @example
      #     users.as(MyUserModel)
      #
      #   @param [Class>] model Your custom model class
      #
      # @overload map_with(*mappers)
      #   Map tuples using registered mappers
      #
      #   @example
      #     users.map_with(:my_mapper, :my_other_mapper)
      #
      #   @param [Array<Symbol>] mappers A list of mapper identifiers
      #
      # @return [RelationProxy] A new relation proxy with pipelined relation
      #
      # @api public
      def map_with(*names, **opts)
        if names.size == 1 && names[0].is_a?(Class)
          with(meta: meta.merge(model: names[0]))
        elsif names.size > 1 && names.any? { |name| name.is_a?(Class) }
          raise ArgumentError, 'using custom mappers and a model is not supported'
        else
          if opts[:auto_map]
            mappers = [mapper, *names.map { |name| relation.mappers[name] }]
            mappers.reduce(self) { |a, e| a >> e }
          else
            names.reduce(self) { |a, e| a >> relation.mappers[e] }<commit_msg>Expand yard docs for `#map_with` [ci skip]<commit_after>require 'rom/initializer'
require 'rom/relation/materializable'

require 'rom/repository/relation_proxy/combine'
require 'rom/repository/relation_proxy/wrap'

module ROM
  class Repository
    # RelationProxy decorates a relation and automatically generates mappers that
    # will map raw tuples into rom structs
    #
    # Relation proxies are being registered within repositories so typically there's
    # no need to instantiate them manually.
    #
    # @api public
    class RelationProxy
      extend Initializer
      include Relation::Materializable

      include RelationProxy::Combine
      include RelationProxy::Wrap

      RelationRegistryType = Types.Definition(RelationRegistry).constrained(type: RelationRegistry)

      # @!attribute [r] relation
      #   @return [Relation, Relation::Composite, Relation::Graph, Relation::Curried] The decorated relation object
      param :relation

      option :name, type:  Types::Strict::Symbol
      option :mappers, reader: true, default: proc { MapperBuilder.new }
      option :meta, reader: true, default: proc { EMPTY_HASH }
      option :registry, type: RelationRegistryType, default: proc { RelationRegistry.new }, reader: true
      option :auto_struct, optional: true

      # Relation name
      #
      # @return [ROM::Relation::Name]
      #
      # @api public
      def name
        @name == Dry::Initializer::UNDEFINED ? relation.name : relation.name.with(@name)
      end

      # Materializes wrapped relation and sends it through a mapper
      #
      # For performance reasons a combined relation will skip mapping since
      # we only care about extracting key values for combining
      #
      # @api public
      def call(*args)
        ((combine? || composite?) ? relation : (relation >> mapper)).call(*args)
      end

      # Maps the wrapped relation with other mappers available in the registry
      #
      # @overload map_with(model)
      #   Map tuples to the provided custom model class
      #
      #   @example
      #     users.as(MyUserModel)
      #
      #   @param [Class>] model Your custom model class
      #
      # @overload map_with(*mappers)
      #   Map tuples using registered mappers
      #
      #   @example
      #     users.map_with(:my_mapper, :my_other_mapper)
      #
      #   @param [Array<Symbol>] mappers A list of mapper identifiers
      #
      # @overload map_with(*mappers, auto_map: true)
      #   Map tuples using auto-mapping and custom registered mappers
      #
      #   If `auto_map` is enabled, your mappers will be applied after performing
      #   default auto-mapping. This means that you can compose complex relations
      #   and have them auto-mapped, and use much simpler custom mappers to adjust
      #   resulting data according to your requirements.
      #
      #   @example
      #     users.map_with(:my_mapper, :my_other_mapper, auto_map: true)
      #
      #   @param [Array<Symbol>] mappers A list of mapper identifiers
      #
      # @return [RelationProxy] A new relation proxy with pipelined relation
      #
      # @api public
      def map_with(*names, **opts)
        if names.size == 1 && names[0].is_a?(Class)
          with(meta: meta.merge(model: names[0]))
        elsif names.size > 1 && names.any? { |name| name.is_a?(Class) }
          raise ArgumentError, 'using custom mappers and a model is not supported'
        else
          if opts[:auto_map]
            mappers = [mapper, *names.map { |name| relation.mappers[name] }]
            mappers.reduce(self) { |a, e| a >> e }
          else
            names.reduce(self) { |a, e| a >> relation.mappers[e] }
{'fraction_non_alphanumeric': 0.09240581429842777, 'fraction_numerical': 0.0011865915158706616, 'mean_word_length': 2.6058823529411765, 'pattern_counts': {'":': 0, '<': 6, '<?xml version=': 0, '>': 22, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4135137', 'n_tokens_mistral': 1923, 'n_tokens_neox': 1890, 'n_words': 590}