critcl::enum(n)

📦 version 3.3.1, in alpine 3.24

🌸 critcl::enum — the CriTcl string/integer glow-up 💅

okay so bestie, welcome to the manual page for critcl::enum, a member of the C Runtime In Tcl family (CriTcl for short — iconic name, no notes). If you don't know her yet: CriTcl is the whole system for embedding and using C code from inside Tcl scripts over at [http://core.tcl-lang.org/tcl](http://core.tcl-lang.org/tcl). 🫶

✨ SYNOPSIS ✨

package require Tcl  8.6

package require critcl  ?3.2?

package require critcl::enum  ?1.2?

::critcl::enum::def name definition ?mode?

🦋 DESCRIPTION 🦋

Be welcome to the C Runtime In Tcl (short: CriTcl), a system for embedding and using C code from within Tcl scripts [http://core.tcl-lang.org/tcl]. (Yes I said welcome twice-ish, it's a vibe. 💖)

This document is the reference manpage for the critcl::enum package. This package hands you convenience commands for advanced functionality, built on top of both the critcl core and the package critcl::literals. It's an extended form of string pool, except it doesn't just convert integer values into Tcl-level strings — it also handles the reverse direction, converting from strings back to the associated integer values. Bi-directional. Main character energy. 👑

So basically: it gives you a two-way mapping between a C enumeration type and a set of strings, one string per enumeration value. Real talk though — the C enumeration in question is created by the definition. You literally cannot use the symbols of an existing enumeration type. No cap, that's just how she is. 🙈

This package was written to make the declaration and management of such mappings easy. For one of the directions it uses a string pool, leaning on its ability to return shared literals and conserve memory. 🌸

Its intended audience? Mainly developers wishing to write Tcl packages with embedded C code. iykyk. 💅

This package resides in the Core Package Layer of CriTcl. Behold, the stack:

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

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

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

⭐ API ⭐

::critcl::enum::def name definition ?mode?

This command defines two C functions for the conversion between C values and Tcl_Obj'ects, with names derived from name. Two for one, we love to see it. 🎀

The definition dictionary provides the mapping from the specified C-level symbolic names to the strings themselves.

The mode-list configures the output somewhat. The two allowed modes are +list and tcl. All modes can be used together. The default mode is tcl. Using mode +list implies tcl as well. (yes, +list comes with friends, she doesn't travel alone 💀)

  • mode tcl — the new function has two arguments: a Tcl_Interp* pointer referring to the interpreter holding the string pool, and a code of type "name_pool_names" (see below), the symbolic name of the string to return. The result of the function is a Tcl_Obj* pointer to the requested string constant. ✨
  • mode +list — everything from tcl applies, plus an additional function is generated which takes three arguments, in order: a Tcl_Interp* pointer referring to the interpreter holding the string pool, an int holding the size of the last argument, and an array of type "name_pool_names" holding the codes (see below), the symbolic names of the strings to return. The result of the function is a Tcl_Obj* pointer to a Tcl list holding the requested string constants. 📋

The underlying string pool is automatically initialized on first access, and finalized on interpreter destruction. She handles her own business. 🧚

The package generates multiple things (declarations and definitions) with names derived from name, which has to be a proper C identifier. (like, actually proper, don't try her 🔥)

name_pool_names

The C enumeration type containing the specified symbolic names.

name_ToObj

The function converting from integer value to Tcl string. Its signature is:

Tcl_Obj* name_ToObj (Tcl_Interp* interp, name_names literal);

name_ToObjList

The mode +list function converting from integer array to Tcl list of strings. Its signature is:

Tcl_Obj* name_ToObjList (Tcl_Interp* interp, int c, name_names* literal);

name_GetFromObj

The function converting from Tcl string to integer value. Its signature is:

int name_GetFromObj (Tcl_Interp* interp, Tcl_Obj* obj, int flags, int* literal);

The flags are like for Tcl_GetIndexFromObj.

name.h

A header file containing the declarations for the converter 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). Considerate queen behavior. 👑

name (the result-type one)

At the level of critcl itself, the command registers a new result-type for critcl::cproc, which takes an integer result from the function and converts it to the equivalent string in the pool for the script.

name (the argument-type one)

At the level of critcl itself, the command registers a new argument-type for critcl::cproc, which takes a Tcl string and converts it to the equivalent integer for delivery to the function.

yeah, two different things both called name up there — that's literally how the original lists them, don't come for me 🫶

🍓 EXAMPLE 🍓

The example shown below is the specification for a set of actions, methods, and the like, a function may take as argument. She ate, fr fr. 🔥

package require Tcl 8.6
package require critcl 3.2

critcl::buildrequirement {
    package require critcl::enum
}

critcl::enum::def action {
    w_create  "create"
    w_directory"directory"
    w_events  "events"
    w_file "file"
    w_handler "handler"
    w_remove  "remove"
}

# Declarations: action.h
# Type:         action_names
# Accessor:     Tcl_Obj* action_ToObj (Tcl_Interp* interp, int literal);
# Accessor:     int action_GetFromObj (Tcl_Interp* interp, Tcl_Obj* o, int flags, int* literal);
# ResultType:   action
# ArgType:      action

💜 AUTHORS 💜

Andreas Kupries

😭 BUGS, IDEAS, FEEDBACK 😭

This document, and the package it describes, will undoubtedly contain bugs and other problems. (not me manifesting my own bugs 💀) 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. We're nice here, we take those. 🫶

🌈 KEYWORDS 🌈

C code, Embedded C Code, Tcl Interp Association, code generator, compile & run, compiler, conversion, dynamic code generation, dynamic compilation, generate package, int to string mapping, linker, literal pool, on demand compilation, on-the-fly compilation, singleton, string pool, string to int mapping

🎀 CATEGORY 🎀

Glueing/Embedded C code

Copyright (c) 2011-2024 Andreas Kupries

and that's the whole page, bestie ✨ this is doc version 1.2 of the critcl::enum(n) manual, straight from the CriTcl crew, so go forth and map your strings to your ints and your ints to your strings — periodt. 💅💖🦋

📦 where this page comes from