Conversions and Coercion

# frozen_string_literal: true

require "shelf"

module Shelf
  # A URL-friendly name that can stand in for a String.
  class Slug
    def initialize(text) = @text = text.downcase.tr(" ", "-")

    # Implicit: "I am a String", used when a method needs one.
    def to_str = @text

    # Explicit: how to display me.
    def to_s = "Slug(#{@text})"
  end
end

slug = Shelf::Slug.new("Moby Dick")
prefix = "title: "
p prefix + slug # => "title: moby-dick"
p "slug is #{slug}" # => "slug is Slug(moby-dick)"
String(slug) # => "moby-dick"
File.join("books", slug) # => "books/moby-dick"
["books", slug].join("/") # => "books/moby-dick"
"moby-dick-2".start_with?(slug) # => true
"moby-dick".include?(slug) # => true
{ "moby-dick" => 1 }[slug] # => nil
text = "moby-dick"
p text == slug # => false
text.eql?(slug) # => false

# Shelf::Isbn has to_s but deliberately no to_str.
isbn = Shelf::Isbn.new(digits: "978-0-306-40615-7")
p "ISBN #{isbn}" # => "ISBN 9780306406157"
prefix = "ISBN "
p prefix + isbn # raises TypeError: no implicit conversion of Shelf::Isbn into String
p prefix + :symbol # raises TypeError: no implicit conversion of Symbol into String

# A to_s that returns a non-String is ignored, without an error.
broken = Object.new
def broken.to_s = 42
"value: #{broken}".sub(/0x\h+/, "0x...") # => "value: #<Object:0x...>"

# frozen_string_literal: true

module Shelf
  # Behaves like an Array of titles wherever Ruby asks for one.
  class ReadingList
    def initialize(*titles) = @titles = titles

    def to_ary = @titles
  end

  # Behaves like a Hash of search options wherever Ruby asks for one.
  class Filters
    def initialize(**options) = @options = options

    def to_hash = @options
  end
end

list = Shelf::ReadingList.new("Dune", "Emma")
first, second = list
[first, second] # => ["Dune", "Emma"]
p ["Ulysses"] + list # => ["Ulysses", "Dune", "Emma"]
[list, ["Ulysses"]].flatten # => ["Dune", "Emma", "Ulysses"]
[list].map { |a, b| "#{a}/#{b}" } # => ["Dune/Emma"]
%w[a b].zip(list) # => [["a", "Dune"], ["b", "Emma"]]
Array(list) # => ["Dune", "Emma"]
list.to_a # raises NoMethodError: undefined method 'to_a' for an instance of Shelf::ReadingList
[*list].size # => 1

def search(author: nil, available: true) = [author, available]

filters = Shelf::Filters.new(author: "Le Guin")
search(**filters) # => ["Le Guin", true]
{ available: false }.merge(filters) # => {available: false, author: "Le Guin"}
search(filters) # raises ArgumentError: wrong number of arguments (given 1, expected 0)

# frozen_string_literal: true

require "shelf"

module Shelf
  # A number of copies that can be used where Ruby asks for an Integer.
  class Copies
    def initialize(count) = @count = count

    def to_int = @count
  end

  # A reusable predicate: &by_author calls to_proc on it.
  class ByAuthor
    def initialize(name) = @name = name

    def to_proc = ->(book) { book.author.name == @name }
  end
end

copies = Shelf::Copies.new(2)
%w[a b c][copies] # => "c"
Array.new(copies, "Dune") # => ["Dune", "Dune"]
p "ab" * copies # => "abab"
Integer(copies) # => 2
[1, 2, 3].first(copies) # => [1, 2]
p 3 + copies # raises TypeError: Shelf::Copies can't be coerced into Integer

def book(isbn, title, author) = Shelf::Book.new(Shelf::Isbn.new(digits: isbn), title, Shelf::Author.new(author))

books = [
  book("978-0-306-40615-7", "Notes", "Ada Lovelace"),
  book("978-0-13-235088-4", "Engines", "Charles Babbage")
]
books.select(&Shelf::ByAuthor.new("Ada Lovelace")).map(&:title) # => ["Notes"]

# The built-in implementers of to_proc.
%w[a b].map(&:upcase) # => ["A", "B"]
%w[1 2].map(&method(:Integer)) # => [1, 2]
%i[a b].map(&{ a: 1, b: 2 }) # => [1, 2]
:upcase.to_proc.lambda? # => true
[1, 2].each(&5) # raises TypeError: no implicit conversion of Integer into Proc

# frozen_string_literal: true

tag = Object.new
def tag.to_str = "fiction"

tag2 = Object.new
def tag2.to_int = 3

String.try_convert(tag) # => "fiction"
String.try_convert(:fiction) # => nil
Array.try_convert([1]) # => [1]
Array.try_convert(1..2) # => nil
Hash.try_convert([[1, 2]]) # => nil
Integer.try_convert(tag2) # => 3
Integer.try_convert(1.9) # => 1
Integer.try_convert("1") # => nil
Regexp.try_convert("a+") # => nil
IO.try_convert($stdin).equal?($stdin) # => true

# The idiom behind Kernel#Array, written by hand: a value or a list of values.
def titles_of(value) = Array.try_convert(value) || [value]

titles_of("Dune") # => ["Dune"]
titles_of(%w[Dune Emma]) # => ["Dune", "Emma"]
titles_of(Struct.new(:x, :y).new(1, 2)).size # => 1
Array(Struct.new(:x, :y).new(1, 2)).size # => 2

# respond_to? is the duck-typing check; it is true for both protocols.
[tag.respond_to?(:to_str), :fiction.respond_to?(:to_str), tag2.respond_to?(:to_int)] # => [true, false, true]

# frozen_string_literal: true

# Integer(): strict parsing of Strings, truncation of numbers.
Integer("42") # => 42
Integer(" 42\n") # => 42
Integer("12_000") # => 12000
Integer("-0b11") # => -3
Integer("0x1A") # => 26
Integer("0o17") # => 15
Integer("017") # => 15
Integer("ff", 16) # => 255
Integer("0x1A", 16) # => 26
Integer("zz", 36) # => 1295
Integer("08", 10) # => 8
Integer(3.99) # => 3
Integer(-3.99) # => -3
Integer("12abc") # raises ArgumentError: invalid value for Integer(): "12abc"
Integer("08") # raises ArgumentError: invalid value for Integer(): "08"
Integer("1e3") # raises ArgumentError: invalid value for Integer(): "1e3"
Integer("4 2") # raises ArgumentError: invalid value for Integer(): "4 2"
Integer("") # raises ArgumentError: invalid value for Integer(): ""
Integer("12", 1) # raises ArgumentError: invalid radix 1
Integer(nil) # raises TypeError: can't convert nil into Integer
Integer([1]) # raises TypeError: can't convert Array into Integer
Integer(Float::NAN) # raises FloatDomainError: NaN
Integer(Float::INFINITY) # raises FloatDomainError: Infinity

# exception: false turns the failures above into nil.
Integer("abc", exception: false) # => nil
Integer(nil, exception: false) # => nil
Integer("12", exception: false) # => 12

# frozen_string_literal: true

# Float(): the same strictness for decimal text.
Float("1e3") # => 1000.0
Float("1_000.5") # => 1000.5
Float("  2.5  ") # => 2.5
Float(".5") # => 0.5
Float("1.") # => 1.0
Float("0x1p3") # => 8.0
Float(3) # => 3.0
Float("3.7kg") # raises ArgumentError: invalid value for Float(): "3.7kg"
Float("") # raises ArgumentError: invalid value for Float(): ""
Float(nil) # raises TypeError: can't convert nil into Float
Float("abc", exception: false) # => nil

# String(): to_str first, then to_s. It never fails for ordinary objects.
String(nil) # => ""
String(12) # => "12"
String(:title) # => "title"
String([1, 2]) # => "[1, 2]"

# Array(): to_ary first, then to_a, otherwise a one-element Array.
Array(nil) # => []
list = [1, 2]
Array(list).equal?(list) # => true
Array(1) # => [1]
Array(1..3) # => [1, 2, 3]
Array("a\nb") # => ["a\nb"]
Array({ a: 1 }) # => [[:a, 1]]
Array(Struct.new(:x, :y).new(1, 2)) # => [1, 2]

# Hash(): nil and [] become {}, a Hash stays, everything else is an error.
Hash(nil) # => {}
empty = []
Hash(empty) # => {}
Hash({ a: 1 }) # => {a: 1}
Hash([[1, 2]]) # raises TypeError: can't convert Array into Hash
Hash(1) # raises TypeError: can't convert Integer into Hash
Hash([[1, 2]], exception: false) # raises ArgumentError: wrong number of arguments (given 2, expected 1)

# frozen_string_literal: true

# Rational() and Complex() parse text and combine integers.
Rational("1/3") # => (1/3)
Rational("0.75") # => (3/4)
Rational(" 1/3 ") # => (1/3)
Rational(1, 3) # => (1/3)
Rational("abc") # raises ArgumentError: invalid value for convert(): "abc"
Rational(nil) # raises TypeError: can't convert nil into Rational
Rational(1, 0) # raises ZeroDivisionError: divided by 0
Rational("abc", exception: false) # => nil
Rational(nil, exception: false) # => nil
Complex("1+2i") # => (1+2i)
Complex("x", exception: false) # => nil

# A Float carries its binary error into the Rational; text does not.
Rational(0.1) # => (3602879701896397/36028797018963968)
Rational("0.1") # => (1/10)
[0.1 + 0.2, Rational("0.1") + Rational("0.2")] # => [0.30000000000000004, (3/10)]

# frozen_string_literal: true

# Reading a loan period from the environment: a default for absent input,
# an error for input that is present but wrong.
DEFAULT_LOAN_DAYS = 14

def loan_days_lenient(text) = text.to_i.nonzero? || DEFAULT_LOAN_DAYS

def loan_days_strict(text)
  return DEFAULT_LOAN_DAYS if text.nil? || text.strip.empty?

  days = Integer(text, 10, exception: false)
  raise ArgumentError, "SHELF_LOAN_DAYS must be a positive whole number, got #{text.inspect}" unless days&.positive?

  days
end

loan_days_lenient("21") # => 21
loan_days_lenient("3 weeks") # => 3
loan_days_lenient("three") # => 14
loan_days_strict("21") # => 21
loan_days_strict("08") # => 8
loan_days_strict(nil) # => 14
loan_days_strict("  ") # => 14
loan_days_strict("3 weeks") # raises ArgumentError: SHELF_LOAN_DAYS must be a positive whole number, got "3 weeks"
loan_days_strict("-2") # raises ArgumentError: SHELF_LOAN_DAYS must be a positive whole number, got "-2"
loan_days_strict(ENV.fetch("SHELF_LOAN_DAYS", nil)) # => 14

# frozen_string_literal: true

module Shelf
  # Three ways to guard a parameter that must be a number of days.
  module Guards
    # By class: strict, rejects 14.0 and every duck.
    def self.by_class(days)
      raise ArgumentError, "days must be an Integer, got #{days.inspect}" unless days.is_a?(Integer)

      days
    end

    # By capability: accepts anything with an implicit integer conversion.
    def self.by_duck(days)
      raise ArgumentError, "days must respond to to_int, got #{days.inspect}" unless days.respond_to?(:to_int)

      days.to_int
    end

    # By conversion: accepts text as well and lets Ruby produce the error.
    def self.by_conversion(days) = Integer(days, exception: false) || raise(ArgumentError, "bad days: #{days.inspect}")
  end
end

Shelf::Guards.by_class(14) # => 14
Shelf::Guards.by_class(14.0) # raises ArgumentError: days must be an Integer, got 14.0
Shelf::Guards.by_duck(14.9) # => 14
Shelf::Guards.by_duck("14") # raises ArgumentError: days must respond to to_int, got "14"
Shelf::Guards.by_conversion("14") # => 14
Shelf::Guards.by_conversion(14.9) # => 14
Shelf::Guards.by_conversion("two") # raises ArgumentError: bad days: "two"
Shelf::Guards.by_conversion(nil) # raises ArgumentError: bad days: nil

# frozen_string_literal: true

# A coerce that returns [self, number] is only right for commutative operators.
Quantity = Struct.new(:value) do
  def -(other) = value - other

  def coerce(number) = [self, number]
end

quantity = Quantity.new(3)
p quantity - 10 # => -7
[10 - quantity] # => [-7]

# frozen_string_literal: true

# What Integer#+ does with a right operand that has a broken coerce.
not_a_pair = Object.new
def not_a_pair.coerce(_number) = :nope

wrong_size = Object.new
def wrong_size.coerce(number) = [number]

raises = Object.new
def raises.coerce(_number) = raise(ArgumentError, "no way")

returns_nil = Object.new
def returns_nil.coerce(_number) = nil

p 1 + not_a_pair # raises TypeError: coerce must return [x, y]
p 1 + wrong_size # raises TypeError: coerce must return [x, y]
p 1 + raises # raises ArgumentError: no way
p 1 + returns_nil # raises TypeError: coerce must return [x, y]
p 1 + Object.new # raises TypeError: Object can't be coerced into Integer