INSTALLATION OF THE TCL LIBRARY

Unfortunately, I haven't yet figured out how to incorporate
the Tcl interface into the autoconfiguration system, so
if you want the Tcl interface you'll need to use
TclMakefile. The one thing you are likely to want to configure
is the definition of TCLLIBDIR on the first line of the makefile.
That is the directory into which you want to install the library.
The makefile assumes that you have a typical Linux installation
of the ActiveTcl distribution of Tcl. If that is not the case,
find out where your Tcl libraries go and change the
definition of TCLLIBDIR to reflect this.

To find out where your Tcl installation looks for libraries
execute the script FindTclLibDir.tcl included here:

tclsh FindTclLibDir.tcl

The result will be the search path that Tcl uses, that is, a list
of directories that Tcl searches, in the order in which it searches them.
Copying tcl_uninum.so into any of these directories (with the name
libuninum.so) will enable Tcl to find it. Note that if you copy
into a directory other than the first one, if you have installed
a previous version of the library in an earlier directory, the
older version will mask the new one, so you should either install
the library in the first one or make sure to delete any old copies
that may be in other directories in the path.

If you do not intend to use the C API you need not
install it, but you should go through the configuration
and build sequence. Executing ./configure configures some
aspects of the Tcl API as well as the C API.
Furthermore, the Tcl API has the file uninum.o as one
of its components.

Then do:

make -f TclMakefile

to build the library and (most likely after becoming root):

make -f TclMakefile install

to install it.

If you are using the ActiveTcl distribution, there is a good chance
that tclsh is not in the root path. If this is the case, your
attempt at installation will fail because make will try to
execute a little Tcl script using tclsh and won't be able
to find tclsh. The easiest thing is to add the directory
containing tclsh to your path. Suppose, for concreteness,
that tclsh is in /usr/local/ActiveTcl/bin. If your root
shell is bash, do:

PATH=$PATH:/usr/local/ActiveTcl/bin

If your root shell is tcsh, do:

path = ($path /usr/local/ActiveTcl/bin)

Then do:

make -f TclMakefile install

again and it should succeed.


USE OF THE TCL LIBRARY

Before using the library you should give the following command
to import it:

package require uninum

If you give this command interactively to tclsh, it will respond with 
the version number of the library, e.g.:

2.4

The Tcl interface to this library exposes five functions
and two global variables.

The function for converting strings to numbers is:

UNStrToWNStr <Numeric String> <Number System>

UNStrToWNStr takes as input a Unicode string representing an integer
and returns a plain ASCII string containing the integer as a decimal
string using the usual Western (that is, Indo-Arabic) digits.
For example, the Unicode string \u4E03\u5341\u4E94, consisting of the
Chinese numerals "7 10 5", is returned as "75".

The NumberSystem argument specifies the expected number system.
Most of the valid values are the names of particular number systems,
such as "Arabic" or "Gurmukhi". If the string is not recognized as
a number in the specified number system, an exception is raised.

The NumberSystem argument may also be "any" or "all". In this case
the input may be in any number system. The library will attempt to
identify the number system and perform the appropriate conversion.
An exception is raised if it is unable to identify the number
system.

The second function exposed is:

StrGuessNumberSystem <Numeric String>

It takes as argument a Unicode string representing an integer and returns
a plain ASCII string containing the name of the number system.
If it is unable to identify the number system, it returns the string
"Unknown". If it is unable to identify the number system uniquely
because the string consists entirely of ASCII zeroes, it returns
the string "All_Zero".

The function for converting numbers to strings is:

WNStrToUNStr <Number> <Number System>

Note that here the number system is specified as a string,
e.g. "Gurmukhi".

UninumNumberSystemMaximumValue takes as argument the name of a number
system and returns the maximum value representable in that writing system,
or "unlimited" where there is no limit.

The fourth function is Tcl_ListNumberSystems. If its argument is 0,
it lists the specific number system names usable for conversion from string
to number and from number to string. If its argument is 1, it lists
the cover terms suitable only for conversion of string to number.
It returns a string in which number system names are separated by
spaces. To obtain a Tcl list of number system names, split this string,
e.g.

set NumberSystemList [lsort [split [Tcl_ListNumberSystems 0]]]

The final function is uninum_version, which returns the
library version number.

The first global variable is uninum_err. This has the same function
as the C variable of the same name. It is set to zero prior to every
call and is set to a non-zero value, defined in nsdefs.h, on error.
You should check this variable after every call to UNStrToWNStr
and should only use the value returned if uninum_err is 0.

In addition to the errors that may occur in the C API,
there is one error unique to the Tcl API:

NS_ERROR_OUTSIDE_BMP

This error occurs when the string generated contains characters
outside the Basic Monolingual Plane of Unicode, that is, outside
the range representable in 16 bits. Since Tcl in its normal form
does not yet support Unicode outside the BMP, any string to be
passed to Tcl is first checked for characters outside the BMP.
If any are found, the string is not returned and uninum_err
is set to NS_OUTSIDE_BMP_ERROR.

The second global variable is tcl_uninum_badchar, which corresponds to the
C variable uninum_badchar. If UNStrToWNStr encounters an unexpected
character, it sets uninum_err and stores the codepoint of the unexpected
character in tcl_uninum_badchar. See TestStringToNumber.tcl for an example
of testing for this error and using the information in tcl_uninum_badchar.
