critcl::bitmap(3tcl)

💖 critcl::bitmap — the CriTcl bit-set bestie 💖

okay so bestie, welcome to critcl::bitmap, part of the C Runtime In Tcl (aka CriTcl for short, iykyk). It's the Wrap Support piece that handles Bitset en- and decoding and it's genuinely so useful it hurts. 🦋

---

✨ SYNOPSIS ✨

package require Tcl 8.6

package require critcl ?3.2?

package require critcl::bitmap ?1.1?

::critcl::bitmap::def name definition ?exclusions?

---

🌸 DESCRIPTION 🌸

Hi hiii, welcome to the C Runtime In Tcl (short: CriTcl) — a whole system for embedding and using C code from inside Tcl scripts at http://core.tcl-lang.org/tcl. Obsessed, frankly. 💅

This document is the reference manpage for the critcl::bitmap package, and what this package does is hand you convenience commands for advanced functionality that sits on top of both the critcl core and the package critcl::iassoc. Two parents, one icon. 👑

So here's the vibe: C-level libraries love to cram a bunch of flags into a single value as a bit-set. And that means Tcl bindings to those libraries have a job — converting a Tcl representation of those flags (think: a list of strings, cute) into such bit-sets, and back again. 🔁

Heads up though, no cap: the C-level information has to be something that already exists. The package does not create these values. That's the whole difference between this and the package critcl::enum, which does create an enumeration based on the symbolic names you specify. Not the same job, bestie, don't mix them up. 🙈

This package was written to make declaration and management of such bit-sets and their associated conversion functions easy, hiding all the attendant complexity from you. You're welcome. 💖

Its intended audience is mainly developers wishing to write Tcl packages with embedded C code. (Hi, that's you. You're doing great. 🫶)

This package resides in the Core Package Layer of CriTcl:

+----------------+
|Applications    |
| critcl         |
| critcl::app    |
+----------------+

*================*
|Core Packages   |
| critcl         |
| critcl::util   |
*================*

+----------------+
|Support Packages|
| stubs::*       |
| md5, platform  |
|  ...           |
+----------------+

---

✨ API ✨

• ::critcl::bitmap::def name definition ?exclusions? — this command defines two C functions for converting the named bit-set into Tcl lists, and vice versa. The underlying mapping tables are automatically initialized on first access, and finalized on interpreter destruction. Auto-magic, no manual setup, slay. ✨

The definition dictionary gives you the mapping from the Tcl-level symbolic names of the flags to their C expressions (usually the name of the macro holding the actual value). And bestie, remember: the C-level information has to be something that already exists. The package does not create these values — which is exactly what makes it different from critcl::enum, which creates an enumeration from the specified symbolic names. 🎀

The optional exclusions list is for the flags/bit-sets where converting from bit-set to flag — i.e. decoding — makes no sense at all. One example of such a thing: flags that represent a combination of other flags. Decoding those? 💀 no. Skip.

The package generates multiple things (declarations and definitions) with names derived from name, which has to be a proper C identifier.

• name_encode — the function that encodes a Tcl list of strings into the equivalent bit-set. Its signature is:

int name_encode (Tcl_Interp* interp, Tcl_Obj* flags, int* result);

The return value of the function is a Tcl error code, i.e. TCL_OK, TCL_ERROR, etc. So check it, bestie, fr fr. 🔥

• name_decode — the function that decodes a bit-set into the equivalent Tcl list of strings. Its signature is:

Tcl_Obj* name_decode (Tcl_Interp* interp, int flags);

• name.h — a header file containing the declarations for the two conversion functions, for use by other parts of the system, if necessary. The generated file gets stored somewhere it won't interfere with the overall system outside of the package, while also being available for easy inclusion by package files (csources). Best of both worlds, we love that. 🧚
• name — the name of a critcl argument type encapsulating the encoder function, for use by critcl::cproc.
• name — the name of a critcl result type encapsulating the decoder function, for use by critcl::cproc.

---

🌈 EXAMPLE 🌈

The example shown below is the specification of the event flags pulled from the draft work on a Tcl binding to Linux's inotify APIs:

package require Tcl 8.6
package require critcl 3.2

critcl::buildrequirement {
    package require critcl::bitmap
}

critcl::bitmap::def tcl_inotify_events {
    accessed       IN_ACCESS
    all            IN_ALL_EVENTS
    attribute      IN_ATTRIB
    closed         IN_CLOSE
    closed-nowrite IN_CLOSE_NOWRITE
    closed-write   IN_CLOSE_WRITE
    created        IN_CREATE
    deleted        IN_DELETE
    deleted-self   IN_DELETE_SELF
    dir-only       IN_ONLYDIR
    dont-follow    IN_DONT_FOLLOW
    modified       IN_MODIFY
    move           IN_MOVE
    moved-from     IN_MOVED_FROM
    moved-self     IN_MOVE_SELF
    moved-to       IN_MOVED_TO
    oneshot        IN_ONESHOT
    open           IN_OPEN
    overflow       IN_Q_OVERFLOW
    unmount        IN_UNMOUNT
} {
    all closed move oneshot
}

# Declarations:          tcl_inotify_events.h
# Encoder:      int      tcl_inotify_events_encode (Tcl_Interp* interp, Tcl_Obj* flags, int* result);
# Decoder:      Tcl_Obj* tcl_inotify_events_decode (Tcl_Interp* interp, int flags);
# crit arg-type          tcl_inotify_events
# crit res-type          tcl_inotify_events

---

⭐ AUTHORS ⭐

Andreas Kupries

---

🫶 BUGS, IDEAS, FEEDBACK 🫶

This document, and the package it describes, will undoubtedly contain bugs and other problems. (Not me being dramatic — it says so right there. 😭)

Please report such at https://github.com/andreas-kupries/critcl. Please also report any ideas for enhancements you may have for either package and/or documentation.

---

💜 KEYWORDS 💜

C code, Embedded C Code, Tcl Interp Association, bitmask, bitset, code generator, compile & run, compiler, dynamic code generation, dynamic compilation, flags, generate package, linker, on demand compilation, on-the-fly compilation, singleton

---

🎀 CATEGORY 🎀

Glueing/Embedded C code

---

👑 COPYRIGHT 👑

Copyright (c) 2011-2024 Andreas Kupries

---

and that's the whole page bestie!! 💅 this one came from the doc source, riding at version 1.1, living under the critcl::bitmap(3tcl) name. go forth and encode ur bits, icon. 💖✨🦋