Creates a new double with an optional name.

Redefine virtually all methods to support stubs.

FIXME Reuse method signature generation code.

Defines a macro to define a double. This produces the standard double keyword that accepts default stubs from the keyword arguments and block body.

Defines a double type. The new type is a sub-class of Double. All methods are stubbable.

The name argument is the new type to define. A simple double with no specific methods can be defined with:

Double.define MyDouble
dbl = MyDouble.new

Simple stubs can be defined via stubs. Each element should be an assignment or type declaration. For instance:

Double.define MyDouble,
  some_method1 : Int32,
  some_method2 : Int32 = 42,
  some_method3 = 42
MyDouble.new.some_method2 # => 42

In the example above, 3 methods are defined. Each return an Int32, but the last two will return 42 by default. The first method will raise UnexpectedMessage unless it is stubbed. All methods will accept any arguments and an optional block.

Additionally, these simple stubs can be defined with named_stubs. These are keyword arguments where the keyword is the method name and its value is the default return value.

Double.define MyDouble,
  some_method1: 1,
  some_method2: 2,
  some_method3: 3,
MyDouble.new.some_method2 # => 2

More complex methods can be defined with a block.

Double.define(MyDouble) do
  def label(arg)
    "Value: #{arg}"
  end
end
MyDouble.new.label(42) # => "Value: 42"

The contents of a method will be used as the default behavior.

Simple and complex methods can be mixed.

Double.define(MyDouble, some_method1 = 42, some_method2: 42) do
  def label(arg)
    "Value: #{arg}"
  end
end

The contents of the block are dumped as-is into the class body of the double. This allows for more complex behavior if needed.

Double.define(MyDouble) do
  getter accumulator = 0

  def add(amount)
    @accumulator += amount
  end
end

Returns true if this object is not equal to other.

By default this method is implemented as !(self == other) so there's no need to override this unless there's a more efficient way to do it.

Shortcut to !(self =~ other).

Returns true if this reference is the same as other. Invokes #same?.

Returns false (other can only be a Value here).

Case equality.

The #=== method is used in a case ... when ... end expression.

For example, this code:

case value
when x
  # something when x
when y
  # something when y
end

Is equivalent to this code:

if x === value
  # something when x
elsif y === value
  # something when y
end

Object simply implements #=== by invoking #==, but subclasses (notably Regex) can override it to provide meaningful case-equality semantics.

Pattern match.

Overridden by descendants (notably Regex and String) to provide meaningful pattern-match semantics.

Creates a null object wrapper for the current double.

Returns a shallow copy of this object.

This allocates a new object and copies the contents of self into it.

See Object#hash(hasher)

Generates an UInt64 hash value for this object.

This method must have the property that a == b implies a.hash == b.hash.

The hash value is used along with #== by the Hash class to determine if two objects reference the same hash key.

Subclasses must not override this method. Instead, they must define #hash(hasher), though usually the macro def_hash can be used to generate this method.

Returns true if self is included in the collection argument.

10.in?(0..100)     # => true
10.in?({0, 1, 10}) # => true
10.in?(0, 1, 10)   # => true
10.in?(:foo, :bar) # => false

Returns true if self is included in the collection argument.

10.in?(0..100)     # => true
10.in?({0, 1, 10}) # => true
10.in?(0, 1, 10)   # => true
10.in?(:foo, :bar) # => false

Appends a String representation of this object which includes its class name, its object address and the values of all instance variables.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).inspect # => #<Person:0x10fd31f20 @name="John", @age=32>

Returns an unambiguous and information-rich string representation of this object, typically intended for developers.

This method should usually not be overridden. It delegates to #inspect(IO) which can be overridden for custom implementations.

Also see #to_s.

Returns self.

str = "hello"
str.itself.object_id == str.object_id # => true

Returns self.

Nil overrides this method and raises NilAssertionError, see Nil#not_nil!.

This method can be used to remove Nil from a union type. However, it should be avoided if possible and is often considered a code smell. Usually, you can write code in a way that the compiler can safely exclude Nil types, for example using if var. #not_nil! is only meant as a last resort when there's no other way to explain this to the compiler. Either way, consider instead raising a concrete exception with a descriptive message.

message has no effect. It is only used by Nil#not_nil!(message = nil).

Returns self.

Nil overrides this method and raises NilAssertionError, see Nil#not_nil!.

This method can be used to remove Nil from a union type. However, it should be avoided if possible and is often considered a code smell. Usually, you can write code in a way that the compiler can safely exclude Nil types, for example using if var. #not_nil! is only meant as a last resort when there's no other way to explain this to the compiler. Either way, consider instead raising a concrete exception with a descriptive message.

Returns a pretty printed version of self.

Pretty prints self into the given printer.

By default appends a text that is the result of invoking #inspect on self. Subclasses should override for custom pretty printing.

Returns true if this reference is the same as other. This is only true if this reference's object_id is the same as other's.

Returns false: a reference is never nil.

Yields self to the block, and then returns self.

The primary purpose of this method is to "tap into" a method chain, in order to perform operations on intermediate results within the chain.

(1..10).tap { |x| puts "original: #{x.inspect}" }
  .to_a.tap { |x| puts "array: #{x.inspect}" }
  .select { |x| x % 2 == 0 }.tap { |x| puts "evens: #{x.inspect}" }
  .map { |x| x*x }.tap { |x| puts "squares: #{x.inspect}" }

Constructs a string representation of the double.

Returns a nicely readable and concise string representation of this object, typically intended for users.

This method should usually not be overridden. It delegates to #to_s(IO) which can be overridden for custom implementations.

Also see #inspect.

Yields self. Nil overrides this method and doesn't yield.

This method is useful for dealing with nilable types, to safely perform operations only when the value is not nil.

# First program argument in downcase, or nil
ARGV[0]?.try &.downcase

Unsafely reinterprets the bytes of an object as being of another type.

This method is useful to treat a type that is represented as a chunk of bytes as another type where those bytes convey useful information. As an example, you can check the individual bytes of an Int32:

0x01020304.unsafe_as(StaticArray(UInt8, 4)) # => StaticArray[4, 3, 2, 1]

Or treat the bytes of a Float64 as an Int64:

1.234_f64.unsafe_as(Int64) # => 4608236261112822104

This method is unsafe because it behaves unpredictably when the given type doesn't have the same bytesize as the receiver, or when the given type representation doesn't semantically match the underlying bytes.

Also note that because #unsafe_as is a regular method, unlike the pseudo-method as, you can't specify some types in the type grammar using a short notation, so specifying a static array must always be done as StaticArray(T, N), a tuple as Tuple(...) and so on, never as UInt8[4] or {Int32, Int32}.