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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

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

SYNOPSIS
       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?

______________________________________________________________________________

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::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 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::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  enumera-
	      tion 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 map-
	      ping  is	returned. An important thing to	know: If all C expres-
	      sions 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 defi-
	      nition.

	      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 defini-
	      tions) with names	derived	from name, which has to	be a proper  C
	      identifier.  Some	of the things are generated conditional	on the
	      chosen modes.

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

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

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

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

	      name.h A header file containing the declarations for the conver-
		     sion  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   For  mode	tcl  the command registers a new argument-type
		     for critcl::cproc with critcl, encapsulating the  encoder
		     function.

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

EXAMPLE
       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

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,	bitmask, bitset,  code
       generator,  compile  &  run, compiler, dynamic code generation, dynamic
       compilation, flags, generate package, linker,  on  demand  compilation,
       on-the-fly compilation, singleton

CATEGORY
       Glueing/Embedded	C code

COPYRIGHT
       Copyright (c) 2011-2018 Andreas Kupries

doc				      1.2		       critcl::emap(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_emap&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help