From b10b53c6894081b9229a5ce383de96b4e47b8746 Mon Sep 17 00:00:00 2001 From: Sebastien Helleu Date: Mon, 2 Jan 2006 22:16:54 +0000 Subject: Replaced Texinfo doc by XML Docbook --- doc/en/weechat.en.xml | 3483 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 3483 insertions(+) create mode 100644 doc/en/weechat.en.xml (limited to 'doc/en/weechat.en.xml') 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 @@ + + + + + + + + +]> + + + + + + WeeChat 0.1.7-cvs - User guide + Fast, light and extensible IRC client + + + Sébastien + Helleu + flashcode AT flashtux.org + + + + 2006 + Sébastien Helleu + + + + + 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 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. + + + 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 + + + + + + This manual documents WeeChat IRC client, it is part of WeeChat. + + + Latest version of this document can be found on this page: + + http://weechat.flashtux.org/doc.php + + + + + + + + + + Introduction + + + This chapter describes WeeChat and pre-requisites for its installation. + + +
+ Description + + + WeeChat (Wee Enhanced Environment for Chat) is a free + IRC client, fast and light, designed for many + operating systems. + + + + Main features are: + + + + multi-servers connection (with SSL, IPv6, proxy) + + + + + many GUI: Curses, wxWidgets, Gtk and Qt + + + + + small, fast and light + + + + + customizable and extensible with plugins and scripts + + + + + compliant with RFCs + 1459, + 2810, + 2811, + 2812 and + 2813 + + + + + multi-platform (GNU/Linux, *BSD, MacOS X, Windows and other) + + + + + 100% GPL, free software + + + + + + + WeeChat homepage is here: + + http://weechat.flashtux.org + + + +
+ +
+ Pre-requisites + + + In order to install WeeChat, you need: + + + + a running GNU/Linux system (with compiler tools for source + package) + + + + + "root" privileges (to install WeeChat) + + + + + according to GUI, one of the following libraries: + + + + Curses: ncurses library + + + + + Gtk: *** GUI not developed *** + + + + + WxWidgets: *** GUI not developed *** + + + + + Qt: *** GUI not developed *** + + + + + + + + +
+ + + + + + Installation + + + This chapter explains how to install WeeChat. + + +
+ Binary packages + + + Binary packages are available for these distributions: + + + + Debian (or any Debian compatible distribution): + apt-get install weechat + + + + + Mandriva/RedHat (or any RPM compatible distribution): + + rpm -i /chemin/weechat-x.y.z-1.i386.rpm + + + + + + Gentoo : + emerge weechat + + + + + For other distributions, please look at your manual for + installation instructions. + + +
+ +
+ Source package + + + All you have to do is to run in a console or a terminal: +$ ./configure +$ make + + + Then get root privileges and install WeeChat: +$ su +(enter root password) +# make install + + +
+ +
+ CVS sources + + + Warning: CVS sources are for advanced users: it may not compile + or not be stable. You're warned! + + + + To get CVS sources, issue this command: +$ cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/weechat co weechat + + + + Execute this script: + ./autogen.sh + + + + Then follow instructions for source package + (see ) + + +
+ + + + + + + Usage + + + This chapter explains how to run WeeChat, the default key bindings + used, internal and IRC commands, setup file, and FIFO pipe use. + + +
+ Run WeeChat + + + Command line arguments: + + + + + Parameter + Description + + + + + -a, --no-connect + + Disable auto-connect to servers at startup + + + + -c, --config + + Display config help (list of options) + + + + -f, --key-functions + + Display WeeChat internal functions for keys + + + + -h, --help + + Display help + + + + -i, --irc-commands + + Display IRC commands list + + + + -k, --keys + + Display WeeChat default keys + + + + -l, --license + + Display WeeChat license + + + + -p, --no-plugin + + Disable plugins auto-load + + + + -v, --version + + Display WeeChat version + + + + -w, --weechat-commands + + Display WeeChat commands list + + + + + + + + + It is also possible to give URL for one or many IRC servers, as + follow: + irc[6][s]://[pseudo[:mot_passe]@]irc.example.org[:port][/channel][,channel[...] + Example to join #weechat and #toto on + "irc.freenode.net" server, default port (6667), + with "nono" nick: + $ weechat-curses irc://nono@irc.freenode.net/#weechat,#toto + + + + To start WeeChat, issue this command: + + + + for Curses GUI: weechat-curses + + + + + for Gtk GUI: weechat-gtk + + + + + for wxWidgets GUI: weechat-wxwidgets + + + + + for Qt GUI: weechat-qt + + + + + + + When you run WeeChat for the first time, a default configuration + file is created, with default options. + The default configuration file is: + "~/.weechat/weechat.rc" + + + + You can edit thie file at your convenience to configure WeeChat + (ONLY if WeeChat is not running), or you can set parameters with + "/set" command in WeeChat + (see ) + + +
+ +
+ Key bindings + + + + + + + Key + Action + + + + + Left arrow + + Go to previous char in command line + + + + Right arrow + + Go to next char in command line + + + + Ctrl + left arrow + + Go to previous word in command line + + + + Ctrl + right arrow + + Go to next word in command line + + + + Home / Ctrl + A + + Go to the beginning of command line + + + + End / Ctrl + E + + Go to the end of command line + + + + Ctrl + K + + Delete from cursor until end of command line + + + + Ctrl + L + + Redraw whole window + + + + Ctrl + U + + Delete from cursor until beginning of command line + + + + Ctrl + W + + Delete previous word of command line + + + + Backspace + + Delete previous char in command line + + + + Delete + + Delete next char in command line + + + + Tab + + Complete command or nick + (Tab again: find next completion) + + + + Any char + + Insert char at cursor position in command line + + + + Enter + + Execute command or send message + + + + Up arrow / Down arrow + + Call again last commands/messages + + + + Ctrl + up arrow / Ctrl + down arrow + + Call again last commands/messages in global history + (common for all buffers) + + + + PageUp / PageDown + + Show buffer history + + + + F5 / Alt + left arrow + + Switch to previous buffer + + + + F6 / Alt + right arrow + + Switch to next buffer + + + + F7 + + Switch to previous window + + + + F8 + + Switch to next window + + + + F10 + + Remove last infobar message + + + + F11 / F12 + + Scroll nicklist + + + + Alt + Home / Alt + End + + Go to the beginning / the end of nicklist + + + + Alt + A + + Switch to next buffer with activity + (with priority: highlight, message, other) + + + + Alt + B + + Go to previous word in command line + + + + Alt + D + + Delete next word in command line + + + + Alt + F + + Go to next word in command line + + + + Alt + H + + Clear hotlist + (activity notification on other buffers) + + + + Alt + J then Alt + D + + Display DCC buffer + + + + Alt + J then Alt + L + + Switch to last buffer + + + + Alt + J then Alt + S + + Switch to server buffer + + + + Alt + J puis Alt + X + + Switch to first channel of next buffer + (or server buffer if no channel is opened) + + + + Alt + digit (0-9) + + Switch to buffer by number (0 = 10) + + + + Alt + J then number (01-99) + + Switch to buffer by number + + + + Alt + K + + Grab a key and insert its code in command line + + + + Alt + N + + Scroll to next highlight + + + + Alt + P + + Scroll to previous highlight + + + + Alt + R + + Delete entire command line + + + + Alt + S + + Switch servers on servers buffer + (if option "look_one_server_buffer" is enabled) + + + + Alt + U + + Scroll to first unread line in buffer + + + + Alt + W then Alt + flèche + + Switch to window with direction + + + + + + + +
+ +
+ WeeChat / IRC commands + + + This chapter lists all WeeChat and IRC commands. + + +
+ WeeChat commands + + + &weechat_commands.xml; + + +
+ +
+ Key functions + + + + + + + Function + Description + + + + + &key_functions.xml; + + + + + + +
+ +
+ IRC commands + + + &irc_commands.xml; + + +
+ +
+ +
+ Configuration file + + + List of options for config file: + + + + + Option + Type + Values + Default + Description + + + + + &config.xml; + + + + + + + + Colors for Curses GUI are: + + + + + Keyword + Color + + + + + default + default color (transparent for background) + + + black + black + + + red + dark red + + + lightred + light red + + + green + dark green + + + lightgreen + light green + + + brown + brown + + + yellow + yellow + + + blue + dark blue + + + lightblue + light blue + + + magenta + dark magenta + + + lightmagenta + light magenta + + + cyan + dark cyan + + + lightcyan + light cyan + + + white + white + + + + + + +
+ +
+ FIFO pipe + + + 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). + + + + The FIFO pipe is located in "~/.weechat/" 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. + + + + The syntax for the FIFO pipe commands/text is: + server,channel *text or command here + where server and channel are optional, but if channel is here, server + should be too. + + + + Some examples: + + + + nick change on freenode to "mynick|out" : + $ echo "freenode */nick mynick|out" >~/.weechat/weechat_fifo_12345 + + + + + display text on #weechat channel: + $ echo "freenode,#weechat *hello everybody!" >~/.weechat/weechat_fifo_12345 + + + + + display text on current channel (buffer displayed by WeeChat): + $ echo "*hello!" >~/.weechat/weechat_fifo_12345 + Warning: this is dangerous and you should + not do that except if you know what you do! + + + + + send two commands to unload/reload Perl scripts (you have to + separate them with "\n"): + $ echo -e "freenode */perl unload\nfreenode */perl autoload" >~/.weechat/weechat_fifo_12345 + + + + + + + You can write a script to send command to all running WeeChat at same + time, for example: + +#!/bin/sh +if [ $# -eq 1 ]; then + for fifo in $(/bin/ls ~/.weechat/weechat_fifo_* 2>/dev/null); do + echo -e "$1" >$fifo + done +fi + + If the script is called "auto_weechat_command", you can run it with: + $ ./auto_weechat_command "freenode,#weechat *hello" + + +
+ + + + + + + Plugins + + + This chapter describes WeeChat plugins interface (API) and + the default scripts plugins (Perl, Python, Ruby), provided with + WeeChat. + + +
+ Plugins in WeeChat + + + A plugin is a C program which can call WeeChat functions defined in + an interface. + + + + This C program does not need WeeChat sources to compile and can be + dynamically loaded into WeeChat with command + /plugin. + + + + 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. + + +
+ +
+ Write a plugin + + + 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. + + + + The plugin must have some variables and functions (mandatory, + without them the plugin can't load): + + + + + Variable + Description + + + + + char plugin_name[] + plugin name + + + char plugin_version[] + plugin version + + + char plugin_description[] + short description of plugin + + + + + + + + + + Function + Description + + + + + int weechat_plugin_init (t_weechat_plugin *plugin) + + 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) + + + + void weechat_plugin_end (t_weechat_plugin *plugin) + function called when plugin is unloaded + + + + + + +
+ API functions + +
+ ascii_strcasecmp + + + Prototype: + + int ascii_strcasecmp (t_weechat_plugin *plugin, + char *string1, char *string2) + + + + Locale and case independent string comparison. + + + Arguments: + + + + : pointer to plugin structure + + + + + : first string for comparison + + + + + : second string for comparison + + + + + + Return value: difference between two strings: negative if + string1 < string2, zero if string1 == string2, positive if + string1 > string2 + + + Example: + if (plugin->ascii_strcasecmp (plugin, "abc", "def") != 0) ... + +
+ +
+ ascii_strncasecmp + + + Prototype: + + int ascii_strncasecmp (t_weechat_plugin *plugin, + char *string1, char *string2, int max) + + + + Locale and case independent string comparison, for "max" chars. + + + Arguments: + + + + : pointer to plugin struct + + + + + : first string for comparison + + + + + : second string for comparison + + + + + : max number of chars for comparison + + + + + + Return value: difference between two strings: negative if + string1 < string2, zero if string1 == string2, positive if + string1 > string2 + + + Example: + if (plugin->ascii_strncasecmp (plugin, "abc", "def", 2) != 0) ... + +
+ +
+ explode_string + + + Prototype: + + char **explode_string (t_weechat_plugin *plugin, char *string, + char *separators, int num_items_max, int *num_items) + + + + Explode a string according to one or more delimiter(s). + + + Arguments: + + + + : pointer to plugin struct + + + + + : string to explode + + + + + : delimiters used for explosion + + + + + : maximum number of items + created (0 = no limit) + + + + + : pointer to int which will + contain number of items created + + + + + + Return value: array of strings, NULL if problem. + + + Note: result has to be free by a call to "free_exloded_string" + after use. + + + Example: + +char **argv; +int argc; +argv = plugin->explode_string (plugin, string, " ", 0, &argc); +... +if (argv != NULL) + plugin->free_exploded_string (plugin, argv); + + +
+ +
+ free_exploded_string + + + Prototype: + + char **free_exploded_string (t_weechat_plugin *plugin, + char **string) + + + + Free memory used by a string explosion. + + + Arguments: + + + + : pointer to plugin structure + + + + + : string exploded by + "explode_string" function + + + + + + Return value: none. + + + Example: + +char *argv; +int argc; +argv = plugin->explode_string (plugin, string, " ", 0, &argc); +... +if (argv != NULL) + plugin->free_exploded_string (plugin, argv); + + +
+ +
+ exec_on_files + + + Prototype: + + void exec_on_files (t_weechat_plugin *plugin, char *repertoire, + int (*callback)(t_weechat_plugin *, char *)) + + + + Execute a function on all files of a directory. + + + Arguments: + + + + : pointer tu plugin structure + + + + + : directory for searching files + + + + + : function called for each file + found + + + + + + Return value: none. + + + Example: + +int callback (t_weechat_plugin *plugin, char *file) +{ + plugin->printf_server (plugin, "file: %s", file); + return 1; +} +... +plugin->exec_on_files (plugin, "/tmp", &callback); + + +
+ +
+ printf + + + Prototype: + + void printf (t_weechat_plugin *plugin, + char *server, char *channel, char *message, ...) + + + + Display a message on a WeeChat buffer, identified by server and + channel (both may be NULL for current buffer). + + + Arguments: + + + + : pointer to plugin structure + + + + + : internal name of server to find + buffer for message display (may be NULL) + + + + + : name of channel to find buffer + for message display (may be NULL) + + + + + : message + + + + + + Return value: none. + + + Examples: + +plugin->printf (plugin, NULL, NULL, "hello"); +plugin->printf (plugin, NULL, "#weechat", "hello"); +plugin->printf (plugin, "freenode", "#weechat", "hello"); + + +
+ +
+ printf_server + + + Prototype: + + void printf_server (t_weechat_plugin *plugin, + char *message, ...) + + + + Display a message on current server buffer. + + + Arguments: + + + + : pointer to plugin structure + + + + + : message + + + + + + Return value: none. + + + Example: plugin->printf_server (plugin, "hello"); + +
+ +
+ printf_infobar + + + Prototype: + + void printf_infobar (t_weechat_plugin *plugin, + int time, char *message, ...) + + + + Display a message in infobar for a specified time. + + + Arguments: + + + + : pointer to plugin structure + + + + + : time (in seconds) for displaying + message (0 = never erased) + + + + + + Return value: none. + + + Example: + +plugin->printf_infobar (plugin, 5, "hello"); + + +
+ +
+ msg_handler_add + + + Prototype: + + t_plugin_handler *msg_handler_add (t_weechat_plugin + *plugin, char *message, t_plugin_handler_func *function, + char *handler_args, void *handler_pointer) + + + + Add an IRC message handler, called when an IRC message is + received. + + + Arguments: + + + + : pointer to plugin structure + + + + + : name of IRC message. + To know list of IRC messages, please consult + RFCs + 1459 and + 2812 + + + + + : function called when message + is received + + + + + : arguments given to function + when called + + + + + : pointer given to function + when called + + + + + + Return value: pointer to new message handler. + + + Note: function called when message is received has to return + one of following values: + + + + PLUGIN_RC_KO: function failed + + + + + PLUGIN_RC_OK: function successfully + completed + + + + + PLUGIN_RC_OK_IGNORE_WEECHAT: message + will not be sent to WeeChat + + + + + PLUGIN_RC_OK_IGNORE_PLUGINS: message + will not be sent to other plugins + + + + + PLUGIN_RC_OK_IGNORE_ALL: message + will not be sent to WeeChat neither other plugins + + + + + + Example: + +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); + + +
+ +
+ cmd_handler_add + + + Prototype: + + 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) + + + + Add a WeeChat command handler, called when user uses command + (for example /command). + + + Arguments: + + + + : pointer to plugin structure + + + + + : the new command name, which + may be an existing command (be careful, replaced command + will not be available until plugin is unloaded) + + + + + : short command description + (displayed by /help command) + + + + + : short description of command + arguments (displayed by /help command) + + + + + : long description + of command arguments (displayed by /help command) + + + + + : template for + completion, like "abc|%w def|%i" + 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. + + + Following codes can be used: + + + + + Code + Description + + + + + %- + no completion for argument + + + %a + alias + + + %A + + alias and commandes (WeeChat, IRC and plugins) + + + + %c + current channel + + + %C + channels of current server + + + %f + filename + + + %h + plugins commands + + + %i + IRC commands (sent) + + + %I + IRC commands (received) + + + %k + key functions + + + %n + nicks of current channel + + + %o + setup options + + + %p + default "part" message + + + %q + default "quit" message + + + %s + current server name + + + %S + all servers names + + + %t + topic of current channel + + + %v + setup option value + + + %w + WeeChat commands + + + %y + default "away" message + + + + + + + + + : function called when command + is executed + + + + + : arguments given to function + when called + + + + + : pointer given to function + when called + + + + + + Return value: pointer to new command handler. + + + Note: function called when command is executed has to return + one of following values: + + + + PLUGIN_RC_KO: function failed + + + + + PLUGIN_RC_OK: function successfulle + completed + + + + + + Example: + +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); + + +
+ +
+ handler_remove + + + Prototype: + + void handler_remove (t_weechat_plugin *plugin, + t_plugin_handler *handler) + + + + Remove a handler. + + + Arguments: + + + + : pointer to plugin structure + + + + + : handler to remove + + + + + + Return value: none. + + + Example: + plugin->handler_remove (plugin, my_handler); + +
+ +
+ handler_remove_all + + + Prototype: + + void handler_remove_all (t_weechat_plugin *plugin) + + + + Remove all handlers for a plugin. + + + Arguments: + + + + : pointer to plugin structure + + + + + + Return value: none. + + + Example: + plugin->handler_remove_all (plugin); + +
+ +
+ exec_command + + + Prototype: + + void exec_command (t_weechat_plugin + *plugin, char *server, char *channel, char *command) + + + + Execute a WeeChat command (or send a message to a channel). + + + Arguments: + + + + : pointer to plugin structure + + + + + : internal name of server for + executing command (may be NULL) + + + + + : name of channel for executing + command (may be NULL) + + + + + : command + + + + + + Return value: none. + + + Examples: + +plugin->exec_command (plugin, NULL, NULL, "/help nick"); +plugin->exec_command (plugin, "freenode", "#weechat", "hello"); + + +
+ +
+ get_info + + + Prototype: + + char *get_info (t_weechat_plugin *plugin, + char *info, char *server) + + + + Return an info about WeeChat or a channel. + + + Arguments: + + + + : pointer to plugin structure + + + + + : name of info to read: + + + + + Info + Description + + + + + version + WeeChat's version + + + nick + nick + + + channel + + name of channel (NULL for a server or private) + + + + server + name of server + + + away + "away" flag + + + weechat_dir + + WeeChat home dir + (by default: ~/.weechat/) + + + + weechat_libdir + WeeChat system lib directory + + + weechat_sharedir + WeeChat system share directory + + + + + + + + + : internal name of server for + reading info (if needed) + + + + + + Return value: information asked, NULL if not found. + + + Note: result has to be free by a call to "free" function after + use. + + + Examples: + +char *version = plugin->get_info (plugin, "version", NULL); +char *nick = plugin->get_info (plugin, "nick", "freenode"); + + +
+ +
+ get_dcc_info + + + Prototype: + + t_plugin_info_dcc *get_dcc_info (t_weechat_plugin *plugin) + + + + Return list of DCC currently active or finished. + + + Arguments: + + + + : pointer to plugin structure + + + + + + Return value: linked list of DCC. + + + + + Field + Description + + + + + server + IRC server + + + channel + IRC channel + + + type + + DCC type: + 0 = chat received, + 1 = chat sent, + 2 = file received, + 3 = file sent + + + + status + + DCC status: + 0 = waiting, + 1 = connecting, + 2 = active, + 3 = finished, + 4 = failed, + 5 = interrupted by user + + + + start_time + date/time of DCC creation + + + start_transfer + date/time of DCC transfert start + + + addr + IP address of remote user + + + port + port used for DCC + + + nick + remote nick + + + filename + file name + + + local_filename + local file name + + + size + file size + + + pos + position in file + + + start_resume + start position after interruption + + + bytes_per_sec + + number of bytes per second since transfert start + + + + + + + + Note: result has to be free by a call to "free_dcc_info" function + after use. + + + Examples: + +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); + + +
+ +
+ free_dcc_info + + + Prototype : + + void free_dcc_info (t_weechat_plugin *plugin, + t_plugin_dcc_info *dcc_info) + + + + Free memory used by a DCC list. + + + Arguments: + + + + : pointer to plugin structure + + + + + : pointer to DCC list returned by + "get_dcc_info" function + + + + + + Return value: none. + + + Example: + plugin->free_dcc_info (plugin, dcc_info); + +
+ +
+ get_config + + + Prototype : + + char *get_config (t_weechat_plugin *plugin, char *option) + + + + Return value of a WeeChat config option. + + + Arguments: + + + + : pointer to plugin structure + + + + + : name of option to read + + + + + + Return value: option value, NULL if not found. + + + Note: result has to be free by a call to "free" function after + use. + + + Examples: + +char *value1 = plugin->get_config (plugin, "look_set_title"); +char *value2 = plugin->get_config (plugin, "freenode.server_autojoin"); + + +
+ +
+ set_config + + + Prototype: + + int set_config (t_weechat_plugin *plugin, + char *option, char *value) + + + + Update value of a WeeChat config option. + + + Arguments: + + + + : pointer to plugin structure + + + + + : name of option to update + + + + + : new value for option + + + + + + Return value: 1 if option was successfully updated, 0 if an + error occured. + + + Example: + +plugin->set_config (plugin, "look_nicklist", "off"); + + +
+ +
+ get_plugin_config + + + Prototype: + + char *get_plugin_config (t_weechat_plugin *plugin, char *option) + + + + Return value of a plugin option. + Option is read from file "~/.weechat/plugins.rc" + and is like: "plugin.option=value" + (note: plugin name is automatically added). + + + Arguments: + + + + : pointer to plugin structure + + + + + : name of option to read + + + + + + Return value: option value, NULL if not found. + + + Note: result has to be free by a call to "free" function after + use. + + + Example: + +char *value = plugin->get_plugin_config (plugin, "my_var"); + + +
+ +
+ set_plugin_config + + + Prototype: + + int set_plugin_config (t_weechat_plugin *plugin, + char *option, char *value) + + + + Update value of a plugin option. + Option is written in file "~/.weechat/plugins.rc" + and is like: "plugin.option=value" + (note: plugin name is automatically added). + + + Arguments: + + + + : pointer to plugin structure + + + + + : name of option to update + + + + + : new value for option + + + + + + Return value: 1 if option was successfully updated, 0 if an + error occurred. + + + Example : + +plugin->set_plugin_config (plugin, "my_var", "value"); + + +
+ +
+ +
+ Compile plugin + + + Compile does not need WeeChat sources, only file + "weechat-plugin.h". + + + + To compile a plugin which has one file "toto.c" (sous GNU/Linux): + +$ gcc -fPIC -Wall -c toto.c +$ gcc -shared -fPIC -o libtoto.so toto.o + + + +
+ +
+ Load plugin into WeeChat + + + Copy "libtoto.so" file into system plugins dir (for example + "/usr/local/lib/weechat/plugins") or into + user's plugins dir (for example + "/home/xxxxx/.weechat/plugins"). + + + + Under WeeChat: + /plugin load toto + + +
+ +
+ Plugin example + + + 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!): + +#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 */ +} + + + +
+ +
+ +
+ Scripts plugins + + + Three plugins are provided with WeeChat to use script languages: + Perl, Python and Ruby. + + +
+ Load / unload scripts + + + Scripts are loaded and unloaded with /perl, + /python and /ruby commands + (type /help in WeeChat for help about commands). + + + + Examples: + + + + Load a Perl script: + /perl load /tmp/test.pl + + + + + List all loaded Perl scripts: + /perl + + + + + Load a Python script: + /python load /tmp/test.py + + + + + List all loaded Python scripts: + /python + + + + + Load a Ruby script: + /ruby load /tmp/test.rb + + + + + List all loaded Ruby scripts: + /ruby + + + + + +
+ +
+ WeeChat / scripts API + +
+ register + + + Perl prototype: + + weechat::register ( name, version, end_function, description ); + + + + Python prototype: + + weechat.register ( name, version, end_function, description ) + + + + Ruby prototype: + + Weechat.register ( name, version, end_function, description ) + + + + This is first function to call in script. + All WeeChat scripts have to call this function. + + + Arguments: + + + + : unique name to identify script + (each script must have unique name) + + + + + : script version + + + + + : function called when script is + unloaded (optional parameter, empty string means nothing is + called at the end) + + + + + : short description of script + + + + + + Return value: 1 if script was registered, 0 if an error occured. + + + Examples: + +# 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!") + + +
+ +
+ print + + + Perl prototype: + + weechat::print ( message, [channel, [server]] ) + + + + Python prototype: + + weechat.prnt ( message, [channel, [server]] ) + + + + Ruby prototype: + + Weechat.print ( message, [channel, [server]] ) + + + + Display a message on a WeeChat buffer, identified by server + and channel. + + + Arguments: + + + + : message + + + + + : name of channel to find buffer + for message display + + + + + : internal name of server to find + buffer for message display + + + + + + Return value: 1 if success, 0 if an error occured. + + + Examples: + +# 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") + + +
+ +
+ print_infobar + + + Perl prototype: + + weechat::print_infobar ( time, message ); + + + + Python prototype: + + weechat.print_infobar ( time, message ) + + + + Ruby prototype: + + Weechat.print_infobar ( time, message ) + + + + Display a message in infobar for a specified time. + + + Arguments: + + + + : time (in seconds) for displaying + message (0 = never erased) + + + + + : message + + + + + + Return value: 1 if success, 0 if an error occured. + + + Examples: + +# perl +weechat::print_infobar (5, "message"); + +# python +weechat.print_infobar (5, "message") + +# ruby +Weechat.print_infobar (5, "message") + + +
+ +
+ add_message_handler + + + Perl prototype: + + weechat::add_message_handler ( message, function ); + + + + Python prototype: + + weechat.add_message_handler ( message, function ) + + + + Ruby prototype: + + Weechat.add_message_handler ( message, function ) + + + + Add an IRC message handler, called when an IRC message is + received. + + + Arguments: + + + + : name of IRC message. To know list + of IRC messages, please consult RFCs + 1459 and + 2812 + + + + + : function called when message is + received + + + + + + Return value: 1 if success, 0 if an error occured. + + + Examples: + +# 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 + + + + 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): + + + + PLUGIN_RC_KO: function failed + + + + + PLUGIN_RC_OK: function successfully + completed + + + + + PLUGIN_RC_OK_IGNORE_WEECHAT: message + will not be sent to WeeChat + + + + + PLUGIN_RC_OK_IGNORE_PLUGINS: message + will not be sent to other plugins + + + + + PLUGIN_RC_OK_IGNORE_ALL: message + will not be sent to WeeChat neither other plugins + + + + +
+ +
+ add_command_handler + + + Perl prototype: + + weechat::add_command_handler ( command, function, + [description, arguments, arguments_description, + completion_template] ); + + + + Python prototype: + + weechat.add_command_handler ( command, function, + [description, arguments, arguments_description, + completion_template] ) + + + + Ruby prototype: + + Weechat.add_command_handler ( command, function, + [description, arguments, arguments_description, + completion_template] ) + + + + Add a WeeChat command handler, called when user uses command + (for example /command). + + + Paramètres : + + + + : the new command name, which + may be an existing command (be careful, replaced command + will not be available until script is unloaded) + + + + + : fonction appelée lorsque la + commande est exécutée + + + + + : short description of command + arguments (displayed by /help command) + + + + + : long description + of command arguments (displayed by /help command) + + + + + : template for + completion, like "abc|%w def|%i" which + means "abc" or a WeeChat command for first argument, + "def" or IRC command for second. + (see ) + + + + + + Return value: 1 if success, 0 if an error occured. + + + Examples: + +# 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 + + + + 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): + + + + PLUGIN_RC_KO : function failed + + + + + PLUGIN_RC_OK : function successfully + completed + + + + +
+ +
+ remove_handler + + + Perl prototype: + + weechat::remove_handler ( name, function ); + + + + Python prototype: + + weechat.remove_handler ( name, function ) + + + + Ruby prototype: + + Weechat.remove_handler ( name, function ) + + + + Remove a handler. + + + Arguments: + + + + : name of IRC message or command + + + + + : function + + + + + + Return value: 1 if success, 0 if an error occured. + + + Examples: + +# perl +weechat::remove_handler ("command", my_command); + +# python +weechat.remove_handler ("command", my_command) + +# ruby +Weechat.remove_handler ("command", my_command) + + +
+ +
+ command + + + Perl prototype: + + weechat::command ( command, [channel, [server]] ); + + + + Python prototype: + + weechat.command ( command, [channel, [server]] ) + + + + Ruby prototype: + + Weechat.command ( command, [channel, [server]] ) + + + + Execute a WeeChat command (or send a message to a channel). + + + Arguments: + + + + : command + + + + + : name of channel for executing + command + + + + + : internal name of server for + executing command + + + + + + Return value: 1 if success, 0 if an error occured. + + + Examples: + +# 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") + + +
+ +
+ get_info + + + Perl prototype: + + weechat::get_info ( name, [server] ); + + + + Python prototype: + + weechat.get_info ( name, [server] ) + + + + Ruby prototype: + + Weechat.get_info ( name, [server] ) + + + + Return an info about WeeChat or a channel. + + + Arguments: + + + + : name of info to read + (see ) + + + + + : internal name of server for + reading info (if needed) + + + + + + Return value: information asked, empty string if an error + occured + + + Examples: + +# perl +$version = get_info("version"); +$nick = get_info("nick", "freenode"); + +# python +version = weechat.get_info ("version") +nick = weechat.get_info ("nick", "freenode") + + +
+ +
+ get_dcc_info + + + Perl prototype: + + weechat::get_dcc_info ( ); + + + + Python prototype: + + weechat.get_dcc_info ( ) + + + + Ruby prototype : + + Weechat.get_dcc_info ( ) + + + + Return list of DCC currently active or finished. + + + Return value: list of DCC + (see ). + +
+ +
+ get_config + + + Perl prototype: + + weechat::get_config ( option ); + + + + Python prototype: + + weechat.get_config ( option ) + + + + Ruby prototype: + + Weechat.get_config ( option ) + + + + Return value of a WeeChat config option. + + + Arguments: + + + + : name of option to read + + + + + + Return value: option value, empty string if not found. + + + Examples: + +# 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") + + +
+ +
+ set_config + + + Perl prototype: + + weechat::set_config ( option, value ); + + + + Python prototype: + + weechat.set_config ( option, value ) + + + + Ruby prototype: + + Weechat.set_config ( option, value ) + + + + Update value of a WeeChat config option. + + + Arguments: + + + + : name of option to update + + + + + : new value for option + + + + + + Return value: 1 if option was successfully updated, 0 if an error + occured. + + + Examples: + +# 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") + + +
+ +
+ get_plugin_config + + + Perl prototype: + + weechat::get_plugin_config ( option ); + + + + Python prototype: + + weechat.get_plugin_config ( option ) + + + + Ruby prototype: + + Weechat.get_plugin_config ( option ) + + + + Return value of a plugin option. Option is read from file + "~/.weechat/plugins.rc" and is like: + "plugin.option=value" (note: plugin name + is automatically added). + + + Arguments: + + + + : name of option to read + + + + + + Return value: value of option, empty string if not found. + + + Examples : + +# perl +$value = weechat::get_plugin_config ("my_var"); + +# python +value = weechat.get_plugin_config ("my_var") + + +
+ +
+ set_plugin_config + + + Perl prototype: + + weechat::set_plugin_config ( option, valeur ); + + + + Python prototype: + + weechat.set_plugin_config ( option, valeur ) + + + + Ruby prototype: + + Weechat.set_plugin_config ( option, valeur ) + + + + Update value of a plugin option. Option is written in file + "~/.weechat/plugins.rc" and is like: + "plugin.option=value" (note: plugin name + is automatically added). + + + Arguments: + + + + : name of option to update + + + + + : new value for option + + + + + + Return value: 1 if option was successfully updated, 0 if an error + occured. + + + Examples: + +# perl +weechat::set_plugin_config ("my_var", "value"); + +# python +weechat.set_plugin_config ("my_var", "value") + +# ruby +Weechat.set_plugin_config ("my_var", "value") + + +
+ +
+ +
+ + + + + + + Authors / Support + + + This chapter lists authors and contributors for WeeChat, and + shows ways to get support. + + +
+ Authors + + + WeeChat is developed by: + + + + FlashCode (Sébastien Helleu) + flashcode AT flashtux.org - + main developer + + + + + Kolter + kolter AT free.fr - + developer + + + + + Ptitlouis + ptitlouis AT sysif.net - + Debian packager + + + + + +
+ +
+ Contributors + + + Following people contributed to WeeChat: + + + + Jiri Golembiovsky - + czech translation + + + + + Rudolf Polzer - + patches + + + + + Jim Ramsay - + patches + + + + + Pistos - + patches + + + + + +
+ +
+ Get support + + + 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!) + + + + + + + IRC: server "irc.freenode.net", + channel "#weechat" + + + + + WeeChat forum: + + http://forums.flashtux.org + + + + + + Mailing list: + + + + To subscribe: + + http://mail.nongnu.org/mailman/listinfo/weechat-support + + + + + + To send a mail on mailing list: + weechat-support@nongnu.org + + + + Mailing list archives are available here: + + http://mail.nongnu.org/archive/html/weechat-support + + + + + + +
+ + + + -- cgit v1.2.3