Visibility and Encapsulation

# frozen_string_literal: true

require "shelf"

module Shelf
  # A receipt printed when a book is returned.
  class Receipt
    # No access modifier anywhere: Ruby makes these hooks private by itself.
    def initialize(book) = @book = book

    def initialize_copy(source)
      super
      @book = source.instance_variable_get(:@book)
    end

    def respond_to_missing?(name, include_private = false) = name == :total || super

    def to_s = "Receipt for #{@book.title}"
  end
end

Shelf::Receipt.private_instance_methods(false).sort # => [:initialize, :initialize_copy, :respond_to_missing?]
Shelf::Receipt.public_instance_methods(false).sort # => [:to_s]

author = Shelf::Author.new("Octavia E. Butler")
book = Shelf::Book.new(isbn: Shelf::Isbn.new("9780306406157"), title: "Kindred", author:)
receipt = Shelf::Receipt.new(book)

begin
  receipt.initialize(book)
rescue NoMethodError => e
  e.message # => "private method 'initialize' called for an instance of Shelf::Receipt"
end

receipt.dup.to_s # => "Receipt for Kindred"
receipt.respond_to?(:total) # => true
Object.private_method_defined?(:puts) # => true
Kernel.private_method_defined?(:format) # => true
BasicObject.private_instance_methods(false).sort.first(2) # => [:initialize, :method_missing]

# frozen_string_literal: true

require "shelf"

module Shelf
  # Members with a protected rank: comparable, but the rank is not public API.
  class Patron
    include Comparable

    attr_reader :name

    def initialize(name, loans_count)
      @name = name
      @loans_count = loans_count
    end

    def <=>(other) = other.is_a?(Patron) ? rank <=> other.rank : nil

    protected

    def rank = @loans_count
  end

  class Student < Patron; end
  class Teacher < Patron; end

  # Not a Patron: the same call is rejected.
  class Auditor
    def peek(patron) = patron.rank
  end

  # A module included into Patron: its methods run with a Patron as self.
  module Ranking
    def rank_of(other) = other.rank
  end
  Patron.include(Ranking)
end

ana = Shelf::Student.new("Ana", 4)
ben = Shelf::Teacher.new("Ben", 9)

[ana < ben, ben < ana] # => [true, false]
[ben, ana].min.name # => "Ana"
ana.between?(ana, ben) # => true
ana.rank_of(ben) # => 9

begin
  ana.rank
rescue NoMethodError => e
  e.message # => "protected method 'rank' called for an instance of Shelf::Student"
end

begin
  Shelf::Auditor.new.peek(ana)
rescue NoMethodError => e
  e.message # => "protected method 'rank' called for an instance of Shelf::Student"
end

method_name = :rank
begin
  ana.public_send(method_name)
rescue NoMethodError => e
  e.message # => "protected method 'rank' called for an instance of Shelf::Student"
end

ana.send(method_name) # => 4
ana.respond_to?(:rank) # => false
ana.respond_to?(:rank, true) # => true
Shelf::Patron.protected_instance_methods(false) # => [:rank]
Shelf::Patron.instance_methods(false).sort # => [:<=>, :name, :rank]

# frozen_string_literal: true

module Shelf
  # Every way of choosing a visibility, with the value each call returns (Ruby 3.1+).
  class Stamp
    def by_name = "private by symbol"
    def by_array = "private by array (Ruby 3.0)"
    def pair_one = "private with two names"
    def pair_two = "private with two names"

    private :by_name # => :by_name
    private [:by_array] # => [:by_array]
    private :pair_one, :pair_two # => [:pair_one, :pair_two]

    # The mode switch: affects every `def` that follows, up to the end of the class body.
    private # => nil

    def mode_one = "private from the switch"
    def mode_two = "private from the switch"

    public # => nil

    def visible = "public again"

    # Inline forms take the Symbol that `def` returns.
    private def inline_private = "private, inline" # => :inline_private
    protected def inline_protected = "protected, inline" # => :inline_protected
    public def inline_public = "public, inline" # => :inline_public

    # attr_* return the defined names (Ruby 3.0), so they compose with the modifiers.
    private attr_reader :serial # => [:serial]
    public attr_accessor :label # => [:label, :label=]
  end
end

stamp = Shelf::Stamp
stamp.public_instance_methods(false).sort # => [:inline_public, :label, :label=, :visible]
stamp.protected_instance_methods(false) # => [:inline_protected]
private_names = stamp.private_instance_methods(false).sort
private_names.first(4) # => [:by_array, :by_name, :inline_private, :mode_one]
private_names.last(4) # => [:mode_two, :pair_one, :pair_two, :serial]

# frozen_string_literal: true

require "shelf"

module Shelf
  # A template method: `fee_cents` is a private hook that subclasses override.
  class Pricing
    def quote(days) = "#{format('%<euros>.2f', euros: days * fee_cents / 100.0)} EUR"

    def code = "BASE"

    private

    def fee_cents = 10
  end

  # Overriding a private hook is normal. Without `private` the override is public.
  class WeekendPricing < Pricing
    private

    def fee_cents = 25
  end

  # Here the override is public, so the hook is now part of the API.
  class LeakyPricing < Pricing
    def fee_cents = 50
  end

  # Narrowing an inherited public method: callers of the parent type break.
  class SealedPricing < Pricing
    private :code
  end

  # Widening a private method: `public` copies the entry into the subclass.
  class OpenPricing < Pricing
    public :fee_cents
  end
end

Shelf::Pricing.new.quote(3) # => "0.30 EUR"
Shelf::WeekendPricing.new.quote(3) # => "0.75 EUR"
Shelf::LeakyPricing.new.fee_cents # => 50
Shelf::OpenPricing.new.fee_cents # => 10

begin
  Shelf::SealedPricing.new.code
rescue NoMethodError => e
  e.message # => "private method 'code' called for an instance of Shelf::SealedPricing"
end

Shelf::Pricing.new.code # => "BASE"
Shelf::SealedPricing.instance_method(:code).owner # => Shelf::SealedPricing
Shelf::SealedPricing.private_instance_methods(false) # => [:code]
Shelf::OpenPricing.public_instance_methods(false) # => [:fee_cents]
Shelf::OpenPricing.instance_method(:fee_cents).owner # => Shelf::OpenPricing

# Module#private is itself a private method, so it needs send or class_eval from outside.
begin
  Shelf::Pricing.private(:code)
rescue NoMethodError => e
  e.message # => "private method 'private' called for class Shelf::Pricing"
end

Shelf::Pricing.class_eval { private :code } # => :code
Shelf::Pricing.private_method_defined?(:code) # => true
begin
  Shelf::Pricing.send(:private, :nope)
rescue NameError => e
  e.message # => "undefined method 'nope' for class 'Shelf::Pricing'"
end

# frozen_string_literal: true

require "shelf"
require "singleton"

module Shelf
  # A factory with a private constructor.
  class Barcode
    PREFIX = "SH"

    def self.for_book(book) = new("#{PREFIX}-#{book.isbn}")

    private_class_method :new

    attr_reader :text

    def initialize(text) = @text = text
  end

  # Private class methods are called without a receiver from other class methods.
  class Registry
    def self.reset = clear_all
    def self.snapshot = items.dup

    class << self
      private

      def items = (@items ||= [])
      def clear_all = items.clear
    end

    private_class_method def self.audit = :audited

    def self.run_audit = audit
  end

  # The standard library's Singleton makes `new` private and adds `instance`.
  class Clock
    include Singleton

    def now = Time.at(0).utc.year
  end

  class ManualBarcode < Barcode
    public_class_method :new
  end
end

author = Shelf::Author.new("Ursula K. Le Guin")
book = Shelf::Book.new(isbn: Shelf::Isbn.new("9780306406157"), title: "The Dispossessed", author:)
Shelf::Barcode.for_book(book).text # => "SH-9780306406157"

begin
  Shelf::Barcode.new("x")
rescue NoMethodError => e
  e.message # => "private method 'new' called for class Shelf::Barcode"
end

Shelf::Registry.snapshot # => []
Shelf::Registry.run_audit # => :audited
Shelf::Registry.reset # => []

begin
  Shelf::Registry.items
rescue NoMethodError => e
  e.message # => "private method 'items' called for class Shelf::Registry"
end

Shelf::Clock.instance.equal?(Shelf::Clock.instance) # => true

begin
  Shelf::Clock.new
rescue NoMethodError => e
  e.message # => "private method 'new' called for class Shelf::Clock"
end

# The private `new` is inherited by subclasses until they reopen it.
Shelf::ManualBarcode.new("custom").text # => "custom"
Shelf::Barcode.singleton_class.private_instance_methods(false) # => [:new]
Shelf::Barcode.private_methods(false) # => [:new, :initialize, :inherited]

# A private `new` is a convention, not a lock: allocate, dup, clone and Marshal still make instances.
barcode = Shelf::Barcode.for_book(book)
Shelf::Barcode.allocate.text # => nil
barcode.dup.text # => "SH-9780306406157"
barcode.clone.equal?(barcode) # => false
Marshal.load(Marshal.dump(barcode)).text # => "SH-9780306406157"

# frozen_string_literal: true

module Shelf
  # Constants have their own visibility: private_constant, public_constant, deprecate_constant.
  class Limits
    DEFAULT_DAYS = 14
    MAX_RENEWALS = 3
    SECRET_SALT = "not-a-real-salt"
    OLD_DAYS = 21

    class Helper
      def salt = SECRET_SALT
    end

    private_constant :SECRET_SALT, :Helper
    deprecate_constant :OLD_DAYS

    def self.salt_length = SECRET_SALT.length
    def self.helper = Helper.new
    def describe = "#{DEFAULT_DAYS} days, #{MAX_RENEWALS} renewals, salt #{SECRET_SALT.length}"
  end

  class StrictLimits < Limits
    def bare_reference = SECRET_SALT.length
  end
end

Shelf::Limits.new.describe # => "14 days, 3 renewals, salt 15"
Shelf::Limits.salt_length # => 15
Shelf::StrictLimits.new.bare_reference # => 15
Shelf::Limits.helper.salt # => "not-a-real-salt"
Shelf::Limits.constants.sort # => [:DEFAULT_DAYS, :MAX_RENEWALS, :OLD_DAYS]

begin
  Shelf::Limits::SECRET_SALT
rescue NameError => e
  [e.class, e.name, e.message] # => [NameError, :SECRET_SALT, "private constant Shelf::Limits::SECRET_SALT referenced"]
end

begin
  Shelf::StrictLimits::SECRET_SALT
rescue NameError => e
  e.message # => "private constant Shelf::Limits::SECRET_SALT referenced"
end

Shelf::Limits.const_get(:SECRET_SALT) # => "not-a-real-salt"
Shelf::Limits.const_defined?(:SECRET_SALT) # => true
Shelf::Limits.private_constant(:DEFAULT_DAYS) # => Shelf::Limits
Shelf::Limits.public_constant(:SECRET_SALT) # => Shelf::Limits
Shelf::Limits::SECRET_SALT.length # => 15

# Deprecated constants warn only when the :deprecated category is on (it is off by default).
Warning[:deprecated] = true
Shelf::Limits::OLD_DAYS.succ # => 22
# stderr: e10.rb:54: warning: constant Shelf::Limits::OLD_DAYS is deprecated

# frozen_string_literal: true

require "shelf"

module Shelf
  # module_function: every function is a public singleton method and a private instance method.
  module Slug
    module_function

    def for_title(title) = squeeze(title.downcase.gsub(/[^a-z0-9]+/, "-"))

    def squeeze(text) = text.gsub(/\A-+|-+\z/, "")
  end

  # The same module with explicit names, chosen after the definitions.
  module Dashes
    def dashes(text) = text.tr(" ", "-")
    def internal = :not_a_function

    module_function :dashes # => :dashes
  end

  # extend self: the methods stay public instance methods, and are also singleton methods.
  module Plain
    extend self # rubocop:disable Style/ModuleFunction

    def shout(text) = "#{text.upcase}!"
  end

  class Label
    include Slug

    def initialize(book) = @book = book

    def to_s = for_title(@book.title)
  end
end

author = Shelf::Author.new("Italo Calvino")
book = Shelf::Book.new(isbn: Shelf::Isbn.new("9780306406157"), title: "If on a Winter's Night", author:)

Shelf::Slug.for_title("The Left Hand of Darkness") # => "the-left-hand-of-darkness"
Shelf::Label.new(book).to_s # => "if-on-a-winter-s-night"
Shelf::Slug.singleton_methods.sort # => [:for_title, :squeeze]
Shelf::Slug.private_instance_methods(false).sort # => [:for_title, :squeeze]
Shelf::Dashes.singleton_methods # => [:dashes]
Shelf::Dashes.public_instance_methods(false) # => [:internal]
Shelf::Plain.shout("hey") # => "HEY!"
Shelf::Plain.instance_method(:shout).owner # => Shelf::Plain

begin
  Shelf::Label.new(book).for_title("x")
rescue NoMethodError => e
  e.message # => "private method 'for_title' called for an instance of Shelf::Label"
end

# The built-in modules use the same pattern: Math.sqrt is a singleton method, sqrt a private instance method.
Math.sqrt(16) # => 4.0
Math.private_method_defined?(:sqrt) # => true
ratio = 3.14159
Kernel.format("%05.1f", ratio) # => "003.1"
Kernel.respond_to?(:format) # => true

# module_function copies the method: the two sides are different method objects.
Shelf::Slug.method(:squeeze).owner # => #<Class:Shelf::Slug>
Shelf::Slug.instance_method(:squeeze).owner # => Shelf::Slug

# frozen_string_literal: true

# A method defined at the top level becomes a private instance method of Object.
def banner(text) = "== #{text} =="

banner("Shelf") # => "== Shelf =="
Object.private_method_defined?(:banner) # => true

begin
  "text".banner("x")
rescue NoMethodError => e
  e.message # => "private method 'banner' called for an instance of String"
end

# Every object can call it implicitly, because Object is an ancestor of every class.
class Report
  def title = banner("Report")
end
Report.new.title # => "== Report =="

# `public` and `private` also exist at the top level (as singleton methods of main) and make the next def public.
public def loud(text) = text.upcase
"quiet".loud("hey") # => "HEY"

to_s # => "main"
Object.public_method_defined?(:loud) # => true

# frozen_string_literal: true

module Shelf
  # Something with a private method, a private constant and a hidden instance variable.
  class Vault
    PIN = "0000-not-a-real-pin"
    private_constant :PIN

    def initialize = @opened = 0

    attr_reader :opened

    private

    def open_door(who = "guest")
      @opened += 1
      "opened by #{who}"
    end
  end
end

vault = Shelf::Vault.new
name = :open_door

# Reflection is the first way round the rule: send ignores visibility, public_send honours it.
vault.send(name, "ana") # => "opened by ana"
vault.__send__(name) # => "opened by guest"

begin
  vault.public_send(name)
rescue NoMethodError => e
  e.message # => "private method 'open_door' called for an instance of Shelf::Vault"
end

# A Method object remembers its receiver and calls without any visibility check.
vault.method(name).call("ben") # => "opened by ben"
Shelf::Vault.instance_method(name).bind_call(vault) # => "opened by guest"

begin
  vault.public_method(name)
rescue NameError => e
  e.message # => "method 'open_door' for class 'Shelf::Vault' is private"
end

# Instance variables are reachable by reflection, or by running code with the object as self.
vault.instance_variable_get(:@opened) # => 4
vault.instance_variable_set(:@opened, 100) # => 100
vault.instance_eval { @opened } # => 100
vault.instance_eval { open_door("cara") } # => "opened by cara"
vault.opened # => 101
vault.instance_variables # => [:@opened]

# Reopening the class and class_eval go through the same door.
Shelf::Vault.class_eval { public :open_door }
vault.open_door("dan") # => "opened by dan"

# Constants: const_get ignores private_constant.
Shelf::Vault.const_get(:PIN).length # => 19

# frozen_string_literal: true

require "shelf"

module Shelf
  # One method at each visibility, to compare the reflection API.
  class Probe
    def pub = :pub

    protected def prot = :prot

    private def priv = :priv
  end
end

probe = Shelf::Probe.new
own = ->(list) { list & %i[pub prot priv] }

own.call(probe.methods) # => [:pub, :prot]
own.call(probe.public_methods) # => [:pub]
own.call(probe.protected_methods) # => [:prot]
own.call(probe.private_methods) # => [:priv]
own.call(probe.singleton_methods) # => []

Shelf::Probe.instance_methods(false) # => [:pub, :prot]
Shelf::Probe.public_instance_methods(false) # => [:pub]
Shelf::Probe.protected_instance_methods(false) # => [:prot]
Shelf::Probe.private_instance_methods(false) # => [:priv]

%i[pub prot priv].map { |name| probe.respond_to?(name) } # => [true, false, false]
%i[pub prot priv].map { |name| probe.respond_to?(name, true) } # => [true, true, true]

Shelf::Probe.method_defined?(:prot) # => true
Shelf::Probe.method_defined?(:priv) # => false
Shelf::Probe.public_method_defined?(:pub) # => true
Shelf::Probe.protected_method_defined?(:prot) # => true
Shelf::Probe.private_method_defined?(:priv) # => true
Shelf::Probe.private_method_defined?(:puts) # => true
Shelf::Probe.private_method_defined?(:puts, false) # => false

Shelf::Probe.instance_method(:priv).name # => :priv
probe.public_method(:pub).call # => :pub
Shelf::Probe.public_instance_method(:pub).owner # => Shelf::Probe

# frozen_string_literal: true

require "shelf"

module Shelf
  # Plain object: inspect, pp and error messages print every instance variable.
  class Session
    def initialize(user, token)
      @user = user
      @token = token
    end
  end

  # Ruby 4.0: a private instance_variables_to_inspect hook chooses what inspect shows.
  class QuietSession
    def initialize(user, token)
      @user = user
      @token = token
    end

    private

    def instance_variables_to_inspect = [:@user]
  end

  # State kept only in a closure: there is no instance variable to reach.
  class Counter
    def self.build
      count = 0
      new(-> { count += 1 })
    end

    def initialize(step) = @step = step

    def next = @step.call
  end
end

token = "fake-token"
open = Shelf::Session.new("ana", token)
open.inspect.sub(/0x\h+/, "0x0") # => "#<Shelf::Session:0x0 @user=\"ana\", @token=\"fake-token\">"
quiet = Shelf::QuietSession.new("ana", token)
quiet.inspect.sub(/0x\h+/, "0x0") # => "#<Shelf::QuietSession:0x0 @user=\"ana\">"

counter = Shelf::Counter.build
[counter.next, counter.next] # => [1, 2]
counter.instance_variables # => [:@step]

# Freezing protects against mutation, not against reading.
session = Shelf::Session.new("ben", token).freeze
session.frozen? # => true
session.instance_variable_get(:@user) # => "ben"

begin
  session.instance_variable_set(:@user, "eve")
rescue FrozenError => e
  e.message.include?("fake-token") # => true
end

begin
  quiet.freeze.instance_variable_set(:@user, "eve")
rescue FrozenError => e
  e.message.include?("fake-token") # => false
end

# frozen_string_literal: true

require "shelf"

module Shelf
  # A narrow public interface (checkout, receipt) over private steps, in stepdown order:
  # each private method sits below the first method that calls it.
  class LoanDesk
    Receipt = Data.define(:title, :due_day, :fee_cents)

    attr_reader :catalog

    def initialize(catalog: Catalog.new, today: 1)
      @catalog = catalog
      @today = today
      @lent = {}
    end

    def checkout(book, member: "guest")
      ensure_available(book)
      record_loan(book, member)
      receipt_for(book)
    end

    def lent?(book) = @lent.key?(book.isbn)

    private

    def ensure_available(book)
      raise Shelf::Error, "#{book.title} is already lent" if lent?(book)
    end

    def record_loan(book, member)
      @catalog.add(book)
      @lent[book.isbn] = member
    end

    def receipt_for(book) = Receipt.new(title: book.title, due_day: due_date, fee_cents: daily_fee_cents)

    def due_date = @today + Shelf.config.loan_days

    def daily_fee_cents = 10
  end
end

author = Shelf::Author.new("Ursula K. Le Guin")
book = Shelf::Book.new(isbn: Shelf::Isbn.new("9780306406157"), title: "The Dispossessed", author:)
desk = Shelf::LoanDesk.new

receipt = desk.checkout(book, member: "ana")
receipt.to_h # => {title: "The Dispossessed", due_day: 15, fee_cents: 10}
desk.lent?(book) # => true
desk.public_methods(false).sort # => [:catalog, :checkout, :lent?]
private_names = desk.private_methods(false).sort
private_names.first(3) # => [:daily_fee_cents, :due_date, :ensure_available]
private_names.last(3) # => [:initialize, :receipt_for, :record_loan]

begin
  desk.checkout(book)
rescue Shelf::Error => e
  e.message # => "The Dispossessed is already lent"
end