# encoding: utf-8

module Hexx

  # The Null object class.
  #
  # Except for some special cases (see examples below) calling any method
  # returns the +Null+ itself.
  #
  # @note (see Hexx::Null.!)
  # @example (see Hexx::Null.method_missing)
  # @example (see Hexx::Null.new)
  # @example (see Hexx::Null.nil?)
  # @example (see Hexx::Null.eq?)
  # @example (see Hexx::Null.<=>)
  # @example (see Hexx::Null.false?)
  # @example (see Hexx::Null.true?)
  # @example (see Hexx::Null.!)
  # @example (see Hexx::Null.to_a)
  # @example (see Hexx::Null.to_h)
  # @example (see Hexx::Null.to_s)
  # @example (see Hexx::Null.to_i)
  # @example (see Hexx::Null.to_f)
  # @example (see Hexx::Null.to_c)
  # @example (see Hexx::Null.to_r)
  # @example (see Hexx::Null.to_nil)
  class Null
    class << self
      include Comparable

      # The constructor constructs itself.
      #
      # @example The +Null+ object constructs itself.
      #   Null.new
      #   # => Null
      #
      # @return [Class] +Null+.
      def new
        self
      end

      # Checks if +Null+ is equal to other object.
      #
      # @example The +Null+ is equal to +nil+.
      #   Null.eq? nil  # => true
      #   Null.eq? Null # => true
      #
      # @example The +Null+ differs from non-nil
      #   Null.eq? 0     # => false
      #   Null.eq? false # => false
      #
      # @param [Object] other The other object to compare to Null.
      # @return [Boolean] The result of comparison.
      def eq?(other)
        other.nil?
      end

      # Compares the +Null+ to other object.
      #
      # @example The +Null+ is less than non-nil object:
      #   Null < 0     # => true
      #   Null < ""    # => true
      #   Null < false # => true
      #
      # @param [Object] other The other object to compare to Null.
      # @return [-1, 0] The result of comparison.
      def <=>(other)
        other.nil? ? 0 : -1
      end

      # Checks if the +Null+ is nil.
      #
      # @example The +Null+ is nil.
      #   Null.nil? # => true
      #
      # @return [Boolean] +true+.
      def nil?
        true
      end

      # Checks if the +Null+ is falseу.
      #
      # @example The +Null+ is falseу.
      #   Null.false?  # => true
      #
      # @example The +Null+ isn't false in logical operations
      #   false || Null # => Null
      #
      # @return [Boolean] +true+.
      def false?
        true
      end

      # Converts nil to true.
      #
      # @note In Ruby the only objects that are +false+ are +nil+ and +false+.
      #   Use the double bang before any object that may be the +Null+.
      #
      # @example The +Null+ is convertible to +true+.
      #   !Null  # => true
      #
      # @example Use a double bang before objects that may be the +Null+.
      #   Null && true   # => true
      #   !!Null && true # => false
      #
      # @return [Boolean] +true+.
      def !
        true
      end

      # Checks if the +Null+ is truthy.
      #
      # @example The +Null+ isn't truthy.
      #   Null.true?  # => false
      #
      # @example The +Null+ is truthy in logical operations.
      #   true && Null # => Null
      #
      # @return [Boolean] +false+.
      def true?
        false
      end

      # Converts the +Null+ to the empty string.
      #
      # @example The +Null+ is convertible to the empty string.
      #   Null.to_s # => ""
      #
      # @return [String] The empty string.
      def to_s
        ""
      end

      # Converts the +Null+ to +nil+.
      #
      # @example The +Null+ is convertible to +nil+.
      #   Null.to_nil # => nil
      #
      # @return [NilClass] +nil+.
      def to_nil
        nil
      end

      # @!method to_a
      # Converts the +Null+ to the empty array.
      # @example The +Null+ is convertible to the empty array.
      #   Null.to_a # => []
      # @return [Array] the empty array.

      # @!method to_i
      # Converts the +Null+ to zero as an integer.
      # @example The +Null+ is convertible to zero as an integer.
      #   Null.to_i # => 0
      # @return [Integer] zero.

      # @!method to_f
      # Converts the +Null+ to zero as a float.
      # @example The +Null+ is convertible to zero as a float.
      #   Null.to_f # => 0.0
      # @return [Float] zero.

      # @!method to_c
      # Converts the +Null+ to zero as a complex.
      # @example The +Null+ is convertible to zero as a complex.
      #   Null.to_c # => (0+0i)
      # @return [Complex] zero.

      # @!method to_r
      # Converts the +Null+ to zero as a rational.
      # @example The +Null+ is convertible to zero as a rational.
      #   Null.to_c # => (0/1)
      # @return [Rational] zero.

      # Checks if a method defined.
      #
      # @example The +Null+ responds to any object.
      #   Null.respond_to? arbitrary_method
      #   # => true
      #
      # @return [Boolean] +true+.
      def respond_to?(*)
        true
      end

      private

      # @api hide
      # @example An arbitrary method returns the +Null+ itself.
      #   Null.is_an_eagle_owl?  # => Null
      #   Null.is_an_elk?        # => Null
      #   Null.fly               # => Null
      #   # ... etc.
      #
      # @example An arbitrary method called with a block yields the block.
      #   Null.when_fishing { p "I've got it!" }
      #   # => "I've got it!"
      #   # => Null
      #
      def method_missing(name, *args, &block)
        return nil.send(name, *args, &block) if nil.respond_to?(name)
        block.call if block_given?
        self
      end
    end
  end
end