next(n)

💖 next(n) — TclOO Commands 💖

okay bestie, buckle up, we're doing the next page and it's genuinely one of the most iconic TclOO moves out there 🫶 it lives in the TclOO commands family, and it's all about calling up the chain. let's go ✨

---

🌸 NAME 🌸

next, nextto — invoke superclass method implementations

---

✨ SYNOPSIS ✨

package require tcl::oo

next ?arg ...?
nextto class ?arg ...?

---

💅 DESCRIPTION 💅

so. the next command is how you call implementations of a method by a class, superclass or mixin that are overridden by the current method. no cap. and listen — it can only be used from inside a method. that's the vibe check it enforces. 🎀

it's also the thing you use inside filters to mark the exact point where a filter hands off to the actual implementation (the filter is fully allowed to not go along the chain at all, and it can also do whatever it wants with the results of going along the chain of methods). main character energy, honestly. 💅

the result of the next command is the result of the next method in the method chain. but — and this is the part that will humble you 😭 — if there are no further methods in the method chain, the result of next will be an error. periodt. the arguments, arg, to next are the arguments you pass along to the next method in the chain.

now nextto — she's the same as next, except she takes an extra class argument that identifies a class whose implementation of the current method chain (peep info object call) should be used. the method implementation selected will be the one provided by the given class, and it must refer to an existing non-filter invocation that lies further along the chain than the current implementation. lowkey picky but she's right to be. 🦋

---

🌈 THE METHOD CHAIN 🌈

when a method of an object is invoked, things happen in several stages, bestie. here's the whole choreography:

1. the structure of the object — its class, superclasses, filters, and mixins — are examined to build a method chain, which contains a list of method implementations to invoke.
2. the first method implementation on the chain is invoked.
3. if that method implementation invokes the next command, the next method implementation is invoked (with its arguments being those that were passed to next).
4. the result from the overall method call is the result from the outermost method implementation; inner method implementations return their results through next.
5. the method chain is cached for future use. 💾

🧚 METHOD SEARCH ORDER 🧚

when constructing the method chain, method implementations are searched for in this order, and yes you have to memorise it, sorry not sorry:

1. in the classes mixed into the object, in class traversal order. the list of mixins is checked in natural order.
2. in the classes mixed into the classes of the object, with sources of mixing in being searched in class traversal order. within each class, the list of mixins is processed in natural order.
3. in the object itself.
4. in the object's class.
5. in the superclasses of the class, following each superclass in a depth-first fashion in the natural order of the superclass list.

any particular method implementation always comes as late in the resulting list of implementations as possible. this means that if some class, A, is both mixed into a class, B, and is also a superclass of B, the instances of B will always treat A as a superclass from the perspective of inheritance. this is true even when the multiple inheritance is processed indirectly. iconic behaviour tbh. 👑

🎀 FILTERS 🎀

when an object has a list of filter names set upon it, or is an instance of a class (or has mixed in a class) that has a list of filter names set upon it, then before every invocation of any method the filters are processed. filter implementations are found in class traversal order, as are the lists of filter names (each of which is traversed in natural list order). 🌀

not me warning you: explicitly invoking a method used as a filter will cause that method to be invoked twice — once as a filter and once as a normal method. she's doing double duty fr fr 💀

each filter should decide for itself whether to permit the execution to go forward to the proper implementation of the method (which it does by invoking the next command, since filters are inserted into the front of the method call chain) and is responsible for returning the result of next. 🫶

filters are invoked when processing an invocation of the unknown method because of a failure to locate a method implementation — but not when invoking either constructors or destructors. (note however that the destroy method is a conventional method, and filters are invoked as normal when it is called. 💖)

---

🔥 EXAMPLES 🔥

this example demonstrates how to use the next command to call the (super)class's implementation of a method. the script:

oo::class create theSuperclass {
    method example {args} {
        puts "in the superclass, args = $args"
    }
}

oo::class create theSubclass {
    superclass theSuperclass
    method example {args} {
        puts "before chaining from subclass, args = $args"
        next a {*}$args b
        next pureSynthesis
        puts "after chaining from subclass"
    }
}

theSubclass create obj
oo::objdefine obj method example args {
    puts "per-object method, args = $args"
    next x {*}$args y
    next
}
obj example 1 2 3

prints the following:

per-object method, args = 1 2 3
before chaining from subclass, args = x 1 2 3 y
in the superclass, args = a x 1 2 3 y b
in the superclass, args = pureSynthesis
after chaining from subclass
before chaining from subclass, args =
in the superclass, args = a b
in the superclass, args = pureSynthesis
after chaining from subclass

---

this next example demonstrates how to build a simple cache class that applies memoization to all the method calls of the objects it is mixed into, and shows how it can make a difference to computation times. the way that after 3000 just sits there simulating deep thought... she's so real 😭

oo::class create cache {
    filter Memoize
    method Memoize args {
        # Do not filter the core method implementations
        if {[lindex [self target] 0] eq "::oo::object"} {
            return [next {*}$args]
        }

        # Check if the value is already in the cache
        my variable ValueCache
        set key [self target],$args
        if {[info exist ValueCache($key)]} {
            return $ValueCache($key)
        }

        # Compute value, insert into cache, and return it
        return [set ValueCache($key) [next {*}$args]]
    }

    method flushCache {} {
        my variable ValueCache
        unset ValueCache
        # Skip the caching
        return -level 2 ""
    }
}

oo::object create demo
oo::objdefine demo {
    mixin cache

    method compute {a b c} {
        after 3000 ;# Simulate deep thought
        return [expr {$a + $b * $c}]
    }

    method compute2 {a b c} {
        after 3000 ;# Simulate deep thought
        return [expr {$a * $b + $c}]
    }
}

puts [demo compute  1 2 3]      → prints "7" after delay
puts [demo compute2 4 5 6]      → prints "26" after delay
puts [demo compute  1 2 3]      → prints "7" instantly
puts [demo compute2 4 5 6]      → prints "26" instantly
puts [demo compute  4 5 6]      → prints "34" after delay
puts [demo compute  4 5 6]      → prints "34" instantly
puts [demo compute  1 2 3]      → prints "7" instantly
demo flushCache
puts [demo compute  1 2 3]      → prints "7" after delay

like, the cache ate and left no crumbs, bestie. 💅✨

---

🦋 SEE ALSO 🦋

oo::class(n), oo::define(n), oo::object(n), self(n)

---

💜 KEYWORDS 💜

call, method, method chain

---

and that's the whole page, bestie!! 🎀 this was TclOO, version 0.1, and the page itself is next(n) — shoutout to her for being so iconic. go chain some methods, you've got this fr fr 💖✨🫶