AppleScript
TextSoap supports a scripting interface to allow you to access the text processing facilities within an AppleScript.
Change in 7.3: By popular request, we bring you the Return of the Agent. The agent will handle most commands (save actually cleaning text) directly. In the case of text cleaning, the textsoap7agent will launch the main app in agent mode to process the text as needed.
To use the new agent, replace "textsoapAgent" (from version 6) or "textsoap7" (from version 7.0-7.2) with "textsoap7agent". See the examples below.
Basic scripting
This basic example demonstrates how to use scripting. Commands are wrapped in tell statements to direct them to the application. Open the TextSoap scripting dictionary in the script editor for a list of all the commands and parameters.
tell application "textsoap7agent"
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 "textsoap7agent"
cleanClipboard with "Convert to Uppercase"
end tell
More Scripting Options
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.
tell application "textsoap7agent"
set groupValues to groupNames
set listValues to groupItems from ":Custom"
end tell
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 "textsoap7agent"
set resultValue to pickCleaner (cleanClipboard with resultValue)
end tell
tell application "textsoap7agent"
set resultValue to pickCleaner with starting group ":Custom"
cleanClipboard with resultValue
end tell
Cleaning Text Files with AppleScript
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 "textsoap7agent"
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