wiki:Documentation/AppleScripting

TracNav(Documentation)? This is part of the Documentation Project, please help document Colloquy if you know anything that would be relevant here for other users to know about.

AppleScripting

  1. Compatibility with scripts written for Colloquy 2C11 and before
  2. Scripting Basics
  3. Opening The Dictionary
  4. Colloquy's AppleScript dictionary suites
  5. Caveat
  6. Posting AppleScripts on the Colloquy Documentation Pages

See also Writing PlugIns for Colloquy in the Development Docs

Compatibility with scripts written for Colloquy 2C11 and before

In order to provide enhanced scripting support, Colloquy’s AppleScript terminology has been completely re-written. Due to the extensive nature of the scripting enhancements, scripts written to work with previous versions of Colloquy are not guaranteed to be compatible with the 2D9 release. All scripts should be validated against the AppleScript dictionary in Colloquy 2D9.

Scripting Basics

The very first thing you may need to do is to send some text to a channel or 'PM'. This is achieved most simply in the following way:

tell application "Colloquy"
	tell active panel of front window
		send message "hello world"
	end tell
end tell

The 'tell target' is of enormous importance. When sending some chat text, it is important to specify, above all, the target of that message. This is because colloquy may be connected to multiple servers, via IRC or SLC, each with multiple chat rooms, and with any number of private chat sessions running. If you know that you want to send some text to the 'current' chat panel, i.e. the one that would receive whatever you typed in the frontmost window, use the syntax given here (active panel of front window). Consider that 'window 1' is a synonym for 'front window' if you would prefer to use it.

If you intend to use this form often in your scripts, keep in mind that any switching between channels, servers and private chats in the user interface will change the recipient of any scripted messages, with unpredictable results.

The target (active panel of front window) gets you a reference via the user interface which is of limited usefulness. For more sophisticated usage, for example, creating bots that can run discrete and individual 'conversations' or transactions with mulitple chat rooms or private chats at the same time, you will need to be more specific about which chat room or which private chat should receive the message, independently of which window is frontmost and which panel is active.

The following example will send a message to every chat room connected via connection 1:

tell application "Colloquy"
	tell connection 1
		repeat with cr in every chat room
			tell cr
				send message "Hi! I'm back"
			end tell
		end repeat
	end tell
end tell

...or even more simply...

tell application "Colloquy"
	tell every chat room of connection 1 to send message "Hi! I'm back"
end tell

When writing AppleScript PlugIns, the target for a message is often provided as an optional parameter to the handler. For example the callback 'process incoming chat message' sends a parameter 'in', which you can use to (for example) reply to the source of the incoming message.

This example can be used to join rooms in a throttled fashion so you don't get kicked for excess_flood

tell application "Colloquy"
 	(* Change these to your rooms *)
 	set rooms to {"#colloquy", "#xchat", "#unix"}
 	(* get connection object *)
 	(* set connection to first connection of application *)
 	tell connection 1
 		(* join the rooms *)
 		repeat with room in rooms
 			join chat room room
 			delay 1
 		end repeat
 	end tell
 end tell

[applescript://com.apple.scripteditor?action=new&script=tell%20application%20%22Colloquy%22%0D%09%28%2A%20Change%20these%20to%20your%20rooms%20%2A%29%0D%09set%20rooms%20to%20%7B%22%23colloquy%22%2C%20%22%23xchat%22%2C%20%22%23unix%22%7D%0D%09%28%2A%20get%20connection%20object%20%2A%29%0D%09%28%2A%20set%20connection%20to%20first%20connection%20of%20application%20%2A%29%0D%09tell%20connection%201%0D%09%09%28%2A%20join%20the%20rooms%20%2A%29%0D%09%09repeat%20with%20room%20in%20rooms%0D%09%09%09join%20chat%20room%20room%0D%09%09%09delay%201%0D%09%09end%20repeat%0D%09end%20tell%0Dend%20tell Click here to open the script in Script Editor.]

Opening The Dictionary

All AppleScriptable applications provide 'dictionaries' of scripting terminology, describing the various classes of object and their relations to each other, commands and callback handlers. As with any other scriptable application, to see Colloquy's AppleScript dictionary from within Script Editor use "File" -> "Open Dictionary", then select Colloquy from the list.

If you wish to streamline this action (it can take a little time to build the list of scriptable applications), make a script to do it for you:

tell application "Script Editor" to open (path to application "Colloquy")

[applescript://com.apple.scripteditor?action=new&script=tell%20application%20%22Script%20Editor%22%20to%20open%20%28path%20to%20application%20%22Colloquy%22%29%0D Click here to open the script in Script Editor]

Some scripts are designed to be invoked by colloquy itself (see AppleScript PlugIns ), but it can also be useful to create utility scripts such as these for more general scripting (or debugging) tasks.

Such utility scripts may be usefully saved in ~/Library/Scripts/Colloquy/? where they will be available via a submenu of the script menu at all times, or in ~/Library/Scripts/Applications/Colloquy/? where they will be available via the script menu when Colloquy is the frontmost application, and hidden at other times.

TIP
Save scripts in:

~/Library/Scripts/Applications/Colloquy/

(which is created automatically by Colloquy) and then make an alias to that folder, called 'Colloquy' in

~/Library/Scripts/

so that you get the best of both worlds. When Colloquy is frontmost, all the Colloquy scripts are easily accessible at the bottom of the Script Menu, but they are still available via a submenu at all other times.

This is a general scripting tip which applies to all other scriptable applications.

Colloquy's AppleScript dictionary suites

Colloquy's AppleScript dictionary has 3 main suites:

  • The "Chat Core" suite
  • The "Chat Plug-In" suite
  • The "Colloquy" suite

The "Chat Core" suite allows for connecting/disconnecting joining rooms and sending messages.

The "Chat Plugin-In" suite specifies a number of events allowing action to be taken for most standard irc events. (See also AppleScript PlugIns)

The "Colloquy" suite allows for interaction with the application and some more irc functions.

Caveat

Using IRC manually it's possible to be impolite, antisocial, aggressive, unpleasant, irritating and generally to accumulate bad karma of all kinds. Typically this will result in you getting kicked or banned from the chatroom in question. Please consider then how much broader are the horizons for causing undesirable effects when you are using a scripting language. In severe cases of network abuse people can (and are) routinely banned from entire servers.

For this reason it is strongly recommended that you open a private channel to carry out testing where possible, so that you don't disrupt the chat experience for others. If you are learning to script colloquy, and seek a tolerant atmosphere for endless iterations of your test messages, you may use the #colloquy-test channel, which even has some human beings looking at it from time to time. In a rare moment you may even find some third party to test your script for you too.

Posting AppleScripts on the Colloquy Documentation Pages

If you wish to add scripts to this or other documentation pages using Apple's handy applescript:// URL protocol, you can get a script to format your code for Wiki by [applescript://com.apple.scripteditor?action=new&script=%2D%2D%20This%20script%20encodes%20the%20AppleScript%20text%20currently%20on%20the%20clipboard%20in%20a%20format%20suitable%20for%20Colloquy%27s%20Wiki%20pages%0Dtry%0D%09set%20this_text%20to%20%28get%20the%20clipboard%29%20as%20string%0D%09%0D%09set%20encodedText%20to%20my%20encode_text%28this_text%29%0D%09%0D%09set%20theParagraphs%20to%20%28paragraphs%20of%20this_text%29%0D%09set%20AppleScript%27s%20text%20item%20delimiters%20to%20return%20%26%20%22%20%22%0D%09set%20insetText%20to%20theParagraphs%20as%20string%0D%09set%20AppleScript%27s%20text%20item%20delimiters%20to%20%22%22%0D%09%0D%09set%20URL_opening%20to%20%22%5Bapplescript%3A%2F%2Fcom%2Eapple%2Escripteditor%3Faction%3Dnew%26script%3D%22%0D%09%0D%09set%20the%20clipboard%20to%20%28%22%7B%7B%7B%22%20%26%20return%20%26%20insetText%20%26%20return%20%26%20%22%7D%7D%7D%22%20%26%20return%20%26%20URL_opening%20%26%20encodedText%20%26%20%22%20Click%20here%20to%20open%20the%20script%20in%20Script%20Editor%2E%5D%22%29%0D%09display%20dialog%20%22The%20encoded%20script%20has%20been%20placed%20on%20the%20clipboard%2E%22%20buttons%20%7B%22OK%22%7D%20default%20button%201%20with%20icon%201%20giving%20up%20after%202%0Don%20error%20error_message%0D%09display%20dialog%20error_message%20buttons%20%7B%22Cancel%22%7D%20default%20button%201%0Dend%20try%0D%0D%2D%2D%20this%20sub%2Droutine%20is%20used%20to%20encode%20text%20%0Don%20encode_text%28this_text%29%0D%09set%20the%20acceptable_characters%20to%20%22abcdefghijklmnopqrstuvwxyz0123456789_%22%0D%09set%20the%20encoded_text%20to%20%22%22%0D%09set%20the%20character_list%20to%20%7B%7D%0D%09repeat%20with%20this_char%20in%20this_text%0D%09%09set%20this_char%20to%20the%20contents%20of%20this_char%0D%09%09if%20this_char%20is%20in%20the%20acceptable_characters%20then%0D%09%09%09set%20the%20end%20of%20the%20character_list%20to%20this_char%0D%09%09else%0D%09%09%09set%20the%20end%20of%20the%20character_list%20to%20encode_char%28this_char%29%0D%09%09end%20if%0D%09end%20repeat%0D%09return%20%28the%20character_list%29%20as%20string%0Dend%20encode_text%0D%0D%2D%2D%20this%20sub%2Droutine%20is%20used%20to%20encode%20a%20character%20%0Don%20encode_char%28this_char%29%0D%09set%20the%20ASCII_num%20to%20%28the%20ASCII%20number%20this_char%29%0D%09set%20the%20hex_list%20to%20%7B%220%22%2C%20%221%22%2C%20%222%22%2C%20%223%22%2C%20%224%22%2C%20%225%22%2C%20%226%22%2C%20%227%22%2C%20%228%22%2C%20%229%22%2C%20%22A%22%2C%20%22B%22%2C%20%22C%22%2C%20%22D%22%2C%20%22E%22%2C%20%22F%22%7D%0D%09set%20x%20to%20item%20%28%28ASCII_num%20div%2016%29%20%2B%201%29%20of%20the%20hex_list%0D%09set%20y%20to%20item%20%28%28ASCII_num%20mod%2016%29%20%2B%201%29%20of%20the%20hex_list%0D%09return%20%28%22%25%22%20%26%20x%20%26%20y%29%20as%20string%0Dend%20encode_char clicking here.]

Last modified 4 years ago Last modified on Feb 25, 2010 8:32:39 AM