singleton(n)

👑 singleton(n) — a TclOO page, bestie edition

Okay so this is the manual page for singleton(n) from the TclOO Commands corner of the world. Sit down, hydrate, and let's get into it 💖

---

✨ NAME ✨

oo::singleton — a class that does only allows one instance of itself 🫶 (yes, the original says it like that, and honestly? iconic phrasing, we're keeping it)

---

✨ SYNOPSIS ✨

package require tcl::oo

oo::singleton method ?arg ...?

---

🌈 CLASS HIERARCHY 🌈

oo::object
   → oo::class
       → oo::singleton

Look at that lineage, the whole family tree is slaying 💅

---

💜 DESCRIPTION 💜

So. Singleton classes are classes that only permit at most one instance of themselves to exist. That's the whole vibe. One. Singular. Main character energy, no sequels.

Here's how they pull it off, no cap:

• They unexport the create and createWithNamespace methods entirely — like, gone, not invited to the group chat.
• They override the new method so that it only makes a new instance if there is no existing instance.

⚠️ Bestie, listen: it is not recommended to inherit from a singleton class — singleton-ness is not inherited. And it is not recommended that a singleton class's constructor take any arguments. Fr fr, just don't.

Instances get their destroy method overridden with a method that always returns an error, purely to discourage destruction of the object — but destruction remains possible if it's strictly necessary (e.g., by destroying the class, or by using rename to delete it). So like, the door's locked but the window's still open 🙈

They also have a (non-exported) <cloned> method defined on them that similarly always returns errors, which makes attempts to use the singleton instance with oo::copy fail. Copy protection: enabled ✨

🎀 CONSTRUCTOR

The oo::singleton class does not define an explicit constructor. Which means it's effectively the same as the constructor of the oo::class class. Nothing extra, nothing fancy — inherited, and honestly it ate 💅

🎀 DESTRUCTOR

The oo::singleton class also does not define an explicit destructor. Destroying an instance of it is just like destroying an ordinary class (and yes — it will destroy the singleton object). 💀

🎀 EXPORTED METHODS

• cls new ?arg ...? — returns the current instance of the singleton class if one exists, and creates a new instance only if there's no existing instance. The extra arguments, arg ..., are only used if a new instance is actually manufactured — and that construction happens via the oo::class class's new method. This is an override of a superclass's method, with an identical call signature to the superclass's implementation. Same signature, different personality 💖

🎀 NON-EXPORTED METHODS

The oo::singleton class explicitly states that create and createWithNamespace are unexported. So callers should not assume they have control over either the name or the namespace name of the singleton instance. It's giving "you don't get to name the baby" 🍼

---

🦋 EXAMPLE 🦋

This example demonstrates that there is only one instance, even though the new method is called three times. Three calls, one object — the way that works is genuinely obsessed 🔥

oo::singleton create Highlander {
    method say {} {
        puts "there can be only one"
    }
}

set h1 [Highlander new]
set h2 [Highlander new]
if {$h1 eq $h2} {
    puts "equal objects"    → prints "equal objects"
}
set h3 [Highlander new]
if {$h1 eq $h3} {
    puts "equal objects"    → prints "equal objects"
}

🌸 Heads up: the name of the instance of the singleton is not guaranteed to be anything in particular. Don't count on it, bestie.

---

⭐ SEE ALSO ⭐

• oo::class(n)

---

👑 KEYWORDS 👑

class, metaclass, object, single instance

---

Okay that's the whole page, go forth and singleton responsibly 🧚‍♀️

This one's from TclOO, version 0.3, dated singleton(n) — mwah, love u, bye 💜🎀