blob: 4a3e3e4acbd56cc73b93281caeaf11a94ea726d4 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
<title>UIMA Tcl Annotators and the Tclator</title>
<h1>UIMA Tcl Annotators and the Tclator</h1>
<h2>What is a Tcl Annotator?</h2>
<p>A Tcl Annotator is a UIMA annotator component written in Tcl that can be used within the
UIMA SDK framework.
<h2>What is the Tclator?</h2>
<p>The Tclator is the linkage between the UIMA framework and a Tcl Annotator.
The Tclator is actually a UIMA C++ annotator which can be referenced by primitive annotator or CAS consumer descriptors.
The descriptor must define one configuration parameter, a second is optional:
<code>SourceFile</code> (mandatory) - a string holding the name of the Tcl module to run, and<br>
<code>DebugLevel</code> (optional) - an integer value that specifies the debug level for tracing. Default value is 0. A value of 101 turns on Tclator tracing. Values 1-100 are reserved for annotator developer use.
When the Tclator is initialized, e.g. at CPE initialization, the C++ code creates a Tcl interpreter, imports the specified script and calls the script's initialization method. Similarly, when other Tclator methods such as process() are called by the UIMA framework, the associated methods in the Tcl script are called.
<p>The Tclator also provides a Tcl library implementing an interface between Tcl and the UIMA APIs of the UIMA C++ framework.
<h2>Supported Platforms</h2>
<p>The Tclator has been tested with Tcl version 8.5 on Linux.
<p>The Tclator uses SWIG ( to implement the Tcl library interface to UIMA. Tested with SWIG version 2.0.10.</p>
<p>The UIMA C++ framework is required.
<h2>Tclator Distribution</h2>
<p>Tclator code is distributed in source form and must be built on the target platform.</p>
<p>Tclator source and sample code is located in the $UIMACPP_HOME/scriptators directory.</p>
<h2>Setting Environment Variables</h2>
<p>The Tclator requires the standard environment for UIMA C++ components.
<h2>Building and Installing the Tclator</h2>
Recursively copy the scriptators directory from the uimacpp distribution to a writable directory tree. CD to the writable scriptators/tcl directory.
<h3>On Linux</h3>
<li><code>Check that you have the required Tcl and Swig packages installed</code></li>
<h3>On Windows</h3>
<li><code>Modify winmake.cmd to set the paths for your Tcl and Swig installs</code></li>
<p>Build results are the C++ annotator, on Linux or tclator.dll on Windows.
<p>If you have write access to UIMA C++ distribution tree, on Linux copy to $UIMACPP_HOME/lib, and on Windows copy tclator.dll to $UIMACPP_HOME/bin.</p>
<p>If you don't have write access, make sure that|.dll is in the LD_LIBRARY_PATH or PATH, as appropriate.
<h2>Testing the Tclator</h2>
</>A simple Tcl regular expression annotator <code>sample.tcl</code> with descriptor <code>TclSample.xml</code> is included in the distribution. Use the descriptor as with any other UIMA annotator descriptor. Note that the Tcl script specified by the descriptor must be explicitly located, either with an absolute path or a path relative to the current directory of the running process.</p>
<h2>Known Tclator Issues</h2>
<li>Not all of the UIMA C++ APIs have been swig'ed. Missing functions can be added by extending the source file uima.i.
<li>UIMA Java components such as the CPE and the Vinci and SOAP service wrappers call analytics on different threads at different times. The Tcltator creates a "worker thread" for each Tcl analytic that is used to call into the interpreter.