critcl::bitmap(n)

🦋 critcl::bitmap(n) 🦋 — CriTcl Wrap Support: Bitset en- and decoding 💅

✨ NAME ✨

critcl::bitmap — CriTcl — Wrap Support — Bitset en- and decoding. This is the reference page for the package that makes bit-set en/decode behavior feel like a main character moment. 💖

🌈 SYNOPSIS 🌈

package require Tcl  8.6

package require critcl  ?3.2?

package require critcl::bitmap  ?1.1?

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

💫 DESCRIPTION 💫

Okay so welcome to the C Runtime In Tcl, aka CriTcl — the whole system for embedding and using C code from inside Tcl scripts over at http://core.tcl-lang.org/tcl. This document is the reference manpage for the critcl::bitmap package. That package gives you convenience commands for advanced functionality built on top of both the critcl core and the package critcl::iassoc. ✨

C-level libraries are obsessed with bit-sets for packing a whole bunch of flags into a single value. Tcl bindings to those libraries then have the job of converting the Tcl representation of those flags — think a list of strings — into that bit-set, and back again. Important note, bestie: the C-level information has to be something that already exists. This package does not create those values. That is in contrast to the package critcl::enum, which creates an enumeration based on the specified symbolic names. 💅

This package was written to make the declaration and management of such bit-sets — and their associated conversion functions — actually easy, hiding all the attendant complexity from the user. Its intended audience is mainly developers who want to write Tcl packages with embedded C code. This package resides in the Core Package Layer of CriTcl. It's giving this stack:

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

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

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

👑 API 👑

::critcl::bitmap::def name definition ?exclusions? — the one command you came for 🫶

This command defines two C functions for the conversion of 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. No manual setup arc, periodt. 💖

The definition dictionary provides the mapping from the Tcl-level symbolic names of the flags to their C expressions — often the name of the macro specifying the actual value. Again: the C-level information has to be something that already exists. The package does not create these values. This is in contrast to the package critcl::enum, which creates an enumeration based on the specified symbolic names.

The optional exclusion list is for the flags/bit-sets for which conversion from bit-set to flag — i.e. decoding — makes no sense. One case for such, for example, are flags representing a combination of other flags.

The package generates multiple things (declarations and definitions) with names derived from name, and name has to be a proper C identifier. Here's the generated fam:

• name_encode — the function for encoding 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.

• name_decode — the function for decoding 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 is stored in a place where it will not interfere with the overall system outside of the package, yet also be available for easy inclusion by package files (csources).
• 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. Yes, same label, two different critcl type jobs. 💅

🌸 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. Very much "flags but make it fashion." 🦋

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. The icon himself. 💖

💀 BUGS, IDEAS, FEEDBACK 💀

This document, and the package it describes, will undoubtedly contain bugs and other problems. 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. No gatekeeping, bestie. 🫶

🔥 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. Footer check: source doc, version 1.1, manual critcl::bitmap(n) — and the original doesn't print a date, so we're not inventing one. Stay iconic. 🎀✨