Blt_TreeCreate(3)

💖 Blt_TreeCreate — the manual page, but make it make sense 💖

okay bestie, this one lives in the BLT Library Procedures section, and it's about Blt_TreeCreate. Let's get into it 🫶

✨ NAME ✨

Blt_TreeCreate — create a tree data object. yes, literally just that. iconic.

🌸 SYNOPSIS 🌸

#include <bltTree.h>

int
Blt_TreeCreate(interp, name, tokenPtr)

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the interpreter we report results back to. our lil messenger girl 💌
• const char *name (in) — the name of the new tree. can be qualified by a namespace, no big deal.
• Blt_Tree *tokenPtr (out) — if it's not NULL, this points to the spot where we stash the client tree token.

💅 DESCRIPTION 💅

So this procedure creates a C-based tree data object, and if you want, it hands you back a token pointing at it. Let's go through the arguments one by one, no skipping, periodt.

• interp — the interpreter we report results back to. if something goes wrong, then interp->result will contain an error message. that's the vibe check right there.
• name — the name of the new tree object. think of name as the memory address of the object, fr fr. it's a unique name that identifies the tree object. no tree object name can already exist — so no stealing names, bestie. name can be qualified by a namespace, like fred::myTree. if you don't use a namespace qualifier, the tree gets created in the current namespace, not the global namespace. and if a qualifier is present, that namespace has to already exist. no automatic baby namespaces here 🙈
• tokenPtr — this holds the returned token. tokenPtr points to a location where it is stored. tree tokens are what you use to work with the tree object. if it's NULL, no token is allocated — that's fine, live your life. you can later use Tcl_TreeGetToken to obtain a token. slay.

The new tree data object you just made will initially contain only a root node. that's it. just the root. you can add new nodes with Blt_TreeCreateNode when you're ready to build it out 🌱

Optionally, a token for the tree data object gets returned. here's the cute part: tree data objects can be shared. for example, the tree and hiertable commands may be accessing the same tree data object. each client grabs a token that is associated with the tree. and when all tokens are released (see Blt_TreeReleaseToken), the tree data object is automatically destroyed. mutual breakup energy, honestly 💔

🔥 RETURNS 🔥

A standard Tcl result gets returned. if TCL_ERROR comes back, then interp->result will contain an error message. here's the drama that may occur:

• There already exists a tree by the same name as name. you can use Tcl_TreeExists to determine if a tree exists beforehand — like, do a background check first, bestie.
• The tree name is prefixed by a namespace that doesn't exist. if you qualified the tree name with a namespace, the namespace must exist. unlike Tcl procs and variables, the namespace is not automatically created for you. it's giving "you have to do it yourself" 😭
• Memory can't be allocated for the tree or token. tragic. nothing we can do.

⭐ EXAMPLE ⭐

The following example creates a new

Blt_Tree token;

if (Blt_TreeCreate(interp, "myTree", &token) != TCL_OK) {
    return TCL_ERROR;
}
printf("tree is %s\n", Blt_TreeName(token));

look at her go 💖

👑 KEYWORDS 👑

Tcl_TreeGetToken, Tcl_TreeExists, Tcl_TreeReleaseToken

and that's the whole page, no cap 🧚 this was BLT version 2.5, and yes, the page itself is dated like that too — it's Blt_TreeCreate(3), forever and always. bye bestie, go build a tree 🌈✨