diff options
Diffstat (limited to 'doc/en/weechat.en.xml')
| -rw-r--r-- | doc/en/weechat.en.xml | 3483 |
1 files changed, 3483 insertions, 0 deletions
diff --git a/doc/en/weechat.en.xml b/doc/en/weechat.en.xml new file mode 100644 index 000000000..6ac8678c7 --- /dev/null +++ b/doc/en/weechat.en.xml @@ -0,0 +1,3483 @@ +<?xml version="1.0" encoding="iso-8859-1"?> + +<!-- + +WeeChat documentation (english version) + +Copyright (c) 2003-2006 by FlashCode <flashcode@flashtux.org> + +This manual is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This manual is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + +--> + +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"file:///usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd" +[ + <!ENTITY config.xml SYSTEM "config.xml"> + <!ENTITY weechat_commands.xml SYSTEM "weechat_commands.xml"> + <!ENTITY irc_commands.xml SYSTEM "irc_commands.xml"> + <!ENTITY key_functions.xml SYSTEM "key_functions.xml"> +]> + +<book lang="en"> + + <bookinfo> + + <title>WeeChat 0.1.7-cvs - User guide</title> + <subtitle>Fast, light and extensible IRC client</subtitle> + + <author> + <firstname>Sébastien</firstname> + <surname>Helleu</surname> + <email>flashcode AT flashtux.org</email> + </author> + + <copyright> + <year>2006</year> + <holder>Sébastien Helleu</holder> + </copyright> + + <legalnotice> + <para> + This manual is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + </para> + <para> + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + </para> + <para> + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA + 02111-1307 USA + </para> + </legalnotice> + + <abstract> + <para> + This manual documents WeeChat IRC client, it is part of WeeChat. + </para> + <para> + Latest version of this document can be found on this page: + <ulink url="http://weechat.flashtux.org/doc.php"> + http://weechat.flashtux.org/doc.php + </ulink> + </para> + </abstract> + + </bookinfo> + + <!-- =========================== Introduction =========================== --> + + <chapter id="chapIntroduction"> + <title>Introduction</title> + + <para> + This chapter describes WeeChat and pre-requisites for its installation. + </para> + + <section id="secDescription"> + <title>Description</title> + + <para> + WeeChat (Wee Enhanced Environment for Chat) is a free + <acronym>IRC</acronym> client, fast and light, designed for many + operating systems. + </para> + + <para> + Main features are: + <itemizedlist> + <listitem> + <para> + multi-servers connection (with SSL, IPv6, proxy) + </para> + </listitem> + <listitem> + <para> + many GUI: Curses, wxWidgets, Gtk and Qt + </para> + </listitem> + <listitem> + <para> + small, fast and light + </para> + </listitem> + <listitem> + <para> + customizable and extensible with plugins and scripts + </para> + </listitem> + <listitem> + <para> + compliant with <acronym>RFC</acronym>s + <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink>, + <ulink url="http://www.ietf.org/rfc/rfc2810.txt">2810</ulink>, + <ulink url="http://www.ietf.org/rfc/rfc2811.txt">2811</ulink>, + <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink> and + <ulink url="http://www.ietf.org/rfc/rfc2813.txt">2813</ulink> + </para> + </listitem> + <listitem> + <para> + multi-platform (GNU/Linux, *BSD, MacOS X, Windows and other) + </para> + </listitem> + <listitem> + <para> + 100% GPL, free software + </para> + </listitem> + </itemizedlist> + </para> + + <para> + WeeChat homepage is here: + <ulink url="http://weechat.flashtux.org"> + http://weechat.flashtux.org + </ulink> + </para> + + </section> + + <section id="secPreRequis"> + <title>Pre-requisites</title> + + <para> + In order to install WeeChat, you <emphasis>need</emphasis>: + <itemizedlist> + <listitem> + <para> + a running GNU/Linux system (with compiler tools for source + package) + </para> + </listitem> + <listitem> + <para> + "root" privileges (to install WeeChat) + </para> + </listitem> + <listitem> + <para> + according to GUI, one of the following libraries: + <itemizedlist> + <listitem> + <para> + Curses: ncurses library + </para> + </listitem> + <listitem> + <para> + Gtk: <emphasis>*** GUI not developed ***</emphasis> + </para> + </listitem> + <listitem> + <para> + WxWidgets: <emphasis>*** GUI not developed ***</emphasis> + </para> + </listitem> + <listitem> + <para> + Qt: <emphasis>*** GUI not developed ***</emphasis> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + + </section> + </chapter> + + <!-- =========================== Installation =========================== --> + + <chapter id="chapInstallation"> + <title>Installation</title> + + <para> + This chapter explains how to install WeeChat. + </para> + + <section id="secBinaryPackages"> + <title>Binary packages</title> + + <para> + Binary packages are available for these distributions: + <itemizedlist> + <listitem> + <para> + Debian (or any Debian compatible distribution): + <userinput>apt-get install weechat</userinput> + </para> + </listitem> + <listitem> + <para> + Mandriva/RedHat (or any RPM compatible distribution): + <userinput> + rpm -i /chemin/weechat-x.y.z-1.i386.rpm + </userinput> + </para> + </listitem> + <listitem> + <para> + Gentoo : + <userinput>emerge weechat</userinput> + </para> + </listitem> + </itemizedlist> + + For other distributions, please look at your manual for + installation instructions. + </para> + + </section> + + <section id="secSourcePackage"> + <title>Source package</title> + + <para> + All you have to do is to run in a console or a terminal: +<screen><prompt>$ </prompt><userinput>./configure</userinput> +<prompt>$ </prompt><userinput>make</userinput></screen> + </para> + <para> + Then get root privileges and install WeeChat: +<screen><prompt>$ </prompt><userinput>su</userinput> +(enter root password) +<prompt># </prompt><userinput>make install</userinput></screen> + </para> + + </section> + + <section id="secCVSSources"> + <title>CVS sources</title> + + <para> + Warning: CVS sources are for advanced users: it may not compile + or not be stable. You're warned! + </para> + + <para> + To get CVS sources, issue this command: +<screen><prompt>$ </prompt><userinput>cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/weechat co weechat</userinput></screen> + </para> + + <para> + Execute this script: + <userinput>./autogen.sh</userinput> + </para> + + <para> + Then follow instructions for source package + (see <xref linkend="secSourcePackage" />) + </para> + + </section> + + </chapter> + + <!-- ============================== Usage =============================== --> + + <chapter id="chapUsage"> + <title>Usage</title> + + <para> + This chapter explains how to run WeeChat, the default key bindings + used, internal and IRC commands, setup file, and FIFO pipe use. + </para> + + <section id="secRunWeeChat"> + <title>Run WeeChat</title> + + <para> + Command line arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Parameter</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>-a, --no-connect</literal></entry> + <entry> + Disable auto-connect to servers at startup + </entry> + </row> + <row> + <entry><literal>-c, --config</literal></entry> + <entry> + Display config help (list of options) + </entry> + </row> + <row> + <entry><literal>-f, --key-functions</literal></entry> + <entry> + Display WeeChat internal functions for keys + </entry> + </row> + <row> + <entry><literal>-h, --help</literal></entry> + <entry> + Display help + </entry> + </row> + <row> + <entry><literal>-i, --irc-commands</literal></entry> + <entry> + Display IRC commands list + </entry> + </row> + <row> + <entry><literal>-k, --keys</literal></entry> + <entry> + Display WeeChat default keys + </entry> + </row> + <row> + <entry><literal>-l, --license</literal></entry> + <entry> + Display WeeChat license + </entry> + </row> + <row> + <entry><literal>-p, --no-plugin</literal></entry> + <entry> + Disable plugins auto-load + </entry> + </row> + <row> + <entry><literal>-v, --version</literal></entry> + <entry> + Display WeeChat version + </entry> + </row> + <row> + <entry><literal>-w, --weechat-commands</literal></entry> + <entry> + Display WeeChat commands list + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + + <para> + It is also possible to give URL for one or many IRC servers, as + follow: + <screen>irc[6][s]://[pseudo[:mot_passe]@]irc.example.org[:port][/channel][,channel[...]</screen> + Example to join #weechat and #toto on + "<literal>irc.freenode.net</literal>" server, default port (6667), + with "nono" nick: + <screen><prompt>$ </prompt><userinput>weechat-curses irc://nono@irc.freenode.net/#weechat,#toto</userinput></screen> + </para> + + <para> + To start WeeChat, issue this command: + <itemizedlist> + <listitem> + <para> + for Curses GUI: <userinput>weechat-curses</userinput> + </para> + </listitem> + <listitem> + <para> + for Gtk GUI: <userinput>weechat-gtk</userinput> + </para> + </listitem> + <listitem> + <para> + for wxWidgets GUI: <userinput>weechat-wxwidgets</userinput> + </para> + </listitem> + <listitem> + <para> + for Qt GUI: <userinput>weechat-qt</userinput> + </para> + </listitem> + </itemizedlist> + </para> + + <para> + When you run WeeChat for the first time, a default configuration + file is created, with default options. + The default configuration file is: + "<literal>~/.weechat/weechat.rc</literal>" + </para> + + <para> + You can edit thie file at your convenience to configure WeeChat + (ONLY if WeeChat is not running), or you can set parameters with + "<literal>/set</literal>" command in WeeChat + (see <xref linkend="secWeeChatCommands" />) + </para> + + </section> + + <section id="secKeyboardShortcuts"> + <title>Key bindings</title> + + <para> + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Key</entry> + <entry>Action</entry> + </row> + </thead> + <tbody> + <row> + <entry>Left arrow</entry> + <entry> + Go to previous char in command line + </entry> + </row> + <row> + <entry>Right arrow</entry> + <entry> + Go to next char in command line + </entry> + </row> + <row> + <entry>Ctrl + left arrow</entry> + <entry> + Go to previous word in command line + </entry> + </row> + <row> + <entry>Ctrl + right arrow</entry> + <entry> + Go to next word in command line + </entry> + </row> + <row> + <entry>Home / Ctrl + A</entry> + <entry> + Go to the beginning of command line + </entry> + </row> + <row> + <entry>End / Ctrl + E</entry> + <entry> + Go to the end of command line + </entry> + </row> + <row> + <entry>Ctrl + K</entry> + <entry> + Delete from cursor until end of command line + </entry> + </row> + <row> + <entry>Ctrl + L</entry> + <entry> + Redraw whole window + </entry> + </row> + <row> + <entry>Ctrl + U</entry> + <entry> + Delete from cursor until beginning of command line + </entry> + </row> + <row> + <entry>Ctrl + W</entry> + <entry> + Delete previous word of command line + </entry> + </row> + <row> + <entry>Backspace</entry> + <entry> + Delete previous char in command line + </entry> + </row> + <row> + <entry>Delete</entry> + <entry> + Delete next char in command line + </entry> + </row> + <row> + <entry>Tab</entry> + <entry> + Complete command or nick + (Tab again: find next completion) + </entry> + </row> + <row> + <entry>Any char</entry> + <entry> + Insert char at cursor position in command line + </entry> + </row> + <row> + <entry>Enter</entry> + <entry> + Execute command or send message + </entry> + </row> + <row> + <entry>Up arrow / Down arrow</entry> + <entry> + Call again last commands/messages + </entry> + </row> + <row> + <entry>Ctrl + up arrow / Ctrl + down arrow</entry> + <entry> + Call again last commands/messages in global history + (common for all buffers) + </entry> + </row> + <row> + <entry>PageUp / PageDown</entry> + <entry> + Show buffer history + </entry> + </row> + <row> + <entry>F5 / Alt + left arrow</entry> + <entry> + Switch to previous buffer + </entry> + </row> + <row> + <entry>F6 / Alt + right arrow</entry> + <entry> + Switch to next buffer + </entry> + </row> + <row> + <entry>F7</entry> + <entry> + Switch to previous window + </entry> + </row> + <row> + <entry>F8</entry> + <entry> + Switch to next window + </entry> + </row> + <row> + <entry>F10</entry> + <entry> + Remove last infobar message + </entry> + </row> + <row> + <entry>F11 / F12</entry> + <entry> + Scroll nicklist + </entry> + </row> + <row> + <entry>Alt + Home / Alt + End</entry> + <entry> + Go to the beginning / the end of nicklist + </entry> + </row> + <row> + <entry>Alt + A</entry> + <entry> + Switch to next buffer with activity + (with priority: highlight, message, other) + </entry> + </row> + <row> + <entry>Alt + B</entry> + <entry> + Go to previous word in command line + </entry> + </row> + <row> + <entry>Alt + D</entry> + <entry> + Delete next word in command line + </entry> + </row> + <row> + <entry>Alt + F</entry> + <entry> + Go to next word in command line + </entry> + </row> + <row> + <entry>Alt + H</entry> + <entry> + Clear hotlist + (activity notification on other buffers) + </entry> + </row> + <row> + <entry>Alt + J then Alt + D</entry> + <entry> + Display DCC buffer + </entry> + </row> + <row> + <entry>Alt + J then Alt + L</entry> + <entry> + Switch to last buffer + </entry> + </row> + <row> + <entry>Alt + J then Alt + S</entry> + <entry> + Switch to server buffer + </entry> + </row> + <row> + <entry>Alt + J puis Alt + X</entry> + <entry> + Switch to first channel of next buffer + (or server buffer if no channel is opened) + </entry> + </row> + <row> + <entry>Alt + digit (0-9)</entry> + <entry> + Switch to buffer by number (0 = 10) + </entry> + </row> + <row> + <entry>Alt + J then number (01-99)</entry> + <entry> + Switch to buffer by number + </entry> + </row> + <row> + <entry>Alt + K</entry> + <entry> + Grab a key and insert its code in command line + </entry> + </row> + <row> + <entry>Alt + N</entry> + <entry> + Scroll to next highlight + </entry> + </row> + <row> + <entry>Alt + P</entry> + <entry> + Scroll to previous highlight + </entry> + </row> + <row> + <entry>Alt + R</entry> + <entry> + Delete entire command line + </entry> + </row> + <row> + <entry>Alt + S</entry> + <entry> + Switch servers on servers buffer + (if option "look_one_server_buffer" is enabled) + </entry> + </row> + <row> + <entry>Alt + U</entry> + <entry> + Scroll to first unread line in buffer + </entry> + </row> + <row> + <entry>Alt + W then Alt + flèche</entry> + <entry> + Switch to window with direction + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + + </section> + + <section id="secWeeChatIRCCommands"> + <title>WeeChat / IRC commands</title> + + <para> + This chapter lists all WeeChat and IRC commands. + </para> + + <section id="secWeeChatCommands"> + <title>WeeChat commands</title> + + <para> + &weechat_commands.xml; + </para> + + </section> + + <section id="secKeyFunctions"> + <title>Key functions</title> + + <para> + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Function</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + + &key_functions.xml; + + </tbody> + </tgroup> + </informaltable> + </para> + + </section> + + <section id="secIRCCommands"> + <title>IRC commands</title> + + <para> + &irc_commands.xml; + </para> + + </section> + + </section> + + <section id="secConfigurationFile"> + <title>Configuration file</title> + + <para> + List of options for config file: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Option</entry> + <entry>Type</entry> + <entry>Values</entry> + <entry>Default</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + + &config.xml; + + </tbody> + </tgroup> + </informaltable> + </para> + + <para> + Colors for Curses GUI are: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Keyword</entry> + <entry>Color</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>default</literal></entry> + <entry>default color (transparent for background)</entry> + </row> + <row> + <entry><literal>black</literal></entry> + <entry>black</entry> + </row> + <row> + <entry><literal>red</literal></entry> + <entry>dark red</entry> + </row> + <row> + <entry><literal>lightred</literal></entry> + <entry>light red</entry> + </row> + <row> + <entry><literal>green</literal></entry> + <entry>dark green</entry> + </row> + <row> + <entry><literal>lightgreen</literal></entry> + <entry>light green</entry> + </row> + <row> + <entry><literal>brown</literal></entry> + <entry>brown</entry> + </row> + <row> + <entry><literal>yellow</literal></entry> + <entry>yellow</entry> + </row> + <row> + <entry><literal>blue</literal></entry> + <entry>dark blue</entry> + </row> + <row> + <entry><literal>lightblue</literal></entry> + <entry>light blue</entry> + </row> + <row> + <entry><literal>magenta</literal></entry> + <entry>dark magenta</entry> + </row> + <row> + <entry><literal>lightmagenta</literal></entry> + <entry>light magenta</entry> + </row> + <row> + <entry><literal>cyan</literal></entry> + <entry>dark cyan</entry> + </row> + <row> + <entry><literal>lightcyan</literal></entry> + <entry>light cyan</entry> + </row> + <row> + <entry><literal>white</literal></entry> + <entry>white</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + + </section> + + <section id="secFIFOpipe"> + <title>FIFO pipe</title> + + <para> + You can remote control WeeChat, by sending commands or text to a + FIFO pipe (you have to enable option "irc_fifo_pipe", it is disabled + by default). + </para> + + <para> + The FIFO pipe is located in "<literal>~/.weechat/</literal>" and is + called "weechat_fifo_xxxxx" (where xxxxx is the process ID (PID) of + running WeeChat). So if many WeeChat are running, you have many FIFO + pipes, one for each session. + </para> + + <para> + The syntax for the FIFO pipe commands/text is: + <screen>server,channel *text or command here</screen> + where server and channel are optional, but if channel is here, server + should be too. + </para> + + <para> + Some examples: + <itemizedlist> + <listitem> + <para> + nick change on freenode to "mynick|out" : + <screen><prompt>$ </prompt><userinput>echo "freenode */nick mynick|out" >~/.weechat/weechat_fifo_12345</userinput></screen> + </para> + </listitem> + <listitem> + <para> + display text on #weechat channel: + <screen><prompt>$ </prompt><userinput>echo "freenode,#weechat *hello everybody!" >~/.weechat/weechat_fifo_12345</userinput></screen> + </para> + </listitem> + <listitem> + <para> + display text on current channel (buffer displayed by WeeChat): + <screen><prompt>$ </prompt><userinput>echo "*hello!" >~/.weechat/weechat_fifo_12345</userinput></screen> + <emphasis>Warning:</emphasis> this is dangerous and you should + not do that except if you know what you do! + </para> + </listitem> + <listitem> + <para> + send two commands to unload/reload Perl scripts (you have to + separate them with "\n"): + <screen><prompt>$ </prompt><userinput>echo -e "freenode */perl unload\nfreenode */perl autoload" >~/.weechat/weechat_fifo_12345</userinput></screen> + </para> + </listitem> + </itemizedlist> + </para> + + <para> + You can write a script to send command to all running WeeChat at same + time, for example: +<screen> +#!/bin/sh +if [ $# -eq 1 ]; then + for fifo in $(/bin/ls ~/.weechat/weechat_fifo_* 2>/dev/null); do + echo -e "$1" >$fifo + done +fi +</screen> + If the script is called "auto_weechat_command", you can run it with: + <screen><prompt>$ </prompt><userinput>./auto_weechat_command "freenode,#weechat *hello"</userinput></screen> + </para> + + </section> + + </chapter> + + <!-- ============================ Extensions ============================ --> + + <chapter id="chapPlugins"> + <title>Plugins</title> + + <para> + This chapter describes WeeChat plugins interface (API) and + the default scripts plugins (Perl, Python, Ruby), provided with + WeeChat. + </para> + + <section id="secPluginsInWeeChat"> + <title>Plugins in WeeChat</title> + + <para> + A plugin is a C program which can call WeeChat functions defined in + an interface. + </para> + + <para> + This C program does not need WeeChat sources to compile and can be + dynamically loaded into WeeChat with command + <command>/plugin</command>. + </para> + + <para> + The plugin has to be a dynamic library, for dynamic loading by + operating system. + Under GNU/Linux, the file has ".so" extension, ".dll" under + Windows. + </para> + + </section> + + <section id="secWriteAPlugin"> + <title>Write a plugin</title> + + <para> + The plugin has to include "weechat-plugin.h" file (available in + WeeChat source code). + This file defines structures and types used to communicate with + WeeChat. + </para> + + <para> + The plugin must have some variables and functions (mandatory, + without them the plugin can't load): + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Variable</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>char plugin_name[]</literal></entry> + <entry>plugin name</entry> + </row> + <row> + <entry><literal>char plugin_version[]</literal></entry> + <entry>plugin version</entry> + </row> + <row> + <entry><literal>char plugin_description[]</literal></entry> + <entry>short description of plugin</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Function</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>int weechat_plugin_init (t_weechat_plugin *plugin)</literal></entry> + <entry> + function called when plugin is loaded, must return + PLUGIN_RC_OK if successful, PLUGIN_RC_KO if error + (if error, plugin will NOT be loaded) + </entry> + </row> + <row> + <entry><literal>void weechat_plugin_end (t_weechat_plugin *plugin)</literal></entry> + <entry>function called when plugin is unloaded</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + + <section id="secAPIFunctions"> + <title>API functions</title> + + <section id="secAPI_ascii_strcasecmp"> + <title>ascii_strcasecmp</title> + + <para> + Prototype: + <command> + int ascii_strcasecmp (t_weechat_plugin *plugin, + char *string1, char *string2) + </command> + </para> + <para> + Locale and case independent string comparison. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>string1</option>: first string for comparison + </para> + </listitem> + <listitem> + <para> + <option>string2</option>: second string for comparison + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: difference between two strings: negative if + string1 < string2, zero if string1 == string2, positive if + string1 > string2 + </para> + <para> + Example: + <screen>if (plugin->ascii_strcasecmp (plugin, "abc", "def") != 0) ...</screen> + </para> + </section> + + <section id="secAPI_ascii_strncasecmp"> + <title>ascii_strncasecmp</title> + + <para> + Prototype: + <command> + int ascii_strncasecmp (t_weechat_plugin *plugin, + char *string1, char *string2, int max) + </command> + </para> + <para> + Locale and case independent string comparison, for "max" chars. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin struct + </para> + </listitem> + <listitem> + <para> + <option>string1</option>: first string for comparison + </para> + </listitem> + <listitem> + <para> + <option>string2</option>: second string for comparison + </para> + </listitem> + <listitem> + <para> + <option>max</option>: max number of chars for comparison + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: difference between two strings: negative if + string1 < string2, zero if string1 == string2, positive if + string1 > string2 + </para> + <para> + Example: + <screen>if (plugin->ascii_strncasecmp (plugin, "abc", "def", 2) != 0) ...</screen> + </para> + </section> + + <section id="secAPI_explode_string"> + <title>explode_string</title> + + <para> + Prototype: + <command> + char **explode_string (t_weechat_plugin *plugin, char *string, + char *separators, int num_items_max, int *num_items) + </command> + </para> + <para> + Explode a string according to one or more delimiter(s). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin struct + </para> + </listitem> + <listitem> + <para> + <option>string</option>: string to explode + </para> + </listitem> + <listitem> + <para> + <option>separators</option>: delimiters used for explosion + </para> + </listitem> + <listitem> + <para> + <option>num_items_max</option>: maximum number of items + created (0 = no limit) + </para> + </listitem> + <listitem> + <para> + <option>num_items</option>: pointer to int which will + contain number of items created + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: array of strings, NULL if problem. + </para> + <para> + Note: result has to be free by a call to "free_exloded_string" + after use. + </para> + <para> + Example: +<screen> +char **argv; +int argc; +argv = plugin->explode_string (plugin, string, " ", 0, &argc); +... +if (argv != NULL) + plugin->free_exploded_string (plugin, argv); +</screen> + </para> + </section> + + <section id="secAPI_free_exploded_string"> + <title>free_exploded_string</title> + + <para> + Prototype: + <command> + char **free_exploded_string (t_weechat_plugin *plugin, + char **string) + </command> + </para> + <para> + Free memory used by a string explosion. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>string</option>: string exploded by + "explode_string" function + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: none. + </para> + <para> + Example: +<screen> +char *argv; +int argc; +argv = plugin->explode_string (plugin, string, " ", 0, &argc); +... +if (argv != NULL) + plugin->free_exploded_string (plugin, argv); +</screen> + </para> + </section> + + <section id="secAPI_exec_on_files"> + <title>exec_on_files</title> + + <para> + Prototype: + <command> + void exec_on_files (t_weechat_plugin *plugin, char *repertoire, + int (*callback)(t_weechat_plugin *, char *)) + </command> + </para> + <para> + Execute a function on all files of a directory. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer tu plugin structure + </para> + </listitem> + <listitem> + <para> + <option>directory</option>: directory for searching files + </para> + </listitem> + <listitem> + <para> + <option>callback</option>: function called for each file + found + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: none. + </para> + <para> + Example: +<screen> +int callback (t_weechat_plugin *plugin, char *file) +{ + plugin->printf_server (plugin, "file: %s", file); + return 1; +} +... +plugin->exec_on_files (plugin, "/tmp", &callback); +</screen> + </para> + </section> + + <section id="secAPI_printf"> + <title>printf</title> + + <para> + Prototype: + <command> + void printf (t_weechat_plugin *plugin, + char *server, char *channel, char *message, ...) + </command> + </para> + <para> + Display a message on a WeeChat buffer, identified by server and + channel (both may be NULL for current buffer). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>server</option>: internal name of server to find + buffer for message display (may be NULL) + </para> + </listitem> + <listitem> + <para> + <option>channel</option>: name of channel to find buffer + for message display (may be NULL) + </para> + </listitem> + <listitem> + <para> + <option>message</option>: message + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: none. + </para> + <para> + Examples: +<screen> +plugin->printf (plugin, NULL, NULL, "hello"); +plugin->printf (plugin, NULL, "#weechat", "hello"); +plugin->printf (plugin, "freenode", "#weechat", "hello"); +</screen> + </para> + </section> + + <section id="secAPI_printf_server"> + <title>printf_server</title> + + <para> + Prototype: + <command> + void printf_server (t_weechat_plugin *plugin, + char *message, ...) + </command> + </para> + <para> + Display a message on current server buffer. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>message</option>: message + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: none. + </para> + <para> + Example: <screen>plugin->printf_server (plugin, "hello");</screen> + </para> + </section> + + <section id="secAPI_printf_infobar"> + <title>printf_infobar</title> + + <para> + Prototype: + <command> + void printf_infobar (t_weechat_plugin *plugin, + int time, char *message, ...) + </command> + </para> + <para> + Display a message in infobar for a specified time. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>time</option>: time (in seconds) for displaying + message (0 = never erased) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: none. + </para> + <para> + Example: +<screen> +plugin->printf_infobar (plugin, 5, "hello"); +</screen> + </para> + </section> + + <section id="secAPI_msg_handler_add"> + <title>msg_handler_add</title> + + <para> + Prototype: + <command> + t_plugin_handler *msg_handler_add (t_weechat_plugin + *plugin, char *message, t_plugin_handler_func *function, + char *handler_args, void *handler_pointer) + </command> + </para> + <para> + Add an IRC message handler, called when an IRC message is + received. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>message</option>: name of IRC message. + To know list of IRC messages, please consult + <acronym>RFC</acronym>s + <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink> and + <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink> + </para> + </listitem> + <listitem> + <para> + <option>function</option>: function called when message + is received + </para> + </listitem> + <listitem> + <para> + <option>handler_args</option>: arguments given to function + when called + </para> + </listitem> + <listitem> + <para> + <option>handler_pointer</option>: pointer given to function + when called + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to new message handler. + </para> + <para> + Note: function called when message is received has to return + one of following values: + <itemizedlist> + <listitem> + <para> + <literal>PLUGIN_RC_KO</literal>: function failed + </para> + </listitem> + <listitem> + <para> + <literal>PLUGIN_RC_OK</literal>: function successfully + completed + </para> + </listitem> + <listitem> + <para> + <literal>PLUGIN_RC_OK_IGNORE_WEECHAT</literal>: message + will not be sent to WeeChat + </para> + </listitem> + <listitem> + <para> + <literal>PLUGIN_RC_OK_IGNORE_PLUGINS</literal>: message + will not be sent to other plugins + </para> + </listitem> + <listitem> + <para> + <literal>PLUGIN_RC_OK_IGNORE_ALL</literal>: message + will not be sent to WeeChat neither other plugins + </para> + </listitem> + </itemizedlist> + </para> + <para> + Example: +<screen> +int msg_kick (t_weechat_plugin *plugin, char *server, char *command, + char *arguments, char *handler_args, void *handler_pointer) +{ + plugin->printf (plugin, serveur, NULL, "KICK received"); + return PLUGIN_RC_OK; +} +... +plugin->msg_handler_add (plugin, "KICK", &msg_kick, NULL, NULL); +</screen> + </para> + </section> + + <section id="secAPI_cmd_handler_add"> + <title>cmd_handler_add</title> + + <para> + Prototype: + <command> + t_plugin_handler *cmd_handler_add (t_weechat_plugin + *plugin, char *command, char *description, char *arguments, + char *arguments_description, char *completion_template, + t_plugin_handler_func *fonction, char *handler_args, + void *handler_pointer) + </command> + </para> + <para> + Add a WeeChat command handler, called when user uses command + (for example /command). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>command</option>: the new command name, which + may be an existing command (be careful, replaced command + will not be available until plugin is unloaded) + </para> + </listitem> + <listitem> + <para> + <option>description</option>: short command description + (displayed by /help command) + </para> + </listitem> + <listitem> + <para> + <option>arguments</option>: short description of command + arguments (displayed by /help command) + </para> + </listitem> + <listitem> + <para> + <option>arguments_description</option>: long description + of command arguments (displayed by /help command) + </para> + </listitem> + <listitem> + <para> + <option>completion_template</option>: template for + completion, like "<literal>abc|%w def|%i</literal>" + which means "abc" or a WeeChat command for first argument, + "def" or IRC command for second. + An empty string lets WeeChat complete any argument with + a nick from current channel, NULL disable completion for + all command arguments. + </para> + <para> + Following codes can be used: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Code</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>%-</literal></entry> + <entry>no completion for argument</entry> + </row> + <row> + <entry><literal>%a</literal></entry> + <entry>alias</entry> + </row> + <row> + <entry><literal>%A</literal></entry> + <entry> + alias and commandes (WeeChat, IRC and plugins) + </entry> + </row> + <row> + <entry><literal>%c</literal></entry> + <entry>current channel</entry> + </row> + <row> + <entry><literal>%C</literal></entry> + <entry>channels of current server</entry> + </row> + <row> + <entry><literal>%f</literal></entry> + <entry>filename</entry> + </row> + <row> + <entry><literal>%h</literal></entry> + <entry>plugins commands</entry> + </row> + <row> + <entry><literal>%i</literal></entry> + <entry>IRC commands (sent)</entry> + </row> + <row> + <entry><literal>%I</literal></entry> + <entry>IRC commands (received)</entry> + </row> + <row> + <entry><literal>%k</literal></entry> + <entry>key functions</entry> + </row> + <row> + <entry><literal>%n</literal></entry> + <entry>nicks of current channel</entry> + </row> + <row> + <entry><literal>%o</literal></entry> + <entry>setup options</entry> + </row> + <row> + <entry><literal>%p</literal></entry> + <entry>default "part" message</entry> + </row> + <row> + <entry><literal>%q</literal></entry> + <entry>default "quit" message</entry> + </row> + <row> + <entry><literal>%s</literal></entry> + <entry>current server name</entry> + </row> + <row> + <entry><literal>%S</literal></entry> + <entry>all servers names</entry> + </row> + <row> + <entry><literal>%t</literal></entry> + <entry>topic of current channel</entry> + </row> + <row> + <entry><literal>%v</literal></entry> + <entry>setup option value</entry> + </row> + <row> + <entry><literal>%w</literal></entry> + <entry>WeeChat commands</entry> + </row> + <row> + <entry><literal>%y</literal></entry> + <entry>default "away" message</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>function</option>: function called when command + is executed + </para> + </listitem> + <listitem> + <para> + <option>handler_args</option>: arguments given to function + when called + </para> + </listitem> + <listitem> + <para> + <option>handler_pointer</option>: pointer given to function + when called + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to new command handler. + </para> + <para> + Note: function called when command is executed has to return + one of following values: + <itemizedlist> + <listitem> + <para> + <literal>PLUGIN_RC_KO</literal>: function failed + </para> + </listitem> + <listitem> + <para> + <literal>PLUGIN_RC_OK</literal>: function successfulle + completed + </para> + </listitem> + </itemizedlist> + </para> + <para> + Example: +<screen> +int cmd_test (t_weechat_plugin *plugin, char *server, + char *command, char *arguments, char *handler_args, + void *handler_pointer) +{ + plugin->printf (plugin, serveur, NULL, + "test command, nick: %s", + (arguments) ? arguments : "none"); + return PLUGIN_RC_OK; +} +... +plugin->cmd_handler_add (plugin, "test", "Test command", + "[nick]", "nick: nick of channel", + "%n", &cmd_test, NULL, NULL); +</screen> + </para> + </section> + + <section id="secAPI_handler_remove"> + <title>handler_remove</title> + + <para> + Prototype: + <command> + void handler_remove (t_weechat_plugin *plugin, + t_plugin_handler *handler) + </command> + </para> + <para> + Remove a handler. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>handler</option>: handler to remove + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: none. + </para> + <para> + Example: + <screen>plugin->handler_remove (plugin, my_handler);</screen> + </para> + </section> + + <section id="secAPI_handler_remove_all"> + <title>handler_remove_all</title> + + <para> + Prototype: + <command> + void handler_remove_all (t_weechat_plugin *plugin) + </command> + </para> + <para> + Remove all handlers for a plugin. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: none. + </para> + <para> + Example: + <screen>plugin->handler_remove_all (plugin);</screen> + </para> + </section> + + <section id="secAPI_exec_command"> + <title>exec_command</title> + + <para> + Prototype: + <command> + void exec_command (t_weechat_plugin + *plugin, char *server, char *channel, char *command) + </command> + </para> + <para> + Execute a WeeChat command (or send a message to a channel). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>server</option>: internal name of server for + executing command (may be NULL) + </para> + </listitem> + <listitem> + <para> + <option>channel</option>: name of channel for executing + command (may be NULL) + </para> + </listitem> + <listitem> + <para> + <option>command</option>: command + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: none. + </para> + <para> + Examples: +<screen> +plugin->exec_command (plugin, NULL, NULL, "/help nick"); +plugin->exec_command (plugin, "freenode", "#weechat", "hello"); +</screen> + </para> + </section> + + <section id="secAPI_get_info"> + <title>get_info</title> + + <para> + Prototype: + <command> + char *get_info (t_weechat_plugin *plugin, + char *info, char *server) + </command> + </para> + <para> + Return an info about WeeChat or a channel. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>info</option> : name of info to read: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Info</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>version</literal></entry> + <entry>WeeChat's version</entry> + </row> + <row> + <entry><literal>nick</literal></entry> + <entry>nick</entry> + </row> + <row> + <entry><literal>channel</literal></entry> + <entry> + name of channel (NULL for a server or private) + </entry> + </row> + <row> + <entry><literal>server</literal></entry> + <entry>name of server</entry> + </row> + <row> + <entry><literal>away</literal></entry> + <entry>"away" flag</entry> + </row> + <row> + <entry><literal>weechat_dir</literal></entry> + <entry> + WeeChat home dir + (by default: ~/.weechat/) + </entry> + </row> + <row> + <entry><literal>weechat_libdir</literal></entry> + <entry>WeeChat system lib directory</entry> + </row> + <row> + <entry><literal>weechat_sharedir</literal></entry> + <entry>WeeChat system share directory</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>server</option>: internal name of server for + reading info (if needed) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: information asked, NULL if not found. + </para> + <para> + Note: result has to be free by a call to "free" function after + use. + </para> + <para> + Examples: +<screen> +char *version = plugin->get_info (plugin, "version", NULL); +char *nick = plugin->get_info (plugin, "nick", "freenode"); +</screen> + </para> + </section> + + <section id="secAPI_get_dcc_info"> + <title>get_dcc_info</title> + + <para> + Prototype: + <command> + t_plugin_info_dcc *get_dcc_info (t_weechat_plugin *plugin) + </command> + </para> + <para> + Return list of DCC currently active or finished. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: linked list of DCC. + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Field</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>server</literal></entry> + <entry>IRC server</entry> + </row> + <row> + <entry><literal>channel</literal></entry> + <entry>IRC channel</entry> + </row> + <row> + <entry><literal>type</literal></entry> + <entry> + DCC type: + 0 = chat received, + 1 = chat sent, + 2 = file received, + 3 = file sent + </entry> + </row> + <row> + <entry><literal>status</literal></entry> + <entry> + DCC status: + 0 = waiting, + 1 = connecting, + 2 = active, + 3 = finished, + 4 = failed, + 5 = interrupted by user + </entry> + </row> + <row> + <entry><literal>start_time</literal></entry> + <entry>date/time of DCC creation</entry> + </row> + <row> + <entry><literal>start_transfer</literal></entry> + <entry>date/time of DCC transfert start</entry> + </row> + <row> + <entry><literal>addr</literal></entry> + <entry>IP address of remote user</entry> + </row> + <row> + <entry><literal>port</literal></entry> + <entry>port used for DCC</entry> + </row> + <row> + <entry><literal>nick</literal></entry> + <entry>remote nick</entry> + </row> + <row> + <entry><literal>filename</literal></entry> + <entry>file name</entry> + </row> + <row> + <entry><literal>local_filename</literal></entry> + <entry>local file name</entry> + </row> + <row> + <entry><literal>size</literal></entry> + <entry>file size</entry> + </row> + <row> + <entry><literal>pos</literal></entry> + <entry>position in file</entry> + </row> + <row> + <entry><literal>start_resume</literal></entry> + <entry>start position after interruption</entry> + </row> + <row> + <entry><literal>bytes_per_sec</literal></entry> + <entry> + number of bytes per second since transfert start + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + <para> + Note: result has to be free by a call to "free_dcc_info" function + after use. + </para> + <para> + Examples: +<screen> +t_plugin_dcc_info *dcc_info = plugin->get_dcc_info (plugin); +for (ptr_dcc = dcc_info; ptr_dcc; ptr_dcc = ptr_dcc->next_dcc) +{ + plugin->printf_server (plugin, "DCC type=%d, with: %s", + ptr_dcc->type, ptr_dcc->nick); +} +if (dcc_info) + plugin->free_dcc_info (plugin, dcc_info); +</screen> + </para> + </section> + + <section id="secAPI_free_dcc_info"> + <title>free_dcc_info</title> + + <para> + Prototype : + <command> + void free_dcc_info (t_weechat_plugin *plugin, + t_plugin_dcc_info *dcc_info) + </command> + </para> + <para> + Free memory used by a DCC list. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>dcc_info</option>: pointer to DCC list returned by + "get_dcc_info" function + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: none. + </para> + <para> + Example: + <screen>plugin->free_dcc_info (plugin, dcc_info);</screen> + </para> + </section> + + <section id="secAPI_get_config"> + <title>get_config</title> + + <para> + Prototype : + <command> + char *get_config (t_weechat_plugin *plugin, char *option) + </command> + </para> + <para> + Return value of a WeeChat config option. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>option</option>: name of option to read + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: option value, NULL if not found. + </para> + <para> + Note: result has to be free by a call to "free" function after + use. + </para> + <para> + Examples: +<screen> +char *value1 = plugin->get_config (plugin, "look_set_title"); +char *value2 = plugin->get_config (plugin, "freenode.server_autojoin"); +</screen> + </para> + </section> + + <section id="secAPI_set_config"> + <title>set_config</title> + + <para> + Prototype: + <command> + int set_config (t_weechat_plugin *plugin, + char *option, char *value) + </command> + </para> + <para> + Update value of a WeeChat config option. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>option</option>: name of option to update + </para> + </listitem> + <listitem> + <para> + <option>value</option>: new value for option + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: 1 if option was successfully updated, 0 if an + error occured. + </para> + <para> + Example: +<screen> +plugin->set_config (plugin, "look_nicklist", "off"); +</screen> + </para> + </section> + + <section id="secAPI_get_plugin_config"> + <title>get_plugin_config</title> + + <para> + Prototype: + <command> + char *get_plugin_config (t_weechat_plugin *plugin, char *option) + </command> + </para> + <para> + Return value of a plugin option. + Option is read from file "<literal>~/.weechat/plugins.rc</literal>" + and is like: "<literal>plugin.option=value</literal>" + (note: plugin name is automatically added). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>option</option>: name of option to read + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: option value, NULL if not found. + </para> + <para> + Note: result has to be free by a call to "free" function after + use. + </para> + <para> + Example: +<screen> +char *value = plugin->get_plugin_config (plugin, "my_var"); +</screen> + </para> + </section> + + <section id="secAPI_set_plugin_config"> + <title>set_plugin_config</title> + + <para> + Prototype: + <command> + int set_plugin_config (t_weechat_plugin *plugin, + char *option, char *value) + </command> + </para> + <para> + Update value of a plugin option. + Option is written in file "<literal>~/.weechat/plugins.rc</literal>" + and is like: "<literal>plugin.option=value</literal>" + (note: plugin name is automatically added). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>plugin</option>: pointer to plugin structure + </para> + </listitem> + <listitem> + <para> + <option>option</option>: name of option to update + </para> + </listitem> + <listitem> + <para> + <option>value</option>: new value for option + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: 1 if option was successfully updated, 0 if an + error occurred. + </para> + <para> + Example : +<screen> +plugin->set_plugin_config (plugin, "my_var", "value"); +</screen> + </para> + </section> + + </section> + + <section id="secCompilePlugin"> + <title>Compile plugin</title> + + <para> + Compile does not need WeeChat sources, only file + "<literal>weechat-plugin.h</literal>". + </para> + + <para> + To compile a plugin which has one file "toto.c" (sous GNU/Linux): +<screen> +<prompt>$ </prompt><userinput>gcc -fPIC -Wall -c toto.c</userinput> +<prompt>$ </prompt><userinput>gcc -shared -fPIC -o libtoto.so toto.o</userinput> +</screen> + </para> + + </section> + + <section id="secLoadPlugin"> + <title>Load plugin into WeeChat</title> + + <para> + Copy "libtoto.so" file into system plugins dir (for example + "<literal>/usr/local/lib/weechat/plugins</literal>") or into + user's plugins dir (for example + "<literal>/home/xxxxx/.weechat/plugins</literal>"). + </para> + + <para> + Under WeeChat: + <screen><userinput>/plugin load toto</userinput></screen> + </para> + + </section> + + <section id="secPluginExample"> + <title>Plugin example</title> + + <para> + Full example of plugin, which adds a /double command, which displays + two times arguments on current channel (ok that's not very useful, but + that's just an example!): +<screen> +#include <stdlib.h> + +#include "weechat-plugin.h" + +char plugin_name[] = "Double"; +char plugin_version[] = "0.1"; +char plugin_description[] = "Test plugin for WeeChat"; + +/* gestionnaire de commande "/double" */ + +int double_cmd (t_weechat_plugin *plugin, char *server, + char *command, char *arguments, + char *handler_args, void *handler_pointer) +{ + if (arguments && arguments[0] && (arguments[0] != '/')) + { + plugin->exec_command (plugin, NULL, NULL, arguments); + plugin->exec_command (plugin, NULL, NULL, arguments); + } + return PLUGIN_RC_OK; +} + +int weechat_plugin_init (t_weechat_plugin *plugin) +{ + plugin->cmd_handler_add (plugin, "double", + "Display two times a message", + "msg", + "msg: message to display two times", + NULL, + &double_cmd, + NULL, NULL); + return PLUGIN_RC_OK; +} + +void weechat_plugin_end (t_weechat_plugin *plugin) +{ + /* nothing done here */ +} +</screen> + </para> + + </section> + + </section> + + <section id="secScriptsPlugins"> + <title>Scripts plugins</title> + + <para> + Three plugins are provided with WeeChat to use script languages: + Perl, Python and Ruby. + </para> + + <section id="secLoadUnloadScripts"> + <title>Load / unload scripts</title> + + <para> + Scripts are loaded and unloaded with <command>/perl</command>, + <command>/python</command> and <command>/ruby</command> commands + (type <command>/help</command> in WeeChat for help about commands). + </para> + + <para> + Examples: + <itemizedlist> + <listitem> + <para> + Load a Perl script: + <command><userinput>/perl load /tmp/test.pl</userinput></command> + </para> + </listitem> + <listitem> + <para> + List all loaded Perl scripts: + <command><userinput>/perl</userinput></command> + </para> + </listitem> + <listitem> + <para> + Load a Python script: + <command><userinput>/python load /tmp/test.py</userinput></command> + </para> + </listitem> + <listitem> + <para> + List all loaded Python scripts: + <command><userinput>/python</userinput></command> + </para> + </listitem> + <listitem> + <para> + Load a Ruby script: + <command><userinput>/ruby load /tmp/test.rb</userinput></command> + </para> + </listitem> + <listitem> + <para> + List all loaded Ruby scripts: + <command><userinput>/ruby</userinput></command> + </para> + </listitem> + </itemizedlist> + </para> + + </section> + + <section id="secWeeChatScriptsAPI"> + <title>WeeChat / scripts API</title> + + <section> + <title>register</title> + + <para> + Perl prototype: + <command> + weechat::register ( name, version, end_function, description ); + </command> + </para> + <para> + Python prototype: + <command> + weechat.register ( name, version, end_function, description ) + </command> + </para> + <para> + Ruby prototype: + <command> + Weechat.register ( name, version, end_function, description ) + </command> + </para> + <para> + This is first function to call in script. + All WeeChat scripts have to call this function. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>name</option>: unique name to identify script + (each script must have unique name) + </para> + </listitem> + <listitem> + <para> + <option>version</option>: script version + </para> + </listitem> + <listitem> + <para> + <option>end_function</option>: function called when script is + unloaded (optional parameter, empty string means nothing is + called at the end) + </para> + </listitem> + <listitem> + <para> + <option>description</option>: short description of script + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: 1 if script was registered, 0 if an error occured. + </para> + <para> + Examples: +<screen> +# perl +weechat::register ("test", "1.0", "end_test", "Test script!"); + +# python +weechat.register ("test", "1.0", "end_test", "Test script!") + +# ruby +Weechat.register ("test", "1.0", "end_test", "Test script!") +</screen> + </para> + </section> + + <section> + <title>print</title> + + <para> + Perl prototype: + <command> + weechat::print ( message, [channel, [server]] ) + </command> + </para> + <para> + Python prototype: + <command> + weechat.prnt ( message, [channel, [server]] ) + </command> + </para> + <para> + Ruby prototype: + <command> + Weechat.print ( message, [channel, [server]] ) + </command> + </para> + <para> + Display a message on a WeeChat buffer, identified by server + and channel. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>message</option>: message + </para> + </listitem> + <listitem> + <para> + <option>channel</option>: name of channel to find buffer + for message display + </para> + </listitem> + <listitem> + <para> + <option>server</option>: internal name of server to find + buffer for message display + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: 1 if success, 0 if an error occured. + </para> + <para> + Examples: +<screen> +# perl +weechat::print ("message"); +weechat::print ("message", "#weechat"); +weechat::print ("message", "#weechat", "freenode"); + +# python +weechat.prnt ("message") +weechat.prnt ("message", "#weechat") +weechat.prnt ("message", "#weechat", "freenode") + +# ruby +Weechat.print ("message") +Weechat.print ("message", "#weechat") +Weechat.print ("message", "#weechat", "freenode") +</screen> + </para> + </section> + + <section> + <title>print_infobar</title> + + <para> + Perl prototype: + <command> + weechat::print_infobar ( time, message ); + </command> + </para> + <para> + Python prototype: + <command> + weechat.print_infobar ( time, message ) + </command> + </para> + <para> + Ruby prototype: + <command> + Weechat.print_infobar ( time, message ) + </command> + </para> + <para> + Display a message in infobar for a specified time. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>time</option>: time (in seconds) for displaying + message (0 = never erased) + </para> + </listitem> + <listitem> + <para> + <option>message</option>: message + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: 1 if success, 0 if an error occured. + </para> + <para> + Examples: +<screen> +# perl +weechat::print_infobar (5, "message"); + +# python +weechat.print_infobar (5, "message") + +# ruby +Weechat.print_infobar (5, "message") +</screen> + </para> + </section> + + <section> + <title>add_message_handler</title> + + <para> + Perl prototype: + <command> + weechat::add_message_handler ( message, function ); + </command> + </para> + <para> + Python prototype: + <command> + weechat.add_message_handler ( message, function ) + </command> + </para> + <para> + Ruby prototype: + <command> + Weechat.add_message_handler ( message, function ) + </command> + </para> + <para> + Add an IRC message handler, called when an IRC message is + received. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>message</option>: name of IRC message. To know list + of IRC messages, please consult <acronym>RFC</acronym>s + <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink> and + <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink> + </para> + </listitem> + <listitem> + <para> + <option>function</option>: function called when message is + received + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: 1 if success, 0 if an error occured. + </para> + <para> + Examples: +<screen> +# perl +weechat::add_message_handler ("privmsg", my_function); +sub my_function +{ + weechat::print ("server=$_[0]\n"); + ($null, $channel, $message) = split ":",$_[1],3; + ($mask, $null, $channel) = split " ", $channel; + weechat::print ("mask=$mask, channel=$channel, msg=$message\n"); + return weechat::PLUGIN_RC_OK; +} + +# python +weechat.add_message_handler ("privmsg", my_function) +def ma_fonction(server, args): + weechat.prnt("server="+serveur) + null, channel, message = string.split(args, ":", 2) + masque, null, channel = string.split(string.strip(channel), " ", 2) + weechat.prnt("mask="+mask+", canal="+channel+", message="+message) + return weechat.PLUGIN_RC_OK +</screen> + </para> + <para> + Note: function called when message is received has to return one + of following values (prefixed by weechat::" for Perl, "weechat." + for Python or "Weechat." for Ruby): + <itemizedlist> + <listitem> + <para> + <literal>PLUGIN_RC_KO</literal>: function failed + </para> + </listitem> + <listitem> + <para> + <literal>PLUGIN_RC_OK</literal>: function successfully + completed + </para> + </listitem> + <listitem> + <para> + <literal>PLUGIN_RC_OK_IGNORE_WEECHAT</literal>: message + will not be sent to WeeChat + </para> + </listitem> + <listitem> + <para> + <literal>PLUGIN_RC_OK_IGNORE_PLUGINS</literal>: message + will not be sent to other plugins + </para> + </listitem> + <listitem> + <para> + <literal>PLUGIN_RC_OK_IGNORE_ALL</literal>: message + will not be sent to WeeChat neither other plugins + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section> + <title>add_command_handler</title> + + <para> + Perl prototype: + <command> + weechat::add_command_handler ( command, function, + [description, arguments, arguments_description, + completion_template] ); + </command> + </para> + <para> + Python prototype: + <command> + weechat.add_command_handler ( command, function, + [description, arguments, arguments_description, + completion_template] ) + </command> + </para> + <para> + Ruby prototype: + <command> + Weechat.add_command_handler ( command, function, + [description, arguments, arguments_description, + completion_template] ) + </command> + </para> + <para> + Add a WeeChat command handler, called when user uses command + (for example /command). + </para> + <para> + Paramètres : + <itemizedlist> + <listitem> + <para> + <option>command</option>: the new command name, which + may be an existing command (be careful, replaced command + will not be available until script is unloaded) + </para> + </listitem> + <listitem> + <para> + <option>function</option>: fonction appelée lorsque la + commande est exécutée + </para> + </listitem> + <listitem> + <para> + <option>arguments</option>: short description of command + arguments (displayed by /help command) + </para> + </listitem> + <listitem> + <para> + <option>arguments_description</option>: long description + of command arguments (displayed by /help command) + </para> + </listitem> + <listitem> + <para> + <option>completion_template</option>: template for + completion, like "<literal>abc|%w def|%i</literal>" which + means "abc" or a WeeChat command for first argument, + "def" or IRC command for second. + (see <xref linkend="secAPI_cmd_handler_add" />) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: 1 if success, 0 if an error occured. + </para> + <para> + Examples: +<screen> +# perl +weechat::add_command_handler ("command", my_command); +sub my_command +{ + weechat::print("Server: $_[0], arguments: $_[1]\n"); + return weechat::PLUGIN_RC_OK; +} + +# python +weechat.add_command_handler ("command", my_command) +def ma_commande(server, args): + weechat.prnt("server:"+serveur+" arguments:"+args) + return weechat.PLUGIN_RC_OK +</screen> + </para> + <para> + Notes: function called when command is executed has to return one + of following values (prefixed by "weechat::" for Perl, "weechat." + for Python or "Weechat." for Ruby): + <itemizedlist> + <listitem> + <para> + <literal>PLUGIN_RC_KO</literal> : function failed + </para> + </listitem> + <listitem> + <para> + <literal>PLUGIN_RC_OK</literal> : function successfully + completed + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section> + <title>remove_handler</title> + + <para> + Perl prototype: + <command> + weechat::remove_handler ( name, function ); + </command> + </para> + <para> + Python prototype: + <command> + weechat.remove_handler ( name, function ) + </command> + </para> + <para> + Ruby prototype: + <command> + Weechat.remove_handler ( name, function ) + </command> + </para> + <para> + Remove a handler. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>name</option>: name of IRC message or command + </para> + </listitem> + <listitem> + <para> + <option>function</option>: function + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: 1 if success, 0 if an error occured. + </para> + <para> + Examples: +<screen> +# perl +weechat::remove_handler ("command", my_command); + +# python +weechat.remove_handler ("command", my_command) + +# ruby +Weechat.remove_handler ("command", my_command) +</screen> + </para> + </section> + + <section> + <title>command</title> + + <para> + Perl prototype: + <command> + weechat::command ( command, [channel, [server]] ); + </command> + </para> + <para> + Python prototype: + <command> + weechat.command ( command, [channel, [server]] ) + </command> + </para> + <para> + Ruby prototype: + <command> + Weechat.command ( command, [channel, [server]] ) + </command> + </para> + <para> + Execute a WeeChat command (or send a message to a channel). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>command</option>: command + </para> + </listitem> + <listitem> + <para> + <option>channel</option>: name of channel for executing + command + </para> + </listitem> + <listitem> + <para> + <option>server</option>: internal name of server for + executing command + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: 1 if success, 0 if an error occured. + </para> + <para> + Examples: +<screen> +# perl +weechat::command ("hello everybody!"); +weechat::command ("/kick toto please leave this channel", "#weechat"); +weechat::command ("/nick newnick", "", "freenode"); + +# python +weechat.command ("hello everybody!") +weechat.command ("/kick toto please leave this channel", "#weechat") +weechat.command ("/nick newnick", "", "freenode") + +# ruby +Weechat.command ("hello everybody!") +Weechat.command ("/kick toto please leave this channel", "#weechat") +Weechat.command ("/nick newnick", "", "freenode") +</screen> + </para> + </section> + + <section> + <title>get_info</title> + + <para> + Perl prototype: + <command> + weechat::get_info ( name, [server] ); + </command> + </para> + <para> + Python prototype: + <command> + weechat.get_info ( name, [server] ) + </command> + </para> + <para> + Ruby prototype: + <command> + Weechat.get_info ( name, [server] ) + </command> + </para> + <para> + Return an info about WeeChat or a channel. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>name</option>: name of info to read + (see <xref linkend="secAPI_get_info" />) + </para> + </listitem> + <listitem> + <para> + <option>server</option>: internal name of server for + reading info (if needed) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: information asked, empty string if an error + occured + </para> + <para> + Examples: +<screen> +# perl +$version = get_info("version"); +$nick = get_info("nick", "freenode"); + +# python +version = weechat.get_info ("version") +nick = weechat.get_info ("nick", "freenode") +</screen> + </para> + </section> + + <section> + <title>get_dcc_info</title> + + <para> + Perl prototype: + <command> + weechat::get_dcc_info ( ); + </command> + </para> + <para> + Python prototype: + <command> + weechat.get_dcc_info ( ) + </command> + </para> + <para> + Ruby prototype : + <command> + Weechat.get_dcc_info ( ) + </command> + </para> + <para> + Return list of DCC currently active or finished. + </para> + <para> + Return value: list of DCC + (see <xref linkend="secAPI_get_dcc_info" />). + </para> + </section> + + <section> + <title>get_config</title> + + <para> + Perl prototype: + <command> + weechat::get_config ( option ); + </command> + </para> + <para> + Python prototype: + <command> + weechat.get_config ( option ) + </command> + </para> + <para> + Ruby prototype: + <command> + Weechat.get_config ( option ) + </command> + </para> + <para> + Return value of a WeeChat config option. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>option</option>: name of option to read + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: option value, empty string if not found. + </para> + <para> + Examples: +<screen> +# perl +$value1 = weechat::get_config ("look_nicklist"); +$value2 = weechat::get_config ("freenode.server_autojoin"); + +# python +value1 = weechat.get_config ("look_nicklist") +value2 = weechat.get_config ("freenode.server_autojoin") +</screen> + </para> + </section> + + <section> + <title>set_config</title> + + <para> + Perl prototype: + <command> + weechat::set_config ( option, value ); + </command> + </para> + <para> + Python prototype: + <command> + weechat.set_config ( option, value ) + </command> + </para> + <para> + Ruby prototype: + <command> + Weechat.set_config ( option, value ) + </command> + </para> + <para> + Update value of a WeeChat config option. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>option</option>: name of option to update + </para> + </listitem> + <listitem> + <para> + <option>value</option>: new value for option + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: 1 if option was successfully updated, 0 if an error + occured. + </para> + <para> + Examples: +<screen> +# perl +weechat::set_config ("look_nicklist", "off"); +weechat::set_config ("freenode.server_autojoin, "#weechat"); + +# python +weechat.set_config ("look_nicklist", "off") +weechat.set_config ("freenode.server_autojoin, "#weechat") + +# ruby +Weechat.set_config ("look_nicklist", "off") +Weechat.set_config ("freenode.server_autojoin, "#weechat") +</screen> + </para> + </section> + + <section> + <title>get_plugin_config</title> + + <para> + Perl prototype: + <command> + weechat::get_plugin_config ( option ); + </command> + </para> + <para> + Python prototype: + <command> + weechat.get_plugin_config ( option ) + </command> + </para> + <para> + Ruby prototype: + <command> + Weechat.get_plugin_config ( option ) + </command> + </para> + <para> + Return value of a plugin option. Option is read from file + "<literal>~/.weechat/plugins.rc</literal>" and is like: + "<literal>plugin.option=value</literal>" (note: plugin name + is automatically added). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>option</option>: name of option to read + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: value of option, empty string if not found. + </para> + <para> + Examples : +<screen> +# perl +$value = weechat::get_plugin_config ("my_var"); + +# python +value = weechat.get_plugin_config ("my_var") +</screen> + </para> + </section> + + <section> + <title>set_plugin_config</title> + + <para> + Perl prototype: + <command> + weechat::set_plugin_config ( option, valeur ); + </command> + </para> + <para> + Python prototype: + <command> + weechat.set_plugin_config ( option, valeur ) + </command> + </para> + <para> + Ruby prototype: + <command> + Weechat.set_plugin_config ( option, valeur ) + </command> + </para> + <para> + Update value of a plugin option. Option is written in file + "<literal>~/.weechat/plugins.rc</literal>" and is like: + "<literal>plugin.option=value</literal>" (note: plugin name + is automatically added). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>option</option>: name of option to update + </para> + </listitem> + <listitem> + <para> + <option>value</option>: new value for option + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: 1 if option was successfully updated, 0 if an error + occured. + </para> + <para> + Examples: +<screen> +# perl +weechat::set_plugin_config ("my_var", "value"); + +# python +weechat.set_plugin_config ("my_var", "value") + +# ruby +Weechat.set_plugin_config ("my_var", "value") +</screen> + </para> + </section> + + </section> + + </section> + + </chapter> + + <!-- ======================== Auteurs / Support ========================= --> + + <chapter id="chapAuthorsSupport"> + <title>Authors / Support</title> + + <para> + This chapter lists authors and contributors for WeeChat, and + shows ways to get support. + </para> + + <section id="secAuthors"> + <title>Authors</title> + + <para> + WeeChat is developed by: + <itemizedlist> + <listitem> + <para> + <emphasis>FlashCode (Sébastien Helleu)</emphasis> + <email>flashcode AT flashtux.org</email> - + main developer + </para> + </listitem> + <listitem> + <para> + <emphasis>Kolter</emphasis> + <email>kolter AT free.fr</email> - + developer + </para> + </listitem> + <listitem> + <para> + <emphasis>Ptitlouis</emphasis> + <email>ptitlouis AT sysif.net</email> - + Debian packager + </para> + </listitem> + </itemizedlist> + </para> + + </section> + + <section id="secContributors"> + <title>Contributors</title> + + <para> + Following people contributed to WeeChat: + <itemizedlist> + <listitem> + <para> + <emphasis>Jiri Golembiovsky</emphasis> - + czech translation + </para> + </listitem> + <listitem> + <para> + <emphasis>Rudolf Polzer</emphasis> - + patches + </para> + </listitem> + <listitem> + <para> + <emphasis>Jim Ramsay</emphasis> - + patches + </para> + </listitem> + <listitem> + <para> + <emphasis>Pistos</emphasis> - + patches + </para> + </listitem> + </itemizedlist> + </para> + + </section> + + <section id="secSupport"> + <title>Get support</title> + + <para> + Before asking for support, be sure you've read documentation and FAQ + provided with WeeChat (documentation is this document, if you don't + read all lines until this sentence, you can start again!) + </para> + + <para> + <itemizedlist> + <listitem> + <para> + IRC: server "<literal>irc.freenode.net</literal>", + channel "<literal>#weechat</literal>" + </para> + </listitem> + <listitem> + <para> + WeeChat forum: + <ulink url="http://forums.flashtux.org"> + http://forums.flashtux.org + </ulink> + </para> + </listitem> + <listitem> + <para> + Mailing list: + <itemizedlist> + <listitem> + <para> + To subscribe: + <ulink url="http://mail.nongnu.org/mailman/listinfo/weechat-support"> + http://mail.nongnu.org/mailman/listinfo/weechat-support + </ulink> + </para> + </listitem> + <listitem> + <para> + To send a mail on mailing list: + <email>weechat-support@nongnu.org</email> + </para> + </listitem> + </itemizedlist> + Mailing list archives are available here: + <ulink url="http://mail.nongnu.org/archive/html/weechat-support"> + http://mail.nongnu.org/archive/html/weechat-support + </ulink> + </para> + </listitem> + </itemizedlist> + </para> + + </section> + + </chapter> + +</book> |