1INSTALLATION OF THE TCL LIBRARY 2 3Unfortunately, I haven't yet figured out how to incorporate 4the Tcl interface into the autoconfiguration system, so 5if you want the Tcl interface you'll need to use 6TclMakefile. The one thing you are likely to want to configure 7is the definition of TCLLIBDIR on the first line of the makefile. 8That is the directory into which you want to install the library. 9The makefile assumes that you have a typical Linux installation 10of the ActiveTcl distribution of Tcl. If that is not the case, 11find out where your Tcl libraries go and change the 12definition of TCLLIBDIR to reflect this. 13 14To find out where your Tcl installation looks for libraries 15execute the script FindTclLibDir.tcl included here: 16 17tclsh FindTclLibDir.tcl 18 19The result will be the search path that Tcl uses, that is, a list 20of directories that Tcl searches, in the order in which it searches them. 21Copying tcl_uninum.so into any of these directories (with the name 22libuninum.so) will enable Tcl to find it. Note that if you copy 23into a directory other than the first one, if you have installed 24a previous version of the library in an earlier directory, the 25older version will mask the new one, so you should either install 26the library in the first one or make sure to delete any old copies 27that may be in other directories in the path. 28 29If you do not intend to use the C API you need not 30install it, but you should go through the configuration 31and build sequence. Executing ./configure configures some 32aspects of the Tcl API as well as the C API. 33Furthermore, the Tcl API has the file uninum.o as one 34of its components. 35 36Then do: 37 38make -f TclMakefile 39 40to build the library and (most likely after becoming root): 41 42make -f TclMakefile install 43 44to install it. 45 46If you are using the ActiveTcl distribution, there is a good chance 47that tclsh is not in the root path. If this is the case, your 48attempt at installation will fail because make will try to 49execute a little Tcl script using tclsh and won't be able 50to find tclsh. The easiest thing is to add the directory 51containing tclsh to your path. Suppose, for concreteness, 52that tclsh is in /usr/local/ActiveTcl/bin. If your root 53shell is bash, do: 54 55PATH=$PATH:/usr/local/ActiveTcl/bin 56 57If your root shell is tcsh, do: 58 59path = ($path /usr/local/ActiveTcl/bin) 60 61Then do: 62 63make -f TclMakefile install 64 65again and it should succeed. 66 67 68USE OF THE TCL LIBRARY 69 70Before using the library you should give the following command 71to import it: 72 73package require uninum 74 75If you give this command interactively to tclsh, it will respond with 76the version number of the library, e.g.: 77 782.4 79 80The Tcl interface to this library exposes five functions 81and two global variables. 82 83The function for converting strings to numbers is: 84 85UNStrToWNStr <Numeric String> <Number System> 86 87UNStrToWNStr takes as input a Unicode string representing an integer 88and returns a plain ASCII string containing the integer as a decimal 89string using the usual Western (that is, Indo-Arabic) digits. 90For example, the Unicode string \u4E03\u5341\u4E94, consisting of the 91Chinese numerals "7 10 5", is returned as "75". 92 93The NumberSystem argument specifies the expected number system. 94Most of the valid values are the names of particular number systems, 95such as "Arabic" or "Gurmukhi". If the string is not recognized as 96a number in the specified number system, an exception is raised. 97 98The NumberSystem argument may also be "any" or "all". In this case 99the input may be in any number system. The library will attempt to 100identify the number system and perform the appropriate conversion. 101An exception is raised if it is unable to identify the number 102system. 103 104The second function exposed is: 105 106StrGuessNumberSystem <Numeric String> 107 108It takes as argument a Unicode string representing an integer and returns 109a plain ASCII string containing the name of the number system. 110If it is unable to identify the number system, it returns the string 111"Unknown". If it is unable to identify the number system uniquely 112because the string consists entirely of ASCII zeroes, it returns 113the string "All_Zero". 114 115The function for converting numbers to strings is: 116 117WNStrToUNStr <Number> <Number System> 118 119Note that here the number system is specified as a string, 120e.g. "Gurmukhi". 121 122UninumNumberSystemMaximumValue takes as argument the name of a number 123system and returns the maximum value representable in that writing system, 124or "unlimited" where there is no limit. 125 126The fourth function is Tcl_ListNumberSystems. If its argument is 0, 127it lists the specific number system names usable for conversion from string 128to number and from number to string. If its argument is 1, it lists 129the cover terms suitable only for conversion of string to number. 130It returns a string in which number system names are separated by 131spaces. To obtain a Tcl list of number system names, split this string, 132e.g. 133 134set NumberSystemList [lsort [split [Tcl_ListNumberSystems 0]]] 135 136The final function is uninum_version, which returns the 137library version number. 138 139The first global variable is uninum_err. This has the same function 140as the C variable of the same name. It is set to zero prior to every 141call and is set to a non-zero value, defined in nsdefs.h, on error. 142You should check this variable after every call to UNStrToWNStr 143and should only use the value returned if uninum_err is 0. 144 145In addition to the errors that may occur in the C API, 146there is one error unique to the Tcl API: 147 148NS_ERROR_OUTSIDE_BMP 149 150This error occurs when the string generated contains characters 151outside the Basic Monolingual Plane of Unicode, that is, outside 152the range representable in 16 bits. Since Tcl in its normal form 153does not yet support Unicode outside the BMP, any string to be 154passed to Tcl is first checked for characters outside the BMP. 155If any are found, the string is not returned and uninum_err 156is set to NS_OUTSIDE_BMP_ERROR. 157 158The second global variable is tcl_uninum_badchar, which corresponds to the 159C variable uninum_badchar. If UNStrToWNStr encounters an unexpected 160character, it sets uninum_err and stores the codepoint of the unexpected 161character in tcl_uninum_badchar. See TestStringToNumber.tcl for an example 162of testing for this error and using the information in tcl_uninum_badchar. 163