<commit_before># frozen_string_literal: true

module Fear
  # Represents a value of one of two possible types (a disjoint union.)
  # An instance of +Either+ is either an instance of +Left+ or +Right+.
  #
  # A common use of +Either+ is as an alternative to +Option+ for dealing
  # with possible missing values.  In this usage, +None+ is replaced
  # with a +Left+ which can contain useful information.
  # +Right+ takes the place of +Some+. Convention dictates
  # that +Left+ is used for failure and +Right+ is used for Right.
  #
  # For example, you could use +Either<String, Fixnum>+ to select_or_else whether a
  # received input is a +String+ or an +Fixnum+.
  #
  # @example
  #   in = Readline.readline('Type Either a string or an Int: ', true)
  #   result = begin
  #     Fear.right(Integer(in))
  #   rescue ArgumentError
  #     Fear.left(in)
  #   end
  #
  #   result.match do |m|
  #     m.right do |x|
  #       "You passed me the Int: #{x}, which I will increment. #{x} + 1 = #{x+1}"
  #     end
  #
  #     m.left do |x|
  #       "You passed me the String: #{x}"
  #     end
  #   end
  #
  # Either is right-biased, which means that +Right+ is assumed to be the default case to
  # operate on. If it is +Left+, operations like +#map+, +#flat_map+, ... return the +Left+ value
  # unchanged:
  #
  # @!method get_or_else(*args)
  #   Returns the value from this +Right+ or evaluates the given
  #   default argument if this is a +Left+.
  #   @overload get_or_else(&default)
  #     @yieldreturn [any]
  #     @return [any]
  #     @example
  #       Fear.right(42).get_or_else { 24/2 }         #=> 42
  #       Fear.left('undefined').get_or_else { 24/2 } #=> 12
  #   @overload get_or_else(default)
  #     @return [any]
  #     @example
  #       Fear.right(42).get_or_else(12)         #=> 42
  #       Fear.left('undefined').get_or_else(12) #=> 12
  #
  # @!method or_else(&alternative)
  #   Returns this +Right+ or the given alternative if this is a +Left+.
  #   @return [Either]
  #   @example
  #     Fear.right(42).or_else { Fear.right(21) }           #=> Fear.right(42)
  #     Fear.left('unknown').or_else { Fear.right(21) }     #=> Fear.right(21)
  #     Fear.left('unknown').or_else { Fear.left('empty') } #=> Fear.left('empty')
  #
  # @!method include?(other_value)
  #   Returns +true+ if +Right+ has an element that is equal
  #   (as determined by +==+) to +other_value+, +false+ otherwise.
  #   @param [any]
  #   @return [Boolean]
  #   @example
  #     Fear.right(17).include?(17)         #=> true
  #     Fear.right(17).include?(7)          #=> false
  #     Fear.left('undefined').include?(17) #=> false
  #
  # @!method each(&block)
  #   Performs the given block if this is a +Right+.
  #   @yieldparam [any] value
  #   @yieldreturn [void]
  #   @return [Option] itself
  #   @example
  #     Fear.right(17).each do |value|
  #       puts value
  #     end #=> prints 17
  #
  #     Fear.left('undefined').each do |value|
  #       puts value
  #     end #=> does nothing
  #
  # @!method map(&block)
  #   Maps the given block to the value from this +Right+ or
  #   returns this if this is a +Left+.
  #   @yieldparam [any] value
  #   @yieldreturn [any]
  #   @example
  #     Fear.right(42).map { |v| v/2 }          #=> Fear.right(21)
  #     Fear.left('undefined').map { |v| v/2 }  #=> Fear.left('undefined')
  #
  # @!method flat_map(&block)
  #   Returns the given block applied to the value from this +Right+
  #   or returns this if this is a +Left+.
  #   @yieldparam [any] value
  #   @yieldreturn [Option]
  #   @return [Option]
  #   @example
  #     Fear.right(42).flat_map { |v| Fear.right(v/2) }         #=> Fear.right(21)
  #     Fear.left('undefined').flat_map { |v| Fear.right(v/2) } #=> Fear.left('undefined')
  #
  # @!method to_option
  #   Returns an +Some+ containing the +Right+ value or a +None+ if
  #   this is a +Left+.
  #   @return [Option]
  #   @example
  #     Fear.right(42).to_option          #=> Fear.some(42)
  #     Fear.left('undefined').to_option  #=> Fear.none()
  #
  # @!method any?(&predicate)
  #   Returns +false+ if +Left+ or returns the result of the
  #   application of the given predicate to the +Right+ value.
  #   @yieldparam [any] value
  #   @yieldreturn [Boolean]
  #   @return [Boolean]
  #   @example
  #     Fear.right(12).any?( |v| v > 10)         #=> true
  #     Fear.right(7).any?( |v| v > 10)          #=> false
  #     Fear.left('undefined').any?( |v| v > 10) #=> false
  #
  # -----
  #
  # @!method right?
  #   Returns +true+ if this is a +Right+, +false+ otherwise.
  #   @note this method is also aliased as +#success?+<commit_msg>Fix typos in either docs (#140)<commit_after># frozen_string_literal: true

module Fear
  # Represents a value of one of two possible types (a disjoint union.)
  # An instance of +Either+ is either an instance of +Left+ or +Right+.
  #
  # A common use of +Either+ is as an alternative to +Option+ for dealing
  # with possible missing values.  In this usage, +None+ is replaced
  # with a +Left+ which can contain useful information.
  # +Right+ takes the place of +Some+. Convention dictates
  # that +Left+ is used for failure and +Right+ is used for Right.
  #
  # For example, you could use +Either<String, Fixnum>+ to select_or_else whether a
  # received input is a +String+ or an +Fixnum+.
  #
  # @example
  #   in = Readline.readline('Type Either a string or an Int: ', true)
  #   result = begin
  #     Fear.right(Integer(in))
  #   rescue ArgumentError
  #     Fear.left(in)
  #   end
  #
  #   result.match do |m|
  #     m.right do |x|
  #       "You passed me the Int: #{x}, which I will increment. #{x} + 1 = #{x+1}"
  #     end
  #
  #     m.left do |x|
  #       "You passed me the String: #{x}"
  #     end
  #   end
  #
  # Either is right-biased, which means that +Right+ is assumed to be the default case to
  # operate on. If it is +Left+, operations like +#map+, +#flat_map+, ... return the +Left+ value
  # unchanged:
  #
  # @!method get_or_else(*args)
  #   Returns the value from this +Right+ or evaluates the given
  #   default argument if this is a +Left+.
  #   @overload get_or_else(&default)
  #     @yieldreturn [any]
  #     @return [any]
  #     @example
  #       Fear.right(42).get_or_else { 24/2 }         #=> 42
  #       Fear.left('undefined').get_or_else { 24/2 } #=> 12
  #   @overload get_or_else(default)
  #     @return [any]
  #     @example
  #       Fear.right(42).get_or_else(12)         #=> 42
  #       Fear.left('undefined').get_or_else(12) #=> 12
  #
  # @!method or_else(&alternative)
  #   Returns this +Right+ or the given alternative if this is a +Left+.
  #   @return [Either]
  #   @example
  #     Fear.right(42).or_else { Fear.right(21) }           #=> Fear.right(42)
  #     Fear.left('unknown').or_else { Fear.right(21) }     #=> Fear.right(21)
  #     Fear.left('unknown').or_else { Fear.left('empty') } #=> Fear.left('empty')
  #
  # @!method include?(other_value)
  #   Returns +true+ if +Right+ has an element that is equal
  #   (as determined by +==+) to +other_value+, +false+ otherwise.
  #   @param [any]
  #   @return [Boolean]
  #   @example
  #     Fear.right(17).include?(17)         #=> true
  #     Fear.right(17).include?(7)          #=> false
  #     Fear.left('undefined').include?(17) #=> false
  #
  # @!method each(&block)
  #   Performs the given block if this is a +Right+.
  #   @yieldparam [any] value
  #   @yieldreturn [void]
  #   @return [Fear::Either] itself
  #   @example
  #     Fear.right(17).each do |value|
  #       puts value
  #     end #=> prints 17
  #
  #     Fear.left('undefined').each do |value|
  #       puts value
  #     end #=> does nothing
  #
  # @!method map(&block)
  #   Maps the given block to the value from this +Right+ or
  #   returns this if this is a +Left+.
  #   @yieldparam [any] value
  #   @yieldreturn [any]
  #   @example
  #     Fear.right(42).map { |v| v/2 }          #=> Fear.right(21)
  #     Fear.left('undefined').map { |v| v/2 }  #=> Fear.left('undefined')
  #
  # @!method flat_map(&block)
  #   Returns the given block applied to the value from this +Right+
  #   or returns this if this is a +Left+.
  #   @yieldparam [any] value
  #   @yieldreturn [Fear::Either]
  #   @return [Fear::Either]
  #   @example
  #     Fear.right(42).flat_map { |v| Fear.right(v/2) }         #=> Fear.right(21)
  #     Fear.left('undefined').flat_map { |v| Fear.right(v/2) } #=> Fear.left('undefined')
  #
  # @!method to_option
  #   Returns an +Some+ containing the +Right+ value or a +None+ if
  #   this is a +Left+.
  #   @return [Option]
  #   @example
  #     Fear.right(42).to_option          #=> Fear.some(42)
  #     Fear.left('undefined').to_option  #=> Fear.none()
  #
  # @!method any?(&predicate)
  #   Returns +false+ if +Left+ or returns the result of the
  #   application of the given predicate to the +Right+ value.
  #   @yieldparam [any] value
  #   @yieldreturn [Boolean]
  #   @return [Boolean]
  #   @example
  #     Fear.right(12).any?( |v| v > 10)         #=> true
  #     Fear.right(7).any?( |v| v > 10)          #=> false
  #     Fear.left('undefined').any?( |v| v > 10) #=> false
  #
  # -----
  #
  # @!method right?
  #   Returns +true+ if this is a +Right+, +false+ otherwise.
  #   @note this method is also aliased as +#success?+
{'fraction_non_alphanumeric': 0.1532119914346895, 'fraction_numerical': 0.015738758029978588, 'mean_word_length': 2.482848620432513, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 53, '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': '1156843', 'n_tokens_mistral': 3493, 'n_tokens_neox': 3322, 'n_words': 940}