DOKK / manpages / debian 11 / critcl / critcl_emap.3tcl.en
critcl::emap(3tcl) C Runtime In Tcl (CriTcl) critcl::emap(3tcl) 







critcl::emap - CriTcl Utilities: Enum en- and decoding








package require Tcl 8.4


package require critcl ?3.1.11?


package require critcl::emap ?1.2?


::critcl::emap::def name definition
    ?-nocase? ?-mode mode?












C Runtime In Tcl, or CriTcl , is a system for
    compiling C code embedded in Tcl on the fly and either loading the resulting
    objects into Tcl for immediate use or packaging them for distribution. Use
    CriTcl to improve performance by rewriting in C those routines that
    are performance bottlenecks.


This document is the reference manpage for the critcl::emap
    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 enumerations or integer values to
    encode information, like the state of a system. Tcl bindings to such
    libraries now have the task of converting a Tcl representation, i.e. a
    string into such state, 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 enumerations 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  |
|  ...           |
+----------------+










  
::critcl::emap::def name definition ?-nocase?
    ?-mode mode?

  
This command defines C functions for the conversion of the named
      state code into a Tcl string, and vice versa. The underlying mapping
      tables are automatically initialized on first access (if not fully
      constant), and finalized on interpreter destruction.
    
The definition dictionary provides the mapping from the
        Tcl-level symbolic names of the state 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.

    
Further note that multiple strings can be mapped to the same C
        expression. When converting to Tcl the first string for the mapping is
        returned. An important thing to know: If all C expressions are
        recognizable as integer numbers and their covered range is not too large
        (at most 50) the package will generate code using direct and fast
        mapping tables instead of using a linear search.

    
If the option -nocase is specified then the encoder
        will match strings case-insensitively, and the decoder will always
        return a lower-case string, regardless of the string's case in the
        definition.

    
If the option -mode is specified its contents will
        interpreted as a list of access modes to support. The two allowed modes
        are c and tcl. Both modes can be used together. The
        default mode is tcl.

    
The package generates multiple things (declarations and
        definitions) with names derived from name, which has to be a
        proper C identifier. Some of the things are generated conditional on the
        chosen modes.

  







  

  
The tcl-mode function for encoding a Tcl string into the equivalent
      state code. Its signature is
    

  






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





The return value of the function is a Tcl error code, i.e.
    TCL_OK, TCL_ERROR, etc.



  

  
The c-mode function for encoding a C string into the equivalent
      state code. Its signature is
    

  






int name_encode_cstr (const char* state);





The return value of the function is the encoded state, or -1 if
    the argument is not a vlaid state.



  

  
The tcl-mode function for decoding a state code into the equivalent
      Tcl string. Its signature is
    

  






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






  

  
The c-mode function for decoding a state code into the equivalent C
      string. Its signature is
    

  






const char* name_decode_cstr (int state);





The return value of the function is the C string for the state, or
    NULL if the state argument does not contain a valid state
    value.



  

  
A header file containing the declarations for the 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).

  

  

  
For mode tcl the command registers a new argument-type for
      critcl::cproc with critcl, encapsulating the encoder function.

  

  
For mode tcl the command registers a new result-type for
      critcl::cproc with critcl, encapsulating the decoder function.












The example shown below is the specification for the possible
    modes of entry (normal, no feedback, stars) used by the Tcl binding to the
    linenoise library.




package require Tcl 8.5
package require critcl 3.1.11
critcl::buildrequirement {


    package require critcl::emap
}
critcl::emap::def hiddenmode {


            no  0 n 0 off 0 false 0 0 0


    all   1 yes 1 y 1 on  1 true  1 1 1


    stars 2
} -nocase
# Declarations: hiddenmode.h
# Encoder:      int      hiddenmode_encode (Tcl_Interp* interp, Tcl_Obj* state, int* result);
# Decoder:      Tcl_Obj* hiddenmode_decode (Tcl_Interp* interp, int state);
# ResultType:   hiddenmode
# ArgumentType: hiddenmode











Andreas Kupries








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.








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








Glueing/Embedded C code








Copyright (c) 2011-2018 Andreas Kupries








  

    1.2
    doc