Provided by: critcl_3.1.17+dfsg-1_all bug


       critcl::literals - CriTcl Utilities: Constant string pools


       package require Tcl  8.4

       package require critcl  ?3.1.11?

       package require critcl::literals  ?1.2?

       ::critcl::literals::def name definition ?mode?



       Welcome  to the C Runtime In Tcl, CriTcl for short, a system to build C extension packages
       for Tcl on the fly, from C code embedded within Tcl scripts, for  all  who  wish  to  make
       their code go faster.

       This  document  is  the  reference  manpage for the critcl::literals package. This package
       provides convenience commands for advanced functionality built on top of both critcl  core
       and package critcl::iassoc.

       Many packages will have a fixed set of string constants occuring in one or places. Most of
       them will be coded to create a new string Tcl_Obj* from a C char* every time the  constant
       is needed, as this is easy to to, despite the inherent waste of memory.

       This  package  was written to make declaration and management of string pools which do not
       waste memory as easy as the wasteful solution, hiding all attendant  complexity  from  the

       Its  intended audience are mainly developers wishing to write Tcl packages with embedded C

       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::literals::def name definition ?mode?
              This command defines a C function with the given name which provides  access  to  a
              pool of constant strings with a Tcl interpreter.

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

              The mode-list configures the output somewhat. The two allowed modes are c and  tcl.
              Both modes can be used together. The default mode is tcl.

              For  mode tcl the new function has two arguments, a Tcl_Interp* pointer refering to
              the interpreter holding the string pool, and  a  code  of  type  "name_names"  (see
              below), the symbolic name of the literal to return. The result of the function is a
              Tcl_Obj* pointer to the requested string constant.

              For mode c the new function has one argument, a  code  of  type  "name_names"  (see
              below), the symbolic name of the literal to return. The result of the function is a
              const char* pointer to the requested string constant.

              The underlying string pool  is  automatically  initialized  on  first  access,  and
              finalized on interpreter destruction.

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

              name   The mode tcl function providing access to the string pool.  Its signature is

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

                     The mode c function providing access to the string pool.  Its signature is

                     const char* name_cstr (name_names literal);

                     A C enumeration type containing the symbolic names of the  strings  provided
                     by the pool.

              name.h A header file containing the declarations for the accessor functions and the
                     enumeration type, 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   New in version 1.1: For mode tcl the command registers a new result-type for
                     critcl::cproc  with  critcl, which takes an integer result from the function
                     and converts it to the equivalent string in the pool for the script.


       The example shown below is the specification of the string pool pulled from the draft work
       on a Tcl binding to Linux's inotify APIs.

              package require Tcl 8.5
              package require critcl 3.1.11

              critcl::buildrequirement {
                  package require critcl::literals

              critcl::literals::def tcl_inotify_strings {
              } {c tcl}

              # Declarations: tcl_inotify_strings.h
              # Type:         tcl_inotify_strings_names
              # Accessor:     Tcl_Obj*    tcl_inotify_strings      (Tcl_Interp*               interp,
              #                                                     tcl_inotify_strings_names literal);
              # Accessor:     const char* tcl_inotify_strings_cstr (tcl_inotify_strings_names literal);
              # ResultType:   tcl_inotify_strings


       Andreas Kupries


       This  document,  and  the  package  it  describes, will undoubtedly contain bugs and other
       problems.  Please report such at   Please  also
       report any ideas for enhancements you may have for either package and/or documentation.


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


       Glueing/Embedded C code


       Copyright (c) 2011-2015 Andreas Kupries