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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

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.1?

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

______________________________________________________________________________

DESCRIPTION
       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
       bottlenecks.

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

API
       ::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
	      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_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 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
		     (csources).

	      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.

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/an-
       dreas-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,  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

CATEGORY
       Glueing/Embedded	C code

COPYRIGHT
       Copyright (c) 2011-2018 Andreas Kupries

doc				      1.1		       critcl::enum(n)

NAME | SYNOPSIS | DESCRIPTION | API | EXAMPLE | AUTHORS | BUGS, IDEAS, FEEDBACK | KEYWORDS | CATEGORY | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=critcl_enum&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help