Add docs explaining how stub macros work

This commit is contained in:
Michael Miller 2022-03-17 02:18:32 -06:00
parent 4f7a4a3453
commit 751ea77172
No known key found for this signature in database
GPG key ID: AC78B32D30CE34A2

View file

@ -86,49 +86,93 @@ module Spectator
{% raise "stub requires a method definition" if !method.is_a?(Def) %}
{% raise "Cannot stub method with reserved keyword as name - #{method.name}" if method.name.starts_with?("_spectator") || ::Spectator::DSL::RESERVED_KEYWORDS.includes?(method.name.symbolize) %}
{% # Figure out how to call the original implementation of the method being stubbed.
# `#has_method?` is effectively `#responds_to?` for macros and will return true if a type or its ancestors or included modules has a method by a given name.
# To be more strict with searching, `#methods` is inspected to handle overrides and the difference in calling convention.
# If the method is defined in an ancestor, `super` should be used.
# Otherwise, when a method is defined in the current type or a module, `previous_def` should be used.
# Additionally, the block usage is forwarded for methods that accept it.
# Even though `super` and `previous_def` without parameters forward the arguments, they don't forward a block.
%}
{% original = ((@type.methods.includes?(method) || !@type.ancestors.any? { |a| a.methods.includes?(method) }) ? :previous_def : :super).id %}
{% if method.accepts_block?
original = "#{original} { |*_spectator_yargs| yield *_spectator_yargs }".id
end %}
{% # Reconstruct the method signature.
# I wish there was a better way of doing this, but there isn't (at not one that I'm aware of).
# This chunk of code must reconstruct the method signature exactly as it was originally.
# If it doesn't match, it doesn't override the method and the stubbing won't work.
%}
{% if method.visibility != :public %}{{method.visibility.id}}{% end %} def {{method.receiver}}{{method.name}}(
{% for arg, i in method.args %}{% if i == method.splat_index %}*{% end %}{{arg}}, {% end %}
{% if method.double_splat %}**{{method.double_splat}}, {% end %}
{% if method.block_arg %}&{{method.block_arg}}{% elsif method.accepts_block? %}&{% end %}
){% if method.return_type %} : {{method.return_type}}{% end %}{% if !method.free_vars.empty? %} forall {{method.free_vars.splat}}{% end %}
# Capture information about the call.
%args = ::Spectator::Arguments.capture(
{% for arg, i in method.args %}{% if i == method.splat_index %}*{% end %}{{arg.internal_name}}, {% end %}
{% if method.double_splat %}**{{method.double_splat}}{% end %}
)
%call = ::Spectator::MethodCall.new({{method.name.symbolize}}, %args)
# Attempt to find a stub that satisfies the method call and arguments.
# Finding a suitable stub is delegated to the type including the `Stubbable` module.
if %stub = _spectator_find_stub(%call)
# Cast the stub or return value to the expected type.
# This is necessary to match the expected return type of the original method.
{% if !method.abstract? %}
# The method isn't abstract, so we can reference the type it returns without calling it.
%stub.as(::Spectator::TypedStub(typeof({{original}}))).value
{% elsif method.return_type %}
# Attempt to cast the stub to the method's return type.
# If successful, return the value of the stub.
# This is a common usage where the return type is simple and matches the stub type exactly.
if %typed = %stub.as?(::Spectator::TypedStub({{method.return_type}}))
%typed.value
else
# The stub couldn't be easily cast to match the return type.
# Get the value as-is from the stub.
# This will be compiled as a union of all known stubbed value types.
%value = %stub.value
# Attempt to cast the value to the method's return type.
# If successful, which it will be in most cases, return it.
# The caller will receive a properly typed value without unions or other side-effects.
if %cast = %value.as?({{method.return_type}})
%cast
else
# Now we're down to edge cases.
{% if method.return_type.resolve >= Nil %}
# The return type might have "cast" correctly, but the value is nil and the return type is nillable.
# Just return nil in this case.
nil
{% else %}
# The stubbed value was something else entirely and cannot be cast to the return type.
# `<Unknown>` should be replaced with the real type of %value (`%value.class`).
# However, there's some weird bug that causes a segfault when trying to inspect the value.
raise TypeCastError.new("#{_spectator_stubbed_name} received message #{%call} and is attempting to return a <Unknown>, but returned type must be `{{method.return_type}}`.")
{% end %}
end
end
{% else %}
# Stubbed method is abstract and there's no return type annotation.
# Return the value of the stub as-is.
# This may produce a "bloated" union of all known stub types.
%stub.value
{% end %}
else
# A stub wasn't found, invoke the type-specific fallback logic.
{% if !method.abstract? %}
# Pass along the type of the original method and a block to invoke it.
_spectator_stub_fallback(%call, typeof({{original}})) { {{original}} }
{% elsif method.return_type %}
# Stubbed method is abstract, so it can't be called.
# Pass along just the return type annotation.
_spectator_abstract_stub_fallback(%call, {{method.return_type}})
{% else %}
# Stubbed method is abstract and there's no type annotation.
_spectator_abstract_stub_fallback(%call)
{% end %}
end
@ -164,40 +208,79 @@ module Spectator
{% raise "abstract_stub requires a method definition" if !method.is_a?(Def) %}
{% raise "Cannot stub method with reserved keyword as name - #{method.name}" if method.name.starts_with?("_spectator") || ::Spectator::DSL::RESERVED_KEYWORDS.includes?(method.name.symbolize) %}
{% # The logic in this macro follows mostly the same logic from `#stub`.
# The main difference is that this macro cannot access the original method being stubbed.
# It might exist or it might not.
# The method could also be abstract.
# For all intents and purposes, this macro defines logic that doesn't depend on an existing method.
%}
{% # Reconstruct the method signature.
# I wish there was a better way of doing this, but there isn't (at not one that I'm aware of).
# This chunk of code must reconstruct the method signature exactly as it was originally.
# If it doesn't match, it doesn't override the method and the stubbing won't work.
%}
{% if method.visibility != :public %}{{method.visibility.id}}{% end %} def {{method.receiver}}{{method.name}}(
{% for arg, i in method.args %}{% if i == method.splat_index %}*{% end %}{{arg}}, {% end %}
{% if method.double_splat %}**{{method.double_splat}}, {% end %}
{% if method.block_arg %}&{{method.block_arg}}{% elsif method.accepts_block? %}&{% end %}
){% if method.return_type %} : {{method.return_type}}{% end %}{% if !method.free_vars.empty? %} forall {{method.free_vars.splat}}{% end %}
# Capture information about the call.
%args = ::Spectator::Arguments.capture(
{% for arg, i in method.args %}{% if i == method.splat_index %}*{% end %}{{arg.internal_name}}, {% end %}
{% if method.double_splat %}**{{method.double_splat}}{% end %}
)
%call = ::Spectator::MethodCall.new({{method.name.symbolize}}, %args)
# Attempt to find a stub that satisfies the method call and arguments.
# Finding a suitable stub is delegated to the type including the `Stubbable` module.
if %stub = _spectator_find_stub(%call)
{% if method.return_type %}
# Attempt to cast the stub to the method's return type.
# If successful, return the value of the stub.
# This is a common usage where the return type is simple and matches the stub type exactly.
if %typed = %stub.as?(::Spectator::TypedStub({{method.return_type}}))
%typed.value
else
# The stub couldn't be easily cast to match the return type.
# Get the value as-is from the stub.
# This will be compiled as a union of all known stubbed value types.
%value = %stub.value
# Attempt to cast the value to the method's return type.
# If successful, which it will be in most cases, return it.
# The caller will receive a properly typed value without unions or other side-effects.
if %cast = %value.as?({{method.return_type}})
%cast
else
# Now we're down to edge cases.
{% if method.return_type.resolve >= Nil %}
# The return type might have "cast" correctly, but the value is nil and the return type is nillable.
# Just return nil in this case.
nil
{% else %}
# The stubbed value was something else entirely and cannot be cast to the return type.
# `<Unknown>` should be replaced with the real type of %value (`%value.class`).
# However, there's some weird bug that causes a segfault when trying to inspect the value.
raise TypeCastError.new("#{_spectator_stubbed_name} received message #{%call} and is attempting to return a <Unknown>, but returned type must be `{{method.return_type}}`.")
{% end %}
end
end
{% else %}
# Stubbed method is abstract and there's no return type annotation.
# Return the value of the stub as-is.
# This may produce a "bloated" union of all known stub types.
%stub.value
{% end %}
else
# A stub wasn't found, invoke the type-specific fallback logic.
{% if method.return_type %}
# Stubbed method is abstract, so it can't be called.
# Pass along just the return type annotation.
_spectator_abstract_stub_fallback(%call, {{method.return_type}})
{% else %}
# Stubbed method is abstract and there's no type annotation.
_spectator_abstract_stub_fallback(%call)
{% end %}
end