Ruby In Steel :: Help Index :: SapphireSteel Software Front Page Return to the Index
Type Assertions
See Also

Glossary Item Box

Type Assertions are declarations of the expected types of parameters sent to a method and the return type of the method. These assertions are entirely optional. They are placed in a comment block immediately preceding a method and have no impact upon the meaning of the Ruby code itself. In other words, Type Assertions give you extra features when you are developing with Ruby In Steel but they have no effect on the code as far as the Ruby interpreter or any other editor or IDE is concerned.

When a method is preceded by type assertions, Ruby In Steel's Parameter Info tooltips are able to display information on the asserted parameter and return types, helping to resolve ambiguities and avoid accidental coding errors. Consider, for example, this method:

def addName( names, aName  )
     return names << aName
end

It is, in principle, impossible to determine the types of the parameters, names and aName, or the class of the return value. Even the << is not a sufficient clue as this is defined for many different classes in Ruby. Consequently, the addName() method could legally be called in the following ways, in each case both the parameter and the return types being different:

addName( "Fred,Mary,", "Simon" )
addName( ["Fred","Mary"], "Simon" )
addName( ["Fred","Mary"], ["Simon"] )
addName( 123, 456 )

But let's suppose that the programmer who wrote the addNames() method had done so with the specific intention that the first parameter, names, should always be an array, the second parameter, aName should always be a string and the returned value should always be an array. The programmer could, of course, document this fact somewhere – but there is no guarantee that the person calling the method will ever read the documentation. By using Type Assertions you can bind your documentation to Ruby In Steel's IntelliSense.

Making Type Assertions

Type assertions are entered into a comment block immediately above a method. The assertion may include a return type and one or more arguments matching the argument list. 

The syntax for assertions can be summarized like this:

# :return: => <ReturnType>
# :arg: <ArgName> => <ArgType>
# <Optionally More Args...>

When no return type is given, NilClass is assumed. The argument assertions should be entered in the same order as the actual parameters. The names of arguments used in the assertions will be used by IntelliSense even if those names differ from those used in the actual parameter list. If more arguments are asserted than actually exist, the superfluous assertions are ignored. If fewer arguments are asserted than actually exist, the extra arguments will default to Object when there is a return value and to NilClass when there is no return value..

Example:

#:return:=>Array
#:arg:names=>Array
#:arg:aName=>String
def addName( names, aName  )
   return names << aName
end

Given the assertions above, the parameter info will now show the following:

assertions in prameter info tooltip

Type assertion comment blocks can be created automatically by entering two # characters over a method. See: Automating Type Assertions

See Also