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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

NAME
       critcl::literals	- CriTcl Utilities: Constant string pools

SYNOPSIS
       package require Tcl  8.4

       package require critcl  ?3.1.11?

       package require critcl::literals	 ?1.3?

       ::critcl::literals::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::literals pack-
       age. This package provides convenience commands for advanced  function-
       ality 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, hid-
       ing 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::literals::def name definition ?mode?
	      This command defines a C function	with the given name which pro-
	      vides access to a	pool of	constant strings  with	a  Tcl	inter-
	      preter.

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

	      The mode-list configures the output somewhat.  The three allowed
	      modes  are  c,  +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_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.

	      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_names" holding the codes (see below), the symbolic
	      names of the literals to return. The result of the function is a
	      Tcl_Obj* pointer to a Tcl	list holding the requested string con-
	      stants.

	      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   The  mode	tcl  function  providing  access to the	string
		     pool.  Its	signature is

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

	      name_list
		     The mode +list function  providing	 multi-access  to  the
		     string pool.  Its signature is

		     Tcl_Obj* name_list	(Tcl_Interp* interp, int c, name_names*	literal);

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

		     const char* name_cstr (name_names literal);

	      name_names
		     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	acces-
		     sor 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.

EXAMPLE
       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	{
		  w_create"create"
		  w_directory"directory"
		  w_events"events"
		  w_file"file"
		  w_handler"handler"
		  w_remove"remove"
	      }	{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

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, dynamic  code  generation,	 dynamic  compilation,
       generate	 package, linker, literal pool,	on demand compilation, on-the-
       fly compilation,	singleton, string pool

CATEGORY
       Glueing/Embedded	C code

COPYRIGHT
       Copyright (c) 2011-2018 Andreas Kupries

doc				      1.3		   critcl::literals(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_literals&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help