NAME

       critcl::enum - CriTcl Utilities: String/Integer mapping

SYNOPSIS

       package require Tcl  8.4

       package require critcl  ?3.1.11?

       package require critcl::enum  ?1.0.1?

       ::critcl::enum::def name definition

_________________________________________________________________________________________________

DESCRIPTION

       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::enum package. This package provides
       convenience commands for advanced functionality built on  top  of  both  critcl  core  and
       package critcl::literals.

       It  is  an  extended  form of string pool which not only converts integer values into Tcl-
       level strings, but also handles the reverse direction,  converting  from  strings  to  the
       associated integer values.

       It essentially provides a bi-directional mapping between a C enumeration type and a set of
       strings, one per enumeration value.  Note that the C enumeration in question is created by
       the definition. It is not possible to use the symbols of an existing enumeration type.

       This  package was written to make the declaration and management of such mappings easy. It
       uses a string pool for one of the directions, using its ability to return shared  literals
       and conserve memory.

       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::enum::def name definition
              This command defines two C functions  for  the  conversion  between  C  values  and
              Tcl_Obj'ects, with named derived from name.

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

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

              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_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).

              name   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   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.

EXAMPLE

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

              package require Tcl 8.5
              package require critcl 3.1.11

              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.  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, 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

       Copyright (c) 2011-2015 Andreas Kupries