+# code generator to help with writing Tcl extensions
+# Copyright 2006-2012 Ian Jackson
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation; either version 2 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this library; if not, see <http://www.gnu.org/licenses/>.
+
+
+# Input format is line-based, ws-significant, offside rule (some kind
+# of, anyway).
+#
+# Type TYPE: C-TYPE-DECLARATOR
+# Defines TYPE as a type (for arguments and return values)
+# which corresponds to the C type specified. C-TYPE-DECLARATOR
+# must contain one `@' where the identifier would go.
+# The type may contain allocated memory, etc., in which case
+# `Init' and `Fini' must be used.
+#
+# TYPE may be either TYPENAME or TYPENAME(ARGS) - in this case,
+# ARGS should be C argument declarations as for in a function
+# prototype, of extra arguments for the application-supplied
+# parser/returner functions. Each time a TYPE is used elsewhere,
+# the ARGS should be the actual arguments to pass, and will be
+# textually copied into the calls to the parser/returner
+# functions.
+#
+# `Type' causes declarations in the .h file of these functions:
+# int cht_pat_TYPENAME(Tcl_Interp*, Tcl_Obj *obj, C-TYPE *val, ARGS);
+# Tcl_Obj *cht_ret_TYPENAME(Tcl_Interp*, C-TYPE val, ARGS);
+#
+# cht_pat_... must attempt to parse obj into the appropriate type.
+# val will already have been initialised with `Init' statements if
+# relevant. Whether cht_pat_... fails or succeeds it may allocate
+# memory into the object and must leave the object valid (for
+# `Fini').
+#
+# cht_ret_... must convert the value back to a new Tcl_Obj. It may
+# not fail.
+#
+# Init TYPENAME C-STATEMENTS
+# Provides some statements which are used to initialise a variable
+# of type TYPENAME. C-STATEMENTS should contain one or more `@',
+# which will be replaced by the actual variable name. The
+# variable will have been declared with the C declarator specified
+# with `Type'. C-STATEMENTS may not fail or longjmp, and they may
+# not allocate memory or other resources. If no `Init' is
+# supplied then there is no invariant (so no `Fini' may be
+# supplied either, and the type is `flat' - no memory, external
+# refs, etc.)
+#
+# Fini TYPENAME C-STATEMENTS
+# Provides some statements (like `Init') which are used to free a
+# variable of type TYPENAME. The variable will already have been
+# initialised with the `Init' statements, and may have been
+# modified since by application per-type or per-command code. Its
+# invariant will be satisfied before C-STATEMENTS. Afterwards the
+# invariant may or may not be satisfied, but it may not have any
+# memory or other resources allocated. C-STATEMENTS may not fail
+# or longjmp.
+#
+# H-Include C-INCLUDE-SPECIFIER
+# Arranges for generated .h files to #include the specified
+# file. C-INCLUDE-SPECIFIER should include the <..> or "..".
+#
+# Table [*]TABLENAME C-ENTRY-TYPE
+# Starts a table of commands or subcommands. The generated .h
+# will contain a definition of C-ENTRY-TYPE containing
+# const char *name;
+# Tcl_ObjCmdProc *func;
+# and the generated .c will contain
+# const C-ENTRY-TYPE C-ARRAY-NAME[];
+# where C-ARRAY-NAME is TABLENAME, with `_entries' appended
+# and `cht_' prepended. The entries are indented one level (one
+# or more spaces) and look like this:
+# ENTRYNAME [ C-EXTRA-ENTRY-VALUES ]
+# FORMALARGNAME TYPE
+# ...
+# [ => RESULT-TYPE ]
+# This will cause the declaration of
+# int cht_do_TABLENAME_ENTRYNAME(ClientData cd, Tcl_Interp *ip,
+# FORMAL-ARGUMENTS, RESULT-C-TYPE*);
+# which is the procedure which the application must supply to
+# implement the function. If the `=> RESULT-TYPE' is omitted, so
+# is the result argument to the function. Each argument to the
+# function is of the C type corresponding to the specified type.
+# TYPE may be `...', in which case the C function will be passed
+# two args (int objc, Tcl_Obj *const *objv) for the remaining
+# arguments.
+#
+# The cht_do_... function should not eat any memory associated with
+# the arguments. The result buffer (if any) will be initialised
+# using the `Init' and should on success contain the relevant
+# result. On failure it should leave the result unmodified (or at
+# least, not in need of freeing).
+#
+# As an alternative, the arguments can be replaced with just
+# dispatch(TYPE-ARGS-FOR-ENUM)
+# which is a shorthand for
+# subcmd enum(TYPE-ARGS-FOR-ENUM)
+# args ...
+# and also generates and uses a standard dispatch function.
+#
+# There will be an entry in C-ARRAY-NAME for every table entry.
+# The name will be ENTRYNAME, and the func will be a function
+# suitable for use as a Tcl command procedure, which parses the
+# arguments, processes the command, and sets any result, as
+# applicable.
+#
+# `*' should be used if the table name is not useful for error
+# messages. It suppresses `TABLENAME ' from the front of the
+# autogenerated argument parsing error strings.
+#
+# EntryExtra C-ENTRY-TYPE
+# Introduces a section of additional C code which will be inserted
+# into the definition of C-ENTRY-TYPE by `Table'. The C
+# code, which follows on several indented lines, should be
+# structure member definitions.
+#
+# When EntryExtra is used, in the corresponding Table, each
+# ENTRYNAME should be followed on the same line by whitespace and
+# EXTRA-VALUES; the EXTRA-VALUES are used as initialisers for the
+# additional structure elements.
+#
+# NoEntryDefine C-ENTRY-TYPE
+# Prevents the definition of C-ENTRY-TYPE by Table.
+# The C type must be defined elsewhere.
+#
+# Also expected are these functions:
+# void cht_setstringresult(Tcl_Interp*, const char*);
+# sets the Tcl result from the supplied string
+# int cht_pat_enum(Tcl_Interp*, Tcl_Obj*, const void **c_e_t_array,
+# const void *c_e_t_return, size_t c_e_t_sz, const char *what);
+# scans a table of C-ENTRY-TYPEs looking for the
+# string matching the string supplied by the script
+# (as a Tcl_Obj). On error sets the result, using
+# what (a noun phrase describing the type of thing).
+# Assumes (unportably!) that the name and func members
+# are in the same places no matter what the rest of
+# the struct contains.
+# and the two predefined types `int' (C `int') and `obj' (Tcl_Obj*,
+# unmodified.) The corresponding definitions are in tcmdiflib.c.
+