--- name: "critcl_bitmap" section: "3tcl" platform: "linux" package: "critcl" version: "3.3.1+dfsg-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/critcl_bitmap" --- # critcl\_bitmap(3tcl) CriTcl - Wrap Support - Bitset en- and decoding ``` ``` ## NAME critcl::bitmap - CriTcl - Wrap Support - Bitset en- and decoding ## SYNOPSIS package require **Tcl 8.6** package require **critcl ?3.2?** package require **critcl::bitmap ?1.1?** **::critcl::bitmap::def** *name* *definition* ?*exclusions*? ``` ``` ## DESCRIPTION Be welcome to the *C Runtime In Tcl* (short: *CriTcl*), a system for embedding and using C code from within *Tcl* \[http://core.tcl-lang.org/tcl\] scripts. This document is the reference manpage for the **critcl::bitmap** package. This package provides convenience commands for advanced functionality built on top of both critcl core and package **critcl::iassoc**. C level libraries often use bit-sets to encode many flags into a single value. Tcl bindings to such libraries now have the task of converting a Tcl representation of such flags (like a list of strings) into such bit-sets, and back. *Note* here that the C-level information has to be something which 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. This package was written to make the declaration and management of such bit-sets and their associated conversions functions easy, hiding all attendant complexity from the user. Its intended audience are mainly developers wishing to write Tcl packages with embedded C code. 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 the conversion of the *name*d bit-set into Tcl lists, and vice versa. The underlying mapping tables are automatically initialized on first access, and finalized on interpreter destruction. 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). *Note* here that the C-level information has to be something which 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 *exlusion* 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*, which has to be a proper C identifier. - *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**. ## 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. 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 ```