Appendix C: Decorated Methods
A method whose name begins with @ is called by the runtime when a piece
of syntax is applied to an instance of its class. They are ordinary
methods otherwise: inherited, overridable, and callable by name.
See Decorated Methods for the guided treatment, and Class Extensions for adding one to a class you did not write.
Construction
| Decorator | Called by | Signature |
|---|---|---|
@new | ClassName(...) | @new(...args) |
@new is the only place self.x = value may declare a field that was not
declared with var.
Arithmetic
| Decorator | Operator | Signature |
|---|---|---|
@add | a + b | @add(other) |
@sub | a - b | @sub(other) |
@mul | a * b | @mul(other) |
@div | a / b | @div(other) |
@floordiv | a // b | @floordiv(other) |
@mod | a % b | @mod(other) |
@pow | a ** b | @pow(other) |
@neg | -a | @neg() |
Bitwise
| Decorator | Operator | Signature |
|---|---|---|
@and | a & b | @and(other) |
@or | a | b | @or(other) |
@xor | a ^ b | @xor(other) |
@not | ~a | @not() |
@lshift | a << b | @lshift(other) |
@rshift | a >> b | @rshift(other) |
@urshift | a >>> b | @urshift(other) |
@not is bound to ~, the bitwise complement. ! is logical negation and
is not overridable: an instance is always truthy, so !instance is always
false.
Comparison
| Decorator | Operator | Signature |
|---|---|---|
@eq | a == b, a != b | @eq(other) |
@lt | a < b | @lt(other) |
@lte | a <= b | @lte(other) |
@gt | a > b | @gt(other) |
@gte | a >= b | @gte(other) |
!= is the negation of @eq. @eq runs only when the right operand is
an object too, so x == nil never calls it, and it must return a bool.
Lists, dictionaries, contains() and index_of() compare instances by
identity whether or not the class defines it.
Iteration
| Decorator | Called by | Signature |
|---|---|---|
@key | for ... in | @key(previous) |
@value | for ... in | @value(key) |
@key(previous) receives the previous key, starting from nil, and
returns the next one or nil when the sequence is finished. @value(key)
returns what is stored at that key.
Defining both is what makes is_iterable() return true for the class.
Display
| Decorator | Called by | Signature |
|---|---|---|
@to_string | echo, print() | @to_string() |
@to_string() returns the text shown for the instance, including when it
sits inside a list or dictionary being shown, as a key or as a value. It
must return a string; anything else raises a TypeError. Without it, an
instance shows as <instance of ClassName>.
Serialisation
| Decorator | Called by | Signature |
|---|---|---|
@to_json | json.encode() | @to_json() |
Returns whatever should be encoded in the instance’s place, which is where you decide what does and does not cross the wire.
Not a Decorator
to_string() has no @. It is a real method every value already carries,
and a class may override it.
Nothing calls it implicitly. String interpolation and + render an
instance as <instance of ClassName>, and echo and print() use
@to_string().
Resolution
The left operand decides. a + b looks for @add on a’s class only; if
a is a number and b is your instance, the operation is a TypeError
rather than a call to b’s @add.
An operator with no matching decorator raises a TypeError naming the
exact signature:
operator '+' not defined for call signature (nil, number)