head	1.19;
access;
symbols
	v0_67:1.18
	v0_65:1.18
	v0_64:1.18
	v0_63:1.18
	v0_62:1.18
	gaim_0_60:1.18
	v0_60:1.18
	ZERO_DOT_FUCKING_SIXTY:1.18
	v0_59_9:1.14
	v0_59_8:1.14
	gaim_0_59_7:1.14
	v0_60alpha3:1.17
	v0_59_6:1.14
	v0_59_5:1.14
	v0_59_4:1.14
	v0_59_3:1.14
	v0_59_2:1.14
	gtk1-stable:1.14.0.2
	v059:1.14
	v058:1.13
	v057:1.13
	v056:1.13
	v055:1.13
	v0_54:1.13;
locks; strict;
comment	@# @;


1.19
date	2003.08.24.04.22.49;	author chipx86;	state dead;
branches;
next	1.18;

1.18
date	2003.03.10.05.30.15;	author seanegan;	state Exp;
branches;
next	1.17;

1.17
date	2002.09.28.08.08.14;	author seanegan;	state Exp;
branches;
next	1.16;

1.16
date	2002.09.26.07.37.51;	author seanegan;	state Exp;
branches;
next	1.15;

1.15
date	2002.08.28.02.38.18;	author seanegan;	state Exp;
branches;
next	1.14;

1.14
date	2002.05.29.01.44.39;	author seanegan;	state Exp;
branches;
next	1.13;

1.13
date	2001.10.18.12.12.36;	author warmenhoven;	state Exp;
branches;
next	1.12;

1.12
date	2001.10.15.20.08.14;	author warmenhoven;	state Exp;
branches;
next	1.11;

1.11
date	2001.10.15.19.52.44;	author warmenhoven;	state Exp;
branches;
next	1.10;

1.10
date	2001.09.24.19.32.57;	author warmenhoven;	state Exp;
branches;
next	1.9;

1.9
date	2001.09.22.09.14.27;	author warmenhoven;	state Exp;
branches;
next	1.8;

1.8
date	2001.09.10.22.27.47;	author warmenhoven;	state Exp;
branches;
next	1.7;

1.7
date	2001.04.30.09.03.58;	author warmenhoven;	state Exp;
branches;
next	1.6;

1.6
date	2001.04.20.23.04.48;	author warmenhoven;	state Exp;
branches;
next	1.5;

1.5
date	2000.11.16.10.06.11;	author warmenhoven;	state Exp;
branches;
next	1.4;

1.4
date	2000.08.31.01.40.57;	author warmenhoven;	state Exp;
branches;
next	1.3;

1.3
date	2000.08.30.23.27.01;	author warmenhoven;	state Exp;
branches;
next	1.2;

1.2
date	2000.08.29.05.25.13;	author warmenhoven;	state Exp;
branches;
next	1.1;

1.1
date	2000.08.23.20.37.16;	author warmenhoven;	state Exp;
branches;
next	;


desc
@@


1.19
log
@Removed the old PERL-HOWTO
@
text
@So, you wanna write a perl script.

Perl scripts in Gaim can be very useful.  Although they can't directly manipulate
Gaim data like a plugin, or provide any sort of UI, they're portable, easy to develop
rapidly and extremely powerful when manipulating incoming and outgoing messages.

This document assumes you know perl--Gaim perl scripts work exactly like normal perl
scripts, with a few extra commands you can use.

The first thing Gaim will do with your plugin (provided it's in $prefix/lib/gaim or
$HOME/.gaim/) is look for and call a function called "description".  description()
gives Gaim the information it will use in the plugins dialog--script name, version,
your name--all sorts of good things.  Let's look at an example:

	sub description {
		my($a, $b, $c, $d, $e, $f) = @@_;
		("Example", "1.0", "An example Gaim perl script that does nothing 
		particularly useful:\n\t-Show a dialog on load\n\t-Set user idle for 
		6,000 seconds\n\t-Greets people signing on with \"Hello\"\n\t-Informs 
		you when script has been loaded for one minute.", 
		"Eric Warmenhoven &lt;eric\@@warmenhoven.org>", "http://gaim.sf.net", 
		"/dev/null");
	}

This pushes what's needed to the perl stack.  What is all that stuff?
	$a - Name 
	$b - Version
	$c - Description
	$d - Authors
	$e - Webpage
	$f - Icon (this is the path to an icon Gaim will use for your script)

It should be noted that this information will be formatted according to Pango's
markup language--a language akin to HTML.  This is neat in that it lets you bold
and italicize your description and stuff, but it's important you take care to 
properly escape stuff (notice the &lt; in $d).

Now, for the Gaim-specific perl functions (if you know x-chat scripts, you'll
feel right at home):

GAIM::register(name, version, shutdownroutine, unused)
	Just like X-Chat. This is the first function your script should call.
	shutdownroutine is a function that will be called when the script
	gets unloaded (like when gaim gets closed). This function returns
	gaim's version number.  This function MUST use the same Name and Version
	given in description()--the plugin won't work otherwise.  This returns a
	handle--you want to hold on to this.

	The handle is what Gaim will use to distinguish your script from any others
	running.  It's actually a string--the path to the script, but you'll probably
	never need to know that.  As long as you just hold on to it and don't change it
	everything should work fine.  You need it for GAIM::add_event_handler and 
	GAIM::add_timeout_handler.

GAIM::get_info(integer, ...)
	This function returns different information based on the integer passed
	to it.
	0 - the version of gaim you're running ("0.10.0" for example).
	1 - the list of connection ids
	2 - given a connection index, the protocol it uses (as an int)
	3 - given a connection index, the screenname of the person
	4 - given a connection index, the index in the users list
	5 - the list of names of users
	6 - the list of protocols of the users
	7 - given a connection index, the name of the protocol (as a string)

GAIM::print(title, message)
	This displays a nice little dialog window.


GAIM::buddy_list(index)
	This returns the buddy list (no groups, just the names of the buddies)
	for the specified connection.

GAIM::online_list(index)
	This returns the list of online buddies for the specified connection.


GAIM::command(command, ...)
	This sends commands to the server, and each command takes various
	arguments. The command should be self-explanatory:
	"signon" - the second arg is the index of the user to sign on
	"signoff" - the optional second arg is the connection index to sign off.
		    if no args are given, all connections are signed off.
	"away" - the second arg is the away message
	"back" - no args.
	"idle" - the second arg is how long (in seconds) to set the idle time
		 (this sets the idle time for all connections)
	"warn" - the second arg is the name of the person to warn. this is
		 especially evil since it warns the person from every 
		 connection.  The third argument is 1 if you want to warn
		 anonymously.  If 0 or ommitted, it will warn normally.
	"info" - the second arg is the connection index whose info you want to set,
	         and the third arg is what you want to set your profile to.

GAIM::user_info(index, nick)
	Returns 8 data items:
		the screenname of the buddy
		the alias of the buddy
		"Online" or "Offline"
		their warning level
		signon time, in seconds since the epoch
		idle time, in seconds (?)
	Since buddy lists are per-connection this goes through the connections
	until it finds a matching buddy name.

GAIM::write_to_conv(to, wflags, what, who)
	This displays a message into a conversation window. <wflags> is the
	message-style and works like that:
		wflags==0: display message as if received by <who>
		wflags==1: display message as if sent by <who>
		wflags==2: display system message

GAIM::serv_send_im(index, who, what, auto)
	Sends what from the connection index to who. :)

GAIM::print_to_conv(index, who, what, auto)
	Convenience function; combination of write_to_conv and serv_send_im.

GAIM::print_to_chat(index, room, what)
	Room is actually an int. Read SIGNALS to find out why.

GAIM::add_event_handler(handle, event, function)
	This is the most important of them all. This is basically exactly like
	gaim_signal_connect for plugins. You pass the handle returned by GAIM::register,
	which event you want to connect to (a string with the same name as the events for 
	plugins, see SIGNALS), and a string with the name of the function you want called. 
	Simple enough?

	When this is triggered, the arguments will be passed in @@_ and are broken
	into a list. This is different from all previous versions of Gaim, where you
	had to parse the arguments yourself. The arguments are quite different from
	what's passed to the plugins, though they are very similar, and you should
	read perl.c to figure out what they are. The arguments are passed after the
	plugins have had their way with them. Perl scripts cannot modify the values
	so that gaim knows what the changes are.

	Perl scripts can short-circuit certain events (namely event_im_send,
	event_im_recv, event_chat_send, event_chat_recv and event_set_info). To
	short-circuit an event simply return a non-0 value. This will cause all
	subsequent scripts and the event itself to never happen (i.e. the user
	won't see it happen, and _send events won't actually send).

GAIM::remove_event_handler(event, function)
	This removes the event handler for the specified event that
	calls "function" as its handler.  The event handler must have been
	previously added with GAIM::add_event_handler.

GAIM::add_timeout_handler(handle, integer, function, args)
	This calls function after integer number of seconds. It only calls function
	once, so if you want to keep calling function, keep readding the handler.
	Args is a string that you'd like to have passed to your timeout handler; it's
	optional.  Handle is the handle returned by GAIM::register--it is not optional.

GAIM::play_sound(int sound)
	Plays a sound using whatever method the user has selected. The argument is
	one of the following numbers:

	0	Buddy logs in
	1	Buddy logs out
	2	Message received
	3	Message received begins conversation
	4	Message sent
	5	Person enters chat
	6	Person leaves chat
	7	You talk in chat
	8	Others talk in chat
	9	Default buddy pounce sound
	10	Someone says your name in chat
@


1.18
log
@This is a new buddy list.

Lots of things about it just Don't Work.  I probably already know about those
things, and you'd just be wasting my time in submitting a bug report about it.

I decided that instead of getting it to all work perfectly before committing,
that I'd get it in cvs, and slowly fix it with regular commits.  That way, it's
easier to keep track of things, and other developers can help.  Plus, I'm getting
pissed off at the buddy list and want it to die.  It's kinda boring, and doing nothing
but the buddy list for such a long time has just gotten me very bitter.

After 0.60 is released later this week, Gaim will resume being fun.  This week is
going to be very stressful, though, I'm sure.

Things you ought to know about this buddy list:
- It crashes
- It leaks
- There's no way to edit the buddy list, or access offline buddies
- Most of the menus and buttons and whatnot just plain ol' don't work.
- Status icons are only implemented for AIM.

That's mostly just because I'm lazy.  As such, you may want to be wary of updating this.
If you do decide to update this, you may want to learn "cvs update -D yesterday" as well :)

All the art there is just placeholder art.

You probably won't really have as many problems as it sounds like you will from reading this.
This message is extra-negative to stress that I don't want to be bothered with complaints about
something not working about it :).  I'll repeat: If something doesn't work, I probably already
know about it.

If you want to actually help with something, I'd be delighted to have it.  IM me.

-s.
@
text
@@


1.17
log
@I made my perl script unloading not suck (as much).  Now you may port your
perl scripts--use gaim.pl and PERL-HOWTO as references.
@
text
@a103 13
		user class, an integer with bit values
			AOL		1
			ADMIN		2
			UNCONFIRMED	4
			NORMAL		8
			AWAY		16
		their capabilites, an integer with bit values
			BUDDYICON	1
			VOICE		2
			IMIMAGE		4
			CHAT		8
			GETFILE		16
			SENDFILE	32
@


1.16
log
@In the interest of continued progress, I pulled what's usable out of my
development tree and am committing it.

Here, we have gotten rid of the plugins dialog and perl menu under Tools and
put them both in preferences.  Perl scripts now work like plugins--you have
to load them explicitly (it will probe $prefix/lib/gaim and $HOME/.gaim for
them) and you can unload them (although right now, this is entirely unreliable)
Oh, and I broke all your perl scripts.  Sorry about that.  Don't try fixing
them yet, though--I'm gonna make unloading single scripts more reliable
tommorow.

I should also finish Phase Two tommorow as well.
@
text
@d45 9
a53 1
	gaim's version number.
d136 1
a136 1
GAIM::add_event_handler(event, function)
d138 4
a141 3
	gaim_signal_connect for plugins. You pass which event you want to connect to
	(a string with the same name as the events for plugins, see SIGNALS), and a
	string with the name of the function you want called. Simple enough?
d162 1
a162 1
GAIM::add_timeout_handler(integer, function, args)
d166 1
a166 1
	optional.
@


1.15
log
@A few patches.  Brian--tell me what your last name is, and I'll put it in. ;)
@
text
@d1 1
a1 2
This is really the wrong place for a HOWTO on writing perl scripts for gaim,
but there didn't seem to be a much better place.
d3 37
a39 27
If you've ever written a perl script for X-Chat then you've basically written
one for gaim as well. perl.c in gaim's source is basically an exact copy of
X-Chat's perl.c file, with small modifications to suit Gaim rather than IRC.

Basically the reason for including perl is based on the experience with the
plugins. X-Chat's docs on Perl Scripting sums it up nicely:
   it's not quite as simple to stick a module together in C and make it
   stable compared to the development time of perl code

Plugins are more powerful as they can directly access gaim's functions and
variables; as such they should be used for things like modifying the UI or
when something takes quite a bit of trickery not offered by perl. But for
the most part things should be written in Perl. It's more stable than
plugins.

There's a really quick simple perl script in this directory, gaim.pl, that
should show most of the functions. Most things should be self-explanatory.

There's one thing you need to be aware of in perl scripts for gaim. Gaim
supports multiple connections, and perl deals with them by using a unique
identifier for each of them (that's a fancy way of saying that perl scripts
use the memory address of the connection). 

Everything available in normal perl scripts should be available in gaim's
perl interface, so I'm not going to bother describing that. The important
things are the functions provided by gaim's internal GAIM module, which is
what most of this document is about. So, onto the functions.
@


1.14
log
@Perl can play sounds!
@
text
@d134 9
a142 4
	event_im_recv, event_chat_send, and event_chat_recv). To short-circuit an
	event simply return a non-0 value. This will cause all subsequent scripts
	and the event itself to never happen (i.e. the user won't see it happen,
	and _send events won't actually send).
@


1.13
log
@I got an itty bitty diff for you now ;-)
@
text
@d144 16
@


1.12
log
@Artem Litvinovich's patch
@
text
@d6 1
a6 1
X-Chat's perl.c file, with small modifications to suit GAIM rather than IRC.
@


1.11
log
@malsyned's patch for args in perl.
@
text
@d139 1
a139 1
GAIM::add_timeout_handler(integer, function)
d142 2
@


1.10
log
@gaim.pl works like it should now
@
text
@d125 5
a129 4
	When this is triggered, the arguments will be passed in @@_ and are not
	broken into a list, but left as one long string. You'll have to parse those
	yourself with split. (Sounding exactly like X-Chat yet?) The arguments are
	the exact same as those passed to the plugins, and are passed after the
a137 4

	Names of buddies and chat rooms will be in quotes, and all other
	values (like text messages) will not be. (Watch the debug window to get a
	better feel for this, or better yet, look at the bottom of plugins.c.)
@


1.9
log
@you say potato, i say potato
you say tomato, i say tomato
potato, potato
tomato, tomato
let's call the whole thing off.

*sigh*. it just doesn't work as well when it's typed. but you wouldn't want to hear me sing it.
@
text
@d48 1
@


1.8
log
@Stefan Weyergraf and Artem Litvinovich both submitted patches that do similar things. I ended up taking Stefan's patch because it did more things than Artem's did.
@
text
@d22 5
d42 6
a47 2
	1 - the list of currently online screennames
	2 - given a screenname, the protocol(s) it(/they) use(s) (as ints)
d53 1
a53 1
GAIM::buddy_list(name)
d55 1
a55 1
	for the specified account
d57 2
a58 2
GAIM::online_list(name)
	This returns the list of online buddies for the specified account.
d64 3
a66 3
	"signon" - the second arg is the screenname to sign on
	"signoff" - the optional second arg is who to sign off. if no args are
		    given, all names are signed off.
d75 2
a76 1
	"info" - the second arg is what you want to set your profile to.
d78 1
a78 1
GAIM::user_info(nick)
d109 5
a113 11
GAIM::print_to_conv(who, what, auto)
	The question is not what does this do, it's who does this do it as. The
	answer is "whatever the default is". It uses whichever connection is
	selected in the conversation window's menu. If the conversation window
	didn't exist beforehand, then it's the default (first) connection.  If
	auto is one, it will send as an auto (read: away) message.  If 0 or
	ommitted, it will send normally.

GAIM::print_to_chat(room, what)
	This goes through each connection. If it finds a room matching the name,
	it'll print the message to that room.
d115 2
a116 2
GAIM::serv_send_im(who, what, auto)
	Same as print_to_conv, but it does not display the message.
@


1.7
log
@na na na na, na na na na, hey hey hey, good bye (you say good bye, while i say hello)
@
text
@d92 7
d111 2
@


1.6
log
@fun stuff
@
text
@d66 1
a66 1
	"setinfo" - the second arg is what you want to set your profile to.
@


1.5
log
@wow, perl got updated.
@
text
@d63 4
a66 1
		 especially evil since it warns the person from every connection.
d92 1
a92 1
GAIM::print_to_conv(who, what)
d96 3
a98 1
	didn't exist beforehand, then it's the default (first) connection.
@


1.4
log
@yay, i think perl is finally working well
@
text
@d6 1
a6 1
X-Chat's perl.c file, with small modifications to suit AIM rather than IRC.
d24 1
a24 1
things are the functions provided by gaim's internal AIM module, which is
d27 1
a27 1
AIM::register(name, version, shutdownroutine, unused)
d33 1
a33 1
AIM::get_info(integer)
d37 2
a38 2
	1 - the screenname to last attempt to sign on
	2 - either "Offline", "TOC", or "Oscar"
d40 1
a40 1
AIM::print(title, message)
d44 1
a44 1
AIM::buddy_list()
d46 1
d48 2
a49 2
AIM::online_list()
	This returns the list of online buddies.
a50 4
AIM::deny_list()
	This returns the deny list. This is probably going to be modified before
	0.10.0 is released to return either the deny or the permit list and the
	current mode.
d52 1
a52 2

AIM::command(command, ...)
d55 3
a57 2
	"signon" - no args.
	"signoff" - no args.
d61 3
a63 1
	"warn" - the second arg is the name of the person to warn
d65 2
a66 2
AIM::user_info(nick)
	Returns 7 data items:
d68 1
d86 2
d89 5
a93 6
		This is probably going to change before 0.10.0 is released to
		also return the alias of the buddy.

AIM::print_to_conv(who, what)
	This should be obvious. If you can't figure this out on your own, you
	shouldn't be using a computer.
d95 3
a97 2
AIM::print_to_chat(room, what)
	This should be just as obvious as the last command.
d100 1
a100 1
AIM::add_event_handler(event, function)
d111 9
a119 4
	so that gaim knows what the changes are. Unlike X-Chat, perl scripts cannot
	short-circut gaim (that is, your script will be called in order it was added,
	despite what other scripts do, and afterwards, execution will continue as
	normal). Names of buddies and chat rooms will be in quotes, and all other
d123 1
a123 1
AIM::add_timeout_handler(integer, function)
@


1.3
log
@ha, i'm smart. i should commit to things.
@
text
@d19 3
d113 2
a114 1
	values (like text messages) will not be.
d118 1
a118 1
	once, so if you want to keep calling function, keep reading the handler.
@


1.2
log
@more perl stuff
@
text
@a18 4
Right now, the only way to test that your script is working correctly is to
load the perl plugin and load the script through that. (This is also the only
way I have of knowing that the interface is working correctly.)

d94 1
d97 3
a99 3
	gaim_signal_connect. You pass which event you want to connect to (a string
	with the same name as the events for plugins, see SIGNALS), and a string
	with the name of the function you want called. Simple enough?
d101 1
a101 1
	When this is triggered, the same arguments will be passed in @@_ and are not
d109 2
a110 1
	normal).
@


1.1
log
@don't get too excited, perl doesn't do many useful things yet
@
text
@d20 2
a21 4
load the perl plugin and load the script through that. Though, right now
there really isn't much point in writing a script, since the two major
functions in the AIM module (message_handler and command_handler) haven't
been implemented yet.
d98 15
a112 5
AIM::add_message_handler
	This actually hasn't been implemented yet, so don't worry about it

AIM::add_command_handler
	This hasn't been implemented yet either. Pay no attention.
@

