textsoapAgent is the background application that provides services for the main application and all the various plugins. It is the component that actually cleans the text. When the application (or plugin) needs to use a cleaner, it asks the textsoapAgent to perform the operation.
Scripting Additions are officially deprecated for the future. The Scripting Addition added several commands to the AppleScript language to provide functionality to access to TextSoap features. Starting with TextSoap 6.1, you can perform every action that the scripting addition performs by scripting the textsoapAgent.
This basic example demonstrates how to use the textsoapAgent. Commands are wrapped in tell statements to direct them to the agent. Open the textsoapAgent scripting dictionary in the script editor for a list of all the commands and parameters.
tell application "textsoapAgent"
set oldTextValue to "This is some starting text"
set newTextValue to cleanText oldTextValue with "Convert to Uppercase"
end tell
Here is an example of the cleanClipboard command. It will apply the given cleaner to the contents of the clipboard.
tell application "textsoapAgent"
cleanClipboard with "Convert to Uppercase"
end tell
Along with the basic apply cleaner, you can get information used by other plugins such as group names and cleaner lists. The following snippet demonstrates how to get the group names and cleaners out of a specific group. With this information, it is possible to build your own interface to TextSoap's features using AppleScript.
set groupValues to groupNames
set listValues to groupItems from ":Custom"
While you can build your own interface, sometimes you might not want to create one just to pick a cleaner. In that case, use the pickCleaner command for a quick solution. The pickCleaner will display a floating palette that you can pick a cleaner from and return the name of the cleaner chosen. The two examples shown below demonstrate using the pickCleaner to clean text from the clipboard.
The second example demonstrates the optional "with starting group". This option allows you to specify which group to display first.
tell application "textsoapAgent"
set resultValue to pickCleaner
cleanClipboard with resultValue
end tell
tell application "textsoapAgent"
set resultValue to pickCleaner with starting group ":Custom"
cleanClipboard with resultValue
end tell
Along with cleaning text within a script and cleaning the clipboard, you can also use AppleScript to clean text files. The cleanFile command will clean a text file. The agent will try to determine the type of file it is and currently supports RTF, RTFD, and plain text files.
Some files are text files but are not necessarily seen by the OS as such. In that case, you can provide a list of file extensions using the optional extensions parameter which will then be treated as plain text files.
When dealing with plain text files, you may also need to specify the encoding for both reading and writing. Both readEncoding and writeEncoding are optional parameters. If you do not specify, the agent will as the OS to make a best guess.
To support text encoding, two additional commands are included: textEncodingList and isValidTextEncoding. textEncodingList returns a list of available text encodings on your system. isValidTextEncoding can be used to test whether the given text encoding name is considered valid.
Here is a simple script that demonstrates the cleanFile command as well as the encoding related commands.
tell application "textsoapAgent"
set encodeList to textEncodingList
set myTextEncode to "Unicode (UTF-8)"
set eResult to isValidTextEncoding myTextEncode
set myfile to "/Volumes/TestFiles/mytestfile.cha"
cleanFile myfile with "Convert to Uppercase" extensions "cha" readEncoding "Unicode (UTF-8)"
end tell