Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
critcl::enum(n)		   C Runtime In	Tcl (CriTcl)	       critcl::enum(n)


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

       package require Tcl  8.4

       package require critcl  ?3.1.11?

       package require critcl::enum  ?1.1?

       ::critcl::enum::def name	definition ?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 im-
       prove performance by rewriting in C those routines that are performance

       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 enumera-
       tion 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	 pack-
       ages 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::enum::def name	definition ?mode?
	      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	speci-
	      fied 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.

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

	      For  mode	 +list all of tcl applies, plus	an additional function
	      is generated which takes three arguments,	in  order:  a  Tcl_In-
	      terp*  pointer  refering	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 func-
	      tion  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.

	      The  package generates multiple things (declarations and defini-
	      tions) with names	derived	from name, which has to	be a proper  C

		     The  C enumeration	type containing	the specified symbolic

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

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

		     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);

		     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 con-
		     verter 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

	      name   At	the level of critcl itself the command registers a new
		     result-type for critcl::cproc, which takes	an integer re-
		     sult 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.

       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 {

	      #	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

       Andreas Kupries

       This  document,	and the	package	it describes, will undoubtedly contain
       bugs and	other problems.	 Please	report such at
       dreas-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,	code  generator,  com-
       pile & run, compiler, conversion, dynamic code generation, dynamic com-
       pilation, generate package, int	to  string  mapping,  linker,  literal
       pool,  on demand	compilation, on-the-fly	compilation, singleton,	string
       pool, string to int mapping

       Glueing/Embedded	C code

       Copyright (c) 2011-2018 Andreas Kupries

doc				      1.1		       critcl::enum(n)


Want to link to this manual page? Use this URL:

home | help