From 086adff43587c02f12b80d3fc17e5f75c37b79ea Mon Sep 17 00:00:00 2001 From: Harvie Date: Sun, 29 Aug 2010 04:03:15 +0200 Subject: [PATCH] Improved documentation ;o) --- README | 30 ----------------- README.md | 75 +++++++++++++++++++++++++++++++++++++++++ purple/answerscripts.sh | 27 ++------------- 3 files changed, 77 insertions(+), 55 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 379526c..0000000 --- a/README +++ /dev/null @@ -1,30 +0,0 @@ -libPurple core-answerscripts plugin - - Framework for hooking scripts to respond received messages for various libpurple clients such as pidgin or finch - - This simple plugin just passes every single message received by any libPurple-based client (pidgin,finch) to sript(s) in user's home directory... So you can add various hooks to your pidgin or finch without need of writing and compiling own C plugin or messing with buggy perl plugin and restarting client after each change in plugin. - - There are already few sample (answer)scripts in purple directory, so you can check how easy it is to write some script for pidgin or finch... - - -Building & installation: - -- The libpurple header files are needed to compile the plugin. - -- To build and install : - You can compile the plugin using - $ make - and install it with - $ make install - This will install it in ~/.purple/plugins so that only the user who install it can use it. - $ make user - Install main script and sample answerscripts to ~/.purple/answerscripts.d/ - -- To install it for everybody on your computer, - $ make - $ su - # make install PREFIX="/path/to/libpurple" (this command as root user) - generally /path/to/libpurple is /usr or /usr/local. If you don't know the path then you can find out using - $ whereis libpurple - and look for the part before "/lib/libpurple.so". - - -Installing from packages: - - ArchLinux: http://aur.archlinux.org/packages.php?ID=37942 diff --git a/README.md b/README.md new file mode 100644 index 0000000..28b76cf --- /dev/null +++ b/README.md @@ -0,0 +1,75 @@ +#libPurple core-answerscripts plugin + * Framework for hooking scripts to **respond received messages** (and maybe bit more in future) for various **libpurple** clients such as **pidgin or finch** + * This simple plugin just passes every single message received by any libPurple-based client (pidgin,finch) to sript(s) in user's home directory... So **you can add various hooks.** + * There are already few sample (answer)scripts in ./purple directory, so you can check how easy it is to write some script for pidgin or finch... + +##What can this do for me? + +There are lot of hacks that you can do with this simple framework if you know some basic scripting. eg.: + +- **Forward your instant messages** to email, SMS gateway, text-to-speach (eg. espeak) or something... + - Smart auto-replying messages based on regular expressions + - Remote control your music player (or anything else on your computer) using instant messages +- Simple IRC/Jabber/ICQ bot (currently accepts PM only, you can run finch in screen on server) +- Providing some service (Searching web, Weather info, System status, RPG game...) +- BackDoor (**even unintentional one - you've been warned**) +- Loging and analyzing messages +- Connect IM with Arduino +- Annoy everyone with spam (and probably **get banned everywhere**) +- **Anything else that you can imagine...** (i'm looking forward to hearing your stories) + +##Writing own (answer)scripts + + * Check example scripts in **./purple/answerscripts.d/** to see how easy it is + * Basically + * Each time you receive message, the main **answerscripts.sh script (answerscripts.exe on M$ Windows) is executed** on background + * Every line that is outputed by this script to it's **STDOUT is sent** as response to message that executed it + * Following **environment values are passed** to the script: + * ANSW\_MSG (text of the message) + * ANSW\_FROM (who sent you message) + * ANSW\_PROTOCOL (protocol used to deliver the message. eg.: jabber, irc,...) + * ANSW\_STATUS (unique ID of status. eg.: available, away,...) + * ANSW\_STATUS\_MSG (status message set by user) + * **WARNING: You should mind security (don't let attackers to execute their messages/nicks!)** + * I guess that you will want to use more than one answerscript, so i made such answerscript which will execute all answerscripts in **~/.purple/answerscripts.d** + * It's quite smart and all you need to do is set the filenames and permissions of answerscripts in that directory properly... + * See it's (**./purple/answerscripts.sh**) comments for rest of documentation... + +###Example +Following answerscript will reply to each incoming message if you are not available. Reply will consist of two messages: one with username of your buddy who sent you a message and text of that message; and second with your status message. Simple huh? + + #!/bin/sh + [ "$ANSW_STATUS" != 'available' ] && echo "<$ANSW_FROM> $ANSW_MSG" && echo "My status: $ANSW_STATUS_MSG"; + +##Building & installation + +###From packages +- ArchLinux: http://aur.archlinux.org/packages.php?ID=37942 +###Manually +- The libpurple header files are needed to compile the plugin. +- To build and install : + You can compile the plugin using + + $ make + + and install it with + + $ make install + + This will install it in ~/.purple/plugins so that only the user who install it can use it. + + $ make user + + Install main script and sample answerscripts to ~/.purple/answerscripts.d/ + +- To install it for everybody on your computer, + + $ make + $ su + # make install PREFIX="/path/to/libpurple" (this command as root user) + + generally /path/to/libpurple is /usr or /usr/local. If you don't know the path then you can find out using + + $ whereis libpurple + + and look for the part before "/lib/libpurple.so". diff --git a/purple/answerscripts.sh b/purple/answerscripts.sh index 4dc0e8a..4410ee4 100755 --- a/purple/answerscripts.sh +++ b/purple/answerscripts.sh @@ -1,32 +1,9 @@ #!/bin/sh - +# # This file is called for every message received by libpurple clients (pidgin,finch,...) -# - Following env values are passed to this script: -# - ANSW_MSG (text of the message) -# - ANSW_FROM (who sent you message) -# - ANSW_PROTOCOL (protocol used to deliver the message. eg.: jabber, irc,...) -# - ANSW_STATUS (unique ID of status. eg.: available, away,...) -# - ANSW_STATUS_MSG (status message set by user) -# - WARNING: You should mind security (don't let attackers to execute their messages/nicks!) -# - Each line of output is sent as reply to that message -# - You can try to rewrite this script in PERL or C for better performance (or different platform) +# - You can try to rewrite this script in PERL or C for better performance (or different platform) - let me know # - On M$ Windows answerscripts.exe from libpurple directory will be called instead of this script # -# Basic example can look like this: -# [ "$ANSW_STATUS" != 'available' ] && echo "<$ANSW_FROM> $ANSW_MSG" && echo "My status: $ANSW_STATUS_MSG"; -# -# There are lot of hacks that you can do with this simple framework if you know some scripting. eg.: -# - Forward your instant messages to email, SMS gateway, text-to-speach (eg. espeak) or something... -# - Smart auto-replying messages based on regular expressions -# - Remote control your music player (or anything else on your computer) using instant messages -# - Simple IRC/Jabber/ICQ bot (accepts PM only, you can run finch in screen on server) -# - Providing some service (Searching web, Weather info, System status, RPG game...) -# - BackDoor (even unintentional one - you've been warned) -# - Loging and analyzing messages -# - Connect IM with Arduino -# - Annoy everyone with spam (and probably get banned everywhere) -# - Anything else that you can imagine... -# # Maybe you will want to add more hooks for receiving messages, so i've made following script # - It just executes all +x files in answerscripts.d directory so you should do your magic there # - To disable some of those scripts simply use: chmod -x ./script -- 2.30.2