WeeChat (Wee Enhanced Environment for Chat) is a console IRC client, which is fast and light. It is released under the terms of the GNU General Public License 3 and has been developed since 2003. There is also a GTK+ interface available and a Qt interface planned.[3]
Everything can be done with a keyboard. It is customizable and extensible with plugins and scripts.
WeeChat 0.2.6 – User guide
Fast, light and extensible IRC client
Sébastien Helleu
Copyright © 2007 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 3 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, see .
2007-09-06 10:44:50
Abstract
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
Table of Contents
1. Introduction
Description
Pre-requisites
2. Installation
Binary packages
Source package
CVS sources
3. Usage
Running WeeChat
Key bindings
Command line
WeeChat / IRC commands
WeeChat commands
Key functions
IRC commands
Configuration file
FIFO pipe
4. Plugins
Plugins in WeeChat
Write a plugin
API functions
Compile plugin
Load plugin into WeeChat
Plugin example
Charset plugin
Settings
FAQ
Scripts plugins
Load / unload scripts
Syntax by language
WeeChat / scripts API
5. Authors / Support
Authors
Contributors
Get support
Chapter 1. Introduction
Table of Contents
Description
Pre-requisites
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:
o
Curses: ncurses library
o
Gtk: *** GUI not developed ***
o
WxWidgets: *** GUI not developed ***
o
Qt: *** GUI not developed ***
Chapter 2. Installation
Table of Contents
Binary packages
Source package
CVS sources
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 the section called “Source package”)
Chapter 3. Usage
Table of Contents
Running WeeChat
Key bindings
Command line
WeeChat / IRC commands
WeeChat commands
Key functions
IRC commands
Configuration file
FIFO pipe
This chapter explains how to run WeeChat, the default key bindings used, internal and IRC commands, setup file, and FIFO pipe use.
Running WeeChat
Command line arguments:
Parameter Description
-a, –no-connect Disable auto-connect to servers at startup
-c, –config Display config help (list of options)
-d, –dir Set path as home for WeeChat (used for configuration files, logs, user plugins and scripts). Default value is “~/.weechat”. Please note that directory is created if not found by WeeChat.
-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 this file at your convenience to configure WeeChat (ONLY if WeeChat is not running), or you can set parameters with “/set” command in WeeChat (see the section called “WeeChat commands”)
Key bindings
Key Action
Left arrow / Ctrl + B Go to previous char in command line
Right arrow / Ctrl + F 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
Ctrl + C then B Insert code for bold text.
Ctrl + C then C Insert code for colored text.
Ctrl + C then O Insert code for color reset.
Ctrl + C then R Insert code for reverse color.
Ctrl + C then U Insert code for underlined text.
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 + R Search for text in buffer history (two times: search exact text)
Ctrl + S then Ctrl + U Set unread marker on all buffers
Ctrl + T Transpose chars
Ctrl + U Delete from cursor until beginning of command line
Ctrl + W Delete previous word of command line
Ctrl + Y Paste clipboard content
Backspace / Ctrl + H Delete previous char in command line
Delete / Ctrl + D Delete next char in command line
Tab / Shift + Tab Complete command or nick (Tab again: find next completion)
Any char Insert char at cursor position in command line
Enter / Ctrl + J / Ctrl + M Execute command or send message (in search mode: stop search)
Up arrow / Down arrow Call again last commands/messages (in search mode: search up/down)
Ctrl + up arrow / Ctrl + down arrow Call again last commands/messages in global history (common for all buffers)
PageUp / PageDown Scroll up / down one page in buffer history
Alt + PageUp / Alt + PageDown Scroll up / down a few lines in buffer history
Alt + Home / Alt + End Scroll to top / bottom of buffer
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
F9 / F10 Scroll topic
F11 / F12 Scroll nicklist
Alt + F11 / Alt + F12 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 + I Remove last infobar message
Alt + J then Alt + D Display DCC buffer
Alt + J then Alt + L Switch to last buffer
Alt + J then Alt + P Switch to buffer previously displayed
Alt + J then Alt + R Switch to raw IRC data buffer
Alt + J then Alt + S Switch to server buffer
Alt + J then Alt + X Switch to first channel of next server (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 + arrow Switch to window with direction
Command line
WeeChat command line (at the bottom of window) lets you send text on channels and execute WeeChat or IRC commands (see the section called “WeeChat / IRC commands”).
Commands begin with “/” char, followed by name of command. For example, to initiate a private chat with “toto”:
/query toto
Text sent to a channel is any text that does not begin with “/” char. For example, to send text “hello” on current channel:
hello
However, it is possible to start with “/” char, by adding another. For example, to send text “/query toto” on current channel:
//query toto
If option for sending IRC colors (“irc_colors_send”) is enabled, you can use color codes and attributes, as follow (press Ctrl-C then following letter, with optional value):
Code Description
^Cb bold text
^Ccxx text color “xx” (see colors table below)
^Ccxx,yy text color “xx” and background “yy” (see colors table below)
^Co disable color and attributes
^Cr reverse video (revert text color with background)
^Cu underlined text
Note: the same code (without number for ^Cc) may be used to stop the attribute.
Color codes for ^Cc are:
Code Color
00 white
01 black
02 dark blue
03 dark green
04 light red
05 dark red
06 magenta
07 orange
08 yellow
09 light green
10 cyan
11 light cyan
12 light blue
13 light magenta
14 gray
15 light gray (white)
Example: display of “hello everybody!” with “hello” in light blue bold, and “everybody” in light red underlined:
^Cc12^Cbhello^Cb^Cc04^Cu everybody^Cu^Cc!
WeeChat / IRC commands
WeeChat commands
Key functions
IRC commands
This chapter lists all WeeChat and IRC commands.
WeeChat commands
alias [alias_name [command [arguments]]]
create an alias for a command
alias_name: name of alias
command: command name (WeeChat or IRC command, many commands can be separated by semicolons)
arguments: arguments for command
is replaced by all arguments.
Variables $nick, $channel and $server are replaced by current nick/channel/server.
buffer [action [args] | number | [[server] [channel]]]
manage buffers
action: action to do:
move: move buffer in the list (may be relative, for example -1)
close: close buffer (optional arg is part message, for a channel)
list: list open buffers (no parameter implies this list)
notify: set notify level for buffer (0=never, 1=highlight, 2=1+msg, 3=2+join/part)
(when executed on server buffer, this sets default notify level for whole server)
scroll: scroll in history (may be relative, and may end by a letter: s=sec, m=min, h=hour, d=day, M=month, y=year); if there is only letter, then scroll to beginning of this item
number: jump to buffer by number
server,
channel: jump to buffer by server and/or channel name
Examples:
move buffer: /buffer move 5
close buffer: /buffer close this is part msg
set notify: /buffer notify 2
scroll 1 day up: /buffer scroll 1d == /buffer scroll -1d == /buffer scroll -24h
scroll to beginning
of this day: /buffer scroll d
scroll 15 min down: /buffer scroll +15m
scroll 20 msgs up: /buffer scroll -20
jump to #weechat: /buffer #weechat
builtin command
launch WeeChat/IRC builtin command (do not look at plugins handlers or aliases)
command: command to execute (a ‘/’ is automatically added if not found at beginning of command)
clear [-all | number [number ...]]
clear window(s)
-all: clear all buffers
number: clear buffer by number
connect [-all [-nojoin] | servername [servername ...] [-nojoin] | hostname [-port port] [-ipv6] [-ssl]]
connect to server(s)
-all: connect to all servers
servername: internal server name to connect
-nojoin: do not join any channel (even if autojoin is enabled on server)
hostname: hostname to connect, creating temporary server
port: port for server (integer, default is 6667)
ipv6: use IPv6 protocol
ssl: use SSL protocol
disconnect [-all | servername [servername ...]]
disconnect from server(s)
-all: disconnect from all servers
servername: server name to disconnect
dcc action [nickname [file]]
starts DCC (file or chat) or close chat
action: ‘send’ (file) or ‘chat’ or ‘close’ (chat)
nickname: nickname to send file or chat
file: filename (on local host)
debug dump | buffer | windows
print debug messages
dump: save memory dump in WeeChat log file (same dump is written when WeeChat crashes)
buffer: dump buffer content with hexadecimal values in log file
windows: display windows tree
help [command]
display help about commands
command: name of a WeeChat or IRC command
history [clear | value]
show buffer command history
clear: clear history
value: number of history entries to show
ignore [mask [[type | command] [channel [server]]]]
ignore IRC messages and/or hosts
mask: nick or host mask to ignore
type: type of message to ignore (action, ctcp, dcc, pv)
command: IRC command
channel: name of channel for ignore
server: name of server for ignore
For each argument, ‘*’ means all.
Without argument, /ignore command lists all defined ignore.
key [key [function/command]] [unbind key] [functions] [call function ["args"]] [reset -yes]
bind/unbind keys
key: display or bind this key to an internal function or a command (beginning by “/”)
unbind: unbind a key
functions: list internal functions for key bindings
call: call a function by name (with optional arguments)
reset: restore bindings to the default values and delete ALL personal bindings (use carefully!)
plugin [list [name]] | [listfull [name]] | [load filename] | [autoload] | [reload [name]] | [unload [name]]
list/load/unload plugins
list: list loaded plugins
listfull: list loaded plugins with detailed info for each plugin
load: load a plugin
autoload: autoload plugins in system or user directory
reload: reload one plugin (if no name given, unload all plugins, then autoload plugins)
unload: unload one or all plugins
Without argument, /plugin command lists loaded plugins.
reconnect [-all [-nojoin] | servername [servername ...] [-nojoin]]
reconnect to server(s)
-all: reconnect to all servers
servername: server name to reconnect
-nojoin: do not join any channel (even if autojoin is enabled on server)
save [file]
save config to disk
file: filename for writing config
server [list [servername]] | [listfull [servername]] | [add servername hostname [-port port] [-temp] [-auto | -noauto] [-ipv6] [-ssl] [-pwd password] [-nicks nick1 nick2 nick3] [-username username] [-realname realname] [-command command] [-autojoin channel[,channel]] ] | [copy servername newservername] | [rename servername newservername] | [keep servername] | [del servername]
list, add or remove servers
list: list servers (no parameter implies this list)
listfull: list servers with detailed info for each server
add: create a new server
servername: server name, for internal and display use
hostname: name or IP address of server
port: port for server (integer, default is 6667)
temp: create temporary server (not saved in config file)
auto: automatically connect to server when WeeChat starts
noauto: do not connect to server when WeeChat starts (default)
ipv6: use IPv6 protocol
ssl: use SSL protocol
password: password for server
nick1: first nick for server
nick2: alternate nick for server
nick3: second alternate nick for server
username: user name
realname: real name of user
copy: duplicate a server
rename: rename a server
keep: keep server in config file (for temporary servers only)
del: delete a server
deloutq: delete messages out queue for all servers (all messages WeeChat is currently sending)
set [option [ = value]]
set config options
option: name of an option (if name is full and no value is given, then help is displayed on option)
value: value for option
Option may be: servername.server_xxx where “servername” is an internal server name and “xxx” an option for this server.
setp [option [ = value]]
set plugin config options
option: name of a plugin option
value: value for option
Option is format: plugin.option, example: perl.myscript.item1
unalias alias_name
remove an alias
alias_name: name of alias to remove
unignore [number | [mask [[type | command] [channel [server]]]]]
unignore IRC messages and/or hosts
number: # of ignore to unignore (number is displayed by list of ignore)
mask: nick or host mask to unignore
type: type of message to unignore (action, ctcp, dcc, pv)
command: IRC command
channel: name of channel for unignore
server: name of server for unignore
For each argument, ‘*’ means all.
Without argument, /unignore command lists all defined ignore.
upgrade [path_to_binary]
upgrade WeeChat without disconnecting from servers
path_to_binary: path to WeeChat binary (default is current binary)
This command run again a WeeChat binary, so it should have been compiled or installed with a package manager before running this command.
uptime [-o]
show WeeChat uptime
-o: send uptime on current channel as an IRC message
window [list | -1 | +1 | b# | up | down | left | right | splith [pct] | splitv [pct] | resize pct | merge [all]]
manage windows
list: list open windows (no parameter implies this list)
-1: jump to previous window
+1: jump to next window
b#: jump to next window displaying buffer number #
up: switch to window above current one
down: switch to window below current one
left: switch to window on the left
right: switch to window on the right
splith: split current window horizontally
splitv: split current window vertically
resize: resize window size, new size is pourcentage of parent window
merge: merge window with another (all = keep only one window)
For splith and splitv, pct is a pourcentage which represents size of new window, computed with current window as size reference. For example 25 means create a new window with size = current_size / 4
Key functions
Function Description
return terminate line
tab complete word
tab_previous find previous completion for word
backspace delete previous char
delete delete next char
delete_end_line delete until end of line
delete_beginning_line delete until beginning of line
delete_line delete entire line
delete_previous_word delete previous word
delete_next_word delete next word
clipboard_paste paste current clipboard content
transpose_chars transpose chars
home go to beginning of line
end go to end of line
left move one char left
previous_word move to previous word
right move one char right
next_word move to next word
up call previous command in history
up_global call previous command in global history
down call next command in history
down_global call next command in global history
page_up scroll one page up
page_down scroll one page down
scroll_up scroll a few lines up
scroll_down scroll a few lines down
scroll_top scroll to top of buffer
scroll_bottom scroll to bottom of buffer
scroll_topic_left scroll left topic
scroll_topic_right scroll right topic
nick_beginning display beginning of nicklist
nick_end display end of nicklist
nick_page_up scroll nicklist one page up
nick_page_down scroll nicklist one page down
jump_smart jump to buffer with activity
jump_dcc jump to DCC buffer
jump_raw_data jump to raw IRC data buffer
jump_last_buffer jump to last buffer
jump_previous_buffer jump to previous buffer
jump_server jump to server buffer
jump_next_server jump to next server
switch_server switch active server on servers buffer
scroll_previous_highlight scroll to previous highlight in buffer
scroll_next_highlight scroll to next highlight in buffer
scroll_unread scroll to first unread line in buffer
set_unread set unread marker on all buffers
hotlist_clear clear hotlist
infobar_clear clear infobar
refresh refresh screen
grab_key grab a key
insert insert a string in command line
search_text search text in buffer history
IRC commands
admin [target]
find information about the administrator of the server
target: server
ame message
send a CTCP action to all channels of all connected servers
message: message to send
amsg text
send message to all channels of all connected servers
text: text to send
away [-all] [message]
toggle away status
-all: toggle away status on all connected servers
message: message for away (if no message is given, away status is removed)
ban [channel] [nickname [nickname ...]]
bans nicks or hosts
channel: channel for ban
nickname: user or host to ban
ctcp receiver type [arguments]
send a CTCP message (Client-To-Client Protocol)
receiver: nick or channel to send CTCP to
type: CTCP type (examples: “version”, “ping”, ..)
arguments: arguments for CTCP
cycle [channel[,channel]] [part_message]
leave and rejoin a channel
channel: channel name for cycle
part_message: part message (displayed to other users)
dehalfop [nickname [nickname]]
removes half channel operator status from nickname(s)
deop [nickname [nickname]]
removes channel operator status from nickname(s)
devoice [nickname [nickname]]
removes voice from nickname(s)
die
shutdown the server
halfop [nickname [nickname]]
gives half channel operator status to nickname(s)
info [target]
get information describing the server
target: server name
invite nickname channel
invite a nick on a channel
nickname: nick to invite
channel: channel to invite
ison nickname [nickname ...]
check if a nickname is currently on IRC
nickname: nickname
join channel[,channel] [key[,key]]
join a channel
channel: channel name to join
key: key to join the channel
kick [channel] nickname [comment]
forcibly remove a user from a channel
channel: channel where user is
nickname: nickname to kick
comment: comment for kick
kickban [channel] nickname [comment]
kicks and bans a nick from a channel
channel: channel where user is
nickname: nickname to kick and ban
comment: comment for kick
kill nickname comment
close client-server connection
nickname: nickname
comment: comment for kill
links [[server] server_mask]
list all servernames which are known by the server answering the query
server: this server should answer the query
server_mask: list of servers must match this mask
list [channel[,channel] [server]]
list channels and their topic
channel: channel to list (a regexp is allowed)
server: server name
lusers [mask [target]]
get statistics about the size of the IRC network
mask: servers matching the mask only
target: server for forwarding request
me message
send a CTCP action to the current channel
message: message to send
mode { channel {[+|-]|o|p|s|i|t|n|b|v} [limit] [user] [ban mask] } | { nickname {[+|-]|i|w|s|o} }
change channel or user mode
channel modes:
channel: channel name to modify
o: give/take channel operator privileges
p: private channel flag
s: secret channel flag
i: invite-only channel flag
t: topic settable by channel operator only flag
n: no messages to channel from clients on the outside
m: moderated channel
l: set the user limit to channel
b: set a ban mask to keep users out
e: set exception mask
v: give/take the ability to speak on a moderated channel
k: set a channel key (password)
user modes:
nickname: nickname to modify
i: mark a user as invisible
s: mark a user for receive server notices
w: user receives wallops
o: operator flag
motd [target]
get the “Message Of The Day”
target: server name
msg receiver[,receiver] text
send message to a nick or channel
receiver: nick or channel (may be mask, ‘*’ = current channel)
text: text to send
names [channel[,channel]]
list nicknames on channels
channel: channel name
nick [-all] nickname
change current nickname
-all: set new nickname for all connected servers
nickname: new nickname
notice nickname text
send notice message to user
nickname: user to send notice to
text: text to send
op nickname [nickname]
gives channel operator status to nickname(s)
oper user password
get operator privileges
user/password: used to get privileges on current IRC server
part [channel[,channel]] [part_message]
leave a channel
channel: channel name to leave
part_message: part message (displayed to other users)
ping server1 [server2]
ping server
server1: server to ping
server2: forward ping to this server
pong daemon [daemon2]
answer to a ping message
daemon: daemon who has responded to Ping message
daemon2: forward message to this daemon
query nickname [text]
send a private message to a nick
nickname: nickname for private conversation
text: text to send
quit [quit_message]
close all connections and quit
quit_message: quit message (displayed to other users)
quote data
send raw data to server without parsing
data: raw data to send
rehash
tell the server to reload its config file
restart
tell the server to restart itself
service nickname reserved distribution type reserved info
register a new service
distribution: visibility of service
type: reserved for future usage
servlist [mask [type]]
list services currently connected to the network
mask: list only services matching this mask
type: list only services of this type
squery service text
deliver a message to a service
service: name of service
text: text to send
squit server comment
disconnect server links
server: server name
comment: comment for quit
stats [query [server]]
query statistics about server
query: c/h/i/k/l/m/o/y/u (see RFC1459)
server: server name
summon user [target [channel]]
give users who are on a host running an IRC server a message asking them to please join IRC
user: username
target: server name
channel: channel name
time [target]
query local time from server
target: query time from specified server
topic [channel] [topic]
get/set channel topic
channel: channel name
topic: new topic for channel (if topic is “-delete” then topic is deleted)
trace [target]
find the route to specific server
target: server
unban [channel] nickname [nickname ...]
unbans nicks or hosts
channel: channel for unban
nickname: user or host to unban
userhost nickname [nickname ...]
return a list of information about nicknames
nickname: nickname
users [target]
list of users logged into the server
target: server
version [server | nickname]
gives the version info of nick or server (current or specified)
server: server name
nickname: nickname
voice [nickname [nickname]]
gives voice to nickname(s)
wallops text
send a message to all currently connected users who have set the ‘w’ user mode for themselves
text to send
who [mask ["o"]]
generate a query which returns a list of information
mask: only information which match this mask
o: only operators are returned according to the mask supplied
whois [server] nickname[,nickname]
query information about user(s)
server: server name
nickname: nickname (may be a mask)
whowas nickname [,nickname [,nickname ...]] [count [target]]
ask for information about a nickname which no longer exists
nickname: nickname to search
count: number of replies to return (full search if negative number)
target: reply should match this mask
Configuration file
List of options for config file:
Option Type Values Default Description
look_save_on_exit boolean ‘on’ or ‘off’ ‘on’ Save config file on exit
look_set_title boolean ‘on’ or ‘off’ ‘on’ Set title for window (terminal for Curses GUI) with name and version
look_startup_logo boolean ‘on’ or ‘off’ ‘on’ Display WeeChat logo at startup
look_startup_version boolean ‘on’ or ‘off’ ‘on’ Display WeeChat version at startup
look_weechat_slogan string any string ‘the geekest IRC client!’ WeeChat slogan (if empty, slogan is not used)
look_one_server_buffer boolean ‘on’ or ‘off’ ‘off’ Use same buffer for all servers
look_open_near_server boolean ‘on’ or ‘off’ ‘off’ Open new channels/privates near server
look_scroll_amount integer between 1 and 2147483647 3 How many lines to scroll by with scroll_up and scroll_down
look_buffer_timestamp string any string ‘[%H:%M:%S]‘ Timestamp for buffers
look_color_nicks_number integer between 1 and 10 10 Number of colors to use for nicks colors
look_color_actions boolean ‘on’ or ‘off’ ‘on’ Display actions with different colors
look_nicklist boolean ‘on’ or ‘off’ ‘on’ Display nicklist window (for channel windows)
look_nicklist_position string ‘left’, ‘right’, ‘top’, ‘bottom’ ‘right’ Nicklist position (top, left, right (default), bottom)
look_nicklist_min_size integer between 0 and 100 0 Min size for nicklist (width or height, depending on look_nicklist_position (0 = no min size))
look_nicklist_max_size integer between 0 and 100 0 Max size for nicklist (width or height, depending on look_nicklist_position (0 = no max size; if min = max and > 0, then size is fixed))
look_nicklist_separator boolean ‘on’ or ‘off’ ‘on’ Separator between chat and nicklist
look_no_nickname string any string ‘-cmd-’ Text to display instead of nick when not connected
look_nickmode boolean ‘on’ or ‘off’ ‘on’ Display nick mode ((half)op/voice) before each nick
look_nickmode_empty boolean ‘on’ or ‘off’ ‘off’ Display space if nick mode is not (half)op/voice
look_nick_prefix string any string ” Text to display before nick in chat window
look_nick_suffix string any string ‘ |’ Text to display after nick in chat window
look_align_nick string ‘none’, ‘left’, ‘right’ ‘right’ Nick alignment (fixed size for nicks in chat window (none, left, right))
look_align_other boolean ‘on’ or ‘off’ ‘on’ Alignment for other messages (not beginning with a nick)
look_align_size integer between 8 and 64 14 Size for aligning nick and other messages
look_align_size_max integer between 8 and 64 20 Max size for aligning nick and other messages (should be >= to look_align_size)
look_align_text_offset integer between -1 and 64 -1 Offset for aligning lines of messages (except first lines), default is -1 (align after nick), a null or positive value is offset after beginning of line
look_nick_completor string any string ‘:’ The string inserted after nick completion
look_nick_completion_ignore string any string ‘[]-^’ Chars ignored for nick completion
look_nick_completion_smart boolean ‘on’ or ‘off’ ‘on’ Smart completion for nicks (completes with last speakers first)
look_nick_complete_first boolean ‘on’ or ‘off’ ‘off’ Complete only with first nick found
look_infobar boolean ‘on’ or ‘off’ ‘on’ Enable info bar
look_infobar_timestamp string any string ‘%B, %A %d %Y’ Timestamp for time in infobar
look_infobar_seconds boolean ‘on’ or ‘off’ ‘on’ Display seconds in infobar time
look_infobar_delay_highlight integer between 0 and 2147483647 7 Delay (in seconds) for highlight messages in infobar (0 = disable highlight notifications in infobar)
look_hotlist_names_count integer between 0 and 32 3 Max number of names in hotlist (0 = no name displayed, only buffer numbers)
look_hotlist_names_level integer between 1 and 15 12 Level for displaying names in hotlist (combination of: 1=join/part, 2=message, 4=private, 8=highlight, for example: 12=private+highlight)
look_hotlist_names_length integer between 0 and 32 0 Max length of names in hotlist (0 = no limit)
look_hotlist_sort string ‘group_time_asc’, ‘group_time_desc’, ‘group_number_asc’, ‘group_number_desc’, ‘number_asc’, ‘number_desc’ ‘group_time_asc’ Hotlist sort type (group_time_asc (default), group_time_desc, group_number_asc, group_number_desc, number_asc, number_desc)
look_day_change boolean ‘on’ or ‘off’ ‘on’ Display special message when day changes
look_day_change_timestamp string any string ‘%a, %d %b %Y’ Timestamp for date displayed when day changed
look_read_marker char any char ‘ ‘ Use a marker on servers/channels to show first unread line
look_input_format string any string ‘[%n(%m)] ‘ Format for input prompt (‘%c’ is replaced by channel or server, ‘%n’ by nick and ‘%m’ by nick modes)
look_paste_max_lines integer between 0 and 2147483647 3 Max number of lines for paste without asking user (0 = disable this feature)
col_real_white boolean ‘on’ or ‘off’ ‘off’ If set, uses real white color, disabled by default for terms with white background (if you never use white background, you should turn on this option to see real white instead of default term foreground color)
col_separator color Curses or Gtk color ‘blue’ Color for window separators (when splited)
col_title color Curses or Gtk color ‘default’ Color for title bar
col_title_more color Curses or Gtk color ‘lightmagenta’ Color for ‘+’ when scrolling topic
col_title_bg color Curses or Gtk color ‘blue’ Background for title bar
col_chat color Curses or Gtk color ‘default’ Color for chat text
col_chat_time color Curses or Gtk color ‘default’ Color for time in chat window
col_chat_time_sep color Curses or Gtk color ‘brown’ Color for time separator (chat window)
col_chat_prefix1 color Curses or Gtk color ‘lightcyan’ Color for 1st and 3rd char of prefix
col_chat_prefix2 color Curses or Gtk color ‘white’ Color for middle char of prefix
col_chat_server color Curses or Gtk color ‘brown’ Color for server name
col_chat_join color Curses or Gtk color ‘lightgreen’ Color for join arrow (prefix)
col_chat_part color Curses or Gtk color ‘lightred’ Color for part/quit arrow (prefix)
col_chat_nick color Curses or Gtk color ‘lightcyan’ Color for nicks in actions (chat window)
col_chat_host color Curses or Gtk color ‘cyan’ Color for hostnames (chat window)
col_chat_channel color Curses or Gtk color ‘white’ Color for channel names in actions (chat window)
col_chat_dark color Curses or Gtk color ‘green’ Color for dark separators (chat window)
col_chat_highlight color Curses or Gtk color ‘yellow’ Color for highlighted nick (chat window)
col_chat_bg color Curses or Gtk color ‘default’ Background for chat window
col_chat_read_marker color Curses or Gtk color ‘yellow’ Color for unread data marker
col_chat_read_marker_bg color Curses or Gtk color ‘magenta’ Background for unread data marker
col_status color Curses or Gtk color ‘default’ Color for status bar
col_status_delimiters color Curses or Gtk color ‘cyan’ Color for status bar delimiters
col_status_channel color Curses or Gtk color ‘white’ Color for current channel in status bar
col_status_data_msg color Curses or Gtk color ‘yellow’ Color for window with new messages (status bar)
col_status_private color Curses or Gtk color ‘lightmagenta’ Color for window with private message (status bar)
col_status_highlight color Curses or Gtk color ‘lightred’ Color for window with highlight (status bar)
col_status_data_other color Curses or Gtk color ‘default’ Color for window with new data (not messages) (status bar)
col_status_more color Curses or Gtk color ‘white’ Color for window with new data (status bar)
col_status_bg color Curses or Gtk color ‘blue’ Background for status window
col_infobar color Curses or Gtk color ‘black’ Color for info bar text
col_infobar_delimiters color Curses or Gtk color ‘blue’ Color for infobar delimiters
col_infobar_highlight color Curses or Gtk color ‘white’ Color for info bar highlight notification
col_infobar_bg color Curses or Gtk color ‘cyan’ Background for info bar window
col_input color Curses or Gtk color ‘default’ Color for input text
col_input_server color Curses or Gtk color ‘brown’ Color for input text (server name)
col_input_channel color Curses or Gtk color ‘white’ Color for input text (channel name)
col_input_nick color Curses or Gtk color ‘lightcyan’ Color for input text (nick name)
col_input_delimiters color Curses or Gtk color ‘cyan’ Color for input text (delimiters)
col_input_text_not_found color Curses or Gtk color ‘red’ Color for text not found
col_input_actions color Curses or Gtk color ‘lightgreen’ Color for actions in input window
col_input_bg color Curses or Gtk color ‘default’ Background for input window
col_nick color Curses or Gtk color ‘default’ Color for nicknames
col_nick_away color Curses or Gtk color ‘cyan’ Color for away nicknames
col_nick_chanowner color Curses or Gtk color ‘lightgreen’ Color for chan owner symbol (specific to unrealircd)
col_nick_chanadmin color Curses or Gtk color ‘lightgreen’ Color for chan admin symbol (specific to unrealircd)
col_nick_op color Curses or Gtk color ‘lightgreen’ Color for operator symbol
col_nick_halfop color Curses or Gtk color ‘lightmagenta’ Color for half-operator symbol
col_nick_voice color Curses or Gtk color ‘yellow’ Color for voice symbol
col_nick_user color Curses or Gtk color ‘blue’ Color for user symbol
col_nick_more color Curses or Gtk color ‘lightmagenta’ Color for ‘+’ when scrolling nicks
col_nick_sep color Curses or Gtk color ‘blue’ Color for nick separator
col_nick_self color Curses or Gtk color ‘white’ Color for local nick
col_nick_color1 color Curses or Gtk color ‘cyan’ Color for nick
col_nick_color2 color Curses or Gtk color ‘magenta’ Color for nick
col_nick_color3 color Curses or Gtk color ‘green’ Color for nick
col_nick_color4 color Curses or Gtk color ‘brown’ Color for nick
col_nick_color5 color Curses or Gtk color ‘lightblue’ Color for nick
col_nick_color6 color Curses or Gtk color ‘default’ Color for nick
col_nick_color7 color Curses or Gtk color ‘lightcyan’ Color for nick
col_nick_color8 color Curses or Gtk color ‘lightmagenta’ Color for nick
col_nick_color9 color Curses or Gtk color ‘lightgreen’ Color for nick
col_nick_color10 color Curses or Gtk color ‘blue’ Color for nick
col_nick_private color Curses or Gtk color ‘default’ Color for other nick in private window
col_nick_bg color Curses or Gtk color ‘default’ Background for nicknames
col_chat_dcc_selected color Curses or Gtk color ‘white’ Color for selected DCC (chat window)
col_dcc_waiting color Curses or Gtk color ‘lightcyan’ Color for “waiting” dcc status
col_dcc_connecting color Curses or Gtk color ‘yellow’ Color for “connecting” dcc status
col_dcc_active color Curses or Gtk color ‘lightblue’ Color for “active” dcc status
col_dcc_done color Curses or Gtk color ‘lightgreen’ Color for “done” dcc status
col_dcc_failed color Curses or Gtk color ‘lightred’ Color for “failed” dcc status
col_dcc_aborted color Curses or Gtk color ‘lightred’ Color for “aborted” dcc status
history_max_lines integer between 0 and 2147483647 4096 Maximum number of lines in history for one server/channel/private window (0 = unlimited)
history_max_commands integer between 0 and 2147483647 100 Maximum number of user commands in history (0 = unlimited)
history_display_default integer between 0 and 2147483647 5 Maximum number of commands to display by default in history listing (0 = unlimited)
log_auto_server boolean ‘on’ or ‘off’ ‘off’ Automatically log server messages
log_auto_channel boolean ‘on’ or ‘off’ ‘off’ Automatically log channel chats
log_auto_private boolean ‘on’ or ‘off’ ‘off’ Automatically log private chats
log_plugin_msg boolean ‘on’ or ‘off’ ‘off’ Log messages from plugins (scripts)
log_path string any string ‘%h/logs/’ Path for WeeChat log files (‘%h’ will be replaced by WeeChat home, ~/.weechat by default)
log_timestamp string any string ‘%Y %b %d %H:%M:%S’ Timestamp for log (see man strftime for date/time specifiers)
log_hide_nickserv_pwd boolean ‘on’ or ‘off’ ‘on’ Hide password displayed by nickserv
irc_display_away string ‘off’, ‘local’, ‘channel’ ‘off’ Display message when (un)marking as away
irc_show_away_once boolean ‘on’ or ‘off’ ‘on’ Show remote away message only once in private
irc_default_msg_part string any string ‘WeeChat %v’ Default part message (leaving channel) (‘%v’ will be replaced by WeeChat version in string)
irc_default_msg_quit string any string ‘WeeChat %v’ Default quit message (‘%v’ will be replaced by WeeChat version in string)
irc_notice_as_pv boolean ‘on’ or ‘off’ ‘off’ Display notices as private messages
irc_away_check integer between 0 and 2147483647 0 Interval between two checks for away (in minutes, 0 = never check)
irc_away_check_max_nicks integer between 0 and 2147483647 0 Do not check away nicks on channels with high number of nicks (0 = unlimited)
irc_lag_check integer between 30 and 2147483647 60 Interval between two checks for lag (in seconds)
irc_lag_min_show integer between 0 and 2147483647 1 Minimum lag to show (in seconds)
irc_lag_disconnect integer between 0 and 2147483647 5 Disconnect after important lag (in minutes, 0 = never disconnect)
irc_anti_flood integer between 0 and 5 2 Anti-flood: # seconds between two user messages (0 = no anti-flood)
irc_fifo_pipe boolean ‘on’ or ‘off’ ‘off’ Create a FIFO pipe for remote control
irc_highlight string any string ” Comma separated list of words to highlight (case insensitive comparison, words may begin or end with “*” for partial match)
irc_colors_receive boolean ‘on’ or ‘off’ ‘on’ When off, colors codes are ignored in incoming messages
irc_colors_send boolean ‘on’ or ‘off’ ‘on’ Allow user to send colors with special codes (^Cb=bold, ^Ccxx=color, ^Ccxx,yy=color+background, ^Cu=underline, ^Cr=reverse)
irc_send_unknown_commands boolean ‘on’ or ‘off’ ‘off’ Send unknown commands to IRC server
dcc_auto_accept_files boolean ‘on’ or ‘off’ ‘off’ Automatically accept incoming dcc files
dcc_auto_accept_chats boolean ‘on’ or ‘off’ ‘off’ Automatically accept dcc chats (use carefully!)
dcc_timeout integer between 5 and 2147483647 300 Timeout for dcc request (in seconds)
dcc_blocksize integer between 1024 and 102400 65536 Block size for dcc packets in bytes (default: 65536)
dcc_fast_send boolean ‘on’ or ‘off’ ‘on’ Does not wait for ACK when sending file
dcc_port_range string any string ” Restricts outgoing dcc to use only ports in the given range (useful for NAT) (syntax: a single port, ie. 5000 or a port range, ie. 5000-5015, empty value means any port)
dcc_own_ip string any string ” IP or DNS address used for outgoing dcc (if empty, local interface IP is used)
dcc_download_path string any string ‘%h/dcc’ Path for writing incoming files with dcc (default: user home)
dcc_upload_path string any string ‘~’ Path for reading files when sending thru dcc (when no path is specified)
dcc_convert_spaces boolean ‘on’ or ‘off’ ‘on’ Convert spaces to underscores when sending files
dcc_auto_rename boolean ‘on’ or ‘off’ ‘on’ Rename incoming files if already exists (add ‘.1′, ‘.2′, …)
dcc_auto_resume boolean ‘on’ or ‘off’ ‘on’ Automatically resume dcc transfer if connection with remote host is loosed
proxy_use boolean ‘on’ or ‘off’ ‘off’ Use a proxy server to connect to irc server
proxy_type string ‘http’, ‘socks4′, ‘socks5′ ‘http’ Proxy type (http (default), socks4, socks5)
proxy_ipv6 boolean ‘on’ or ‘off’ ‘off’ Connect to proxy in ipv6
proxy_address string any string ” Proxy server address (IP or hostname)
proxy_port integer between 0 and 65535 3128 Port for connecting to proxy server
proxy_username string any string ” Username for proxy server
proxy_password string any string ” Password for proxy server
plugins_path string any string ‘%h/plugins’ Path for searching plugins (‘%h’ will be replaced by WeeChat home, ~/.weechat by default)
plugins_autoload string any string ‘*’ Comma separated list of plugins to load automatically at startup, “*” means all plugins found (names may be partial, for example “perl” is ok for “libperl.so”)
plugins_extension string any string ‘.so’ Standard plugins extension in filename, used for autoload (if empty, then all files are loaded when autoload is “*”)
server_name string any string ” Name associated to IRC server (for display only)
server_autoconnect boolean ‘on’ or ‘off’ ‘on’ Automatically connect to server when WeeChat is starting
server_autoreconnect boolean ‘on’ or ‘off’ ‘on’ Automatically reconnect to server when disconnected
server_autoreconnect_delay integer between 0 and 65535 30 Delay (in seconds) before trying again to reconnect to server
server_address string any string ” IP address or hostname of IRC server
server_port integer between 0 and 65535 6667 Port for connecting to server
server_ipv6 boolean ‘on’ or ‘off’ ‘off’ Use IPv6 protocol for server communication
server_ssl boolean ‘on’ or ‘off’ ‘off’ Use SSL for server communication
server_password string any string ” Password for IRC server
server_nick1 string any string ” Nickname to use on IRC server
server_nick2 string any string ” Alternate nickname to use on IRC server (if nickname is already used)
server_nick3 string any string ” 2nd alternate nickname to use on IRC server (if alternate nickname is already used)
server_username string any string ” User name to use on IRC server
server_realname string any string ” Real name to use on IRC server
server_hostname string any string ” Custom hostname/IP for server (optional, if empty local hostname is used)
server_command string any string ” Command(s) to run when connected to server (many commands should be separated by ‘;’, use ‘;’ for a semicolon, special variables $nick, $channel and $server are replaced by their value)
server_command_delay integer between 0 and 3600 0 Delay (in seconds) after command was executed (example: give some time for authentication)
server_autojoin string any string ” Comma separated list of channels to join when connected to server (example: “#chan1,#chan2,#chan3 key1,key2″)
server_autorejoin boolean ‘on’ or ‘off’ ‘on’ Automatically rejoin channels when kicked
server_notify_levels string any string ” Comma separated list of notify levels for channels of this server (format: #channel:1,..), a channel name ‘*’ is reserved for server default notify level
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 unloadnfreenode */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 ~/.weechat/weechat_fifo_*
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”
Chapter 4. Plugins
Table of Contents
Plugins in WeeChat
Write a plugin
API functions
Compile plugin
Load plugin into WeeChat
Plugin example
Charset plugin
Settings
FAQ
Scripts plugins
Load / unload scripts
Syntax by language
WeeChat / scripts API
This chapter describes WeeChat plugins interface (API) and the default scripts plugins (Perl, Python, Ruby, Lua), 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
API functions
Compile plugin
Load plugin into WeeChat
Plugin example
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
set_charset
iconv_to_internal
iconv_from_internal
ascii_strcasecmp
ascii_strncasecmp
explode_string
free_exploded_string
mkdir_home
exec_on_files
print
print_server
print_infobar
infobar_remove
log
msg_handler_add
cmd_handler_add
timer_handler_add
keyboard_handler_add
event_handler_add
handler_remove
handler_remove_all
modifier_add
modifier_remove
modifier_remove_all
exec_command
get_info
get_dcc_info
free_dcc_info
get_server_info
free_server_info
get_channel_info
free_channel_info
get_nick_info
free_nick_info
get_config
set_config
get_plugin_config
set_plugin_config
get_irc_color
input_color
get_window_info
free_window_info
get_buffer_info
free_buffer_info
get_buffer_data
free_buffer_data
set_charset
Prototype: void set_charset (t_weechat_plugin *plugin, char *charset)
Set new plugin charset.
Arguments:
*
plugin: pointer to plugin structure
*
charset: new charset to use
Example:
plugin->set_charset (plugin, “ISO-8859-1″);
iconv_to_internal
Prototype: void iconv_to_internal (t_weechat_plugin *plugin, char *charset, char *string)
Convert string to WeeChat internal charset (UTF-8).
Arguments:
*
plugin: pointer to plugin structure
*
charset: charset to convert
*
string: string to convert
Return value: converted string.
Note: result has to be free by a call to “free” after use.
Example:
char *str = plugin->iconv_to_internal (plugin, “ISO-8859-1″, “iso string: é à”);
iconv_from_internal
Prototype: void iconv_from_internal (t_weechat_plugin *plugin, char *charset, char *string)
Convert string from internal WeeChat charset (UTF-8) to another.
Arguments:
*
plugin: pointer to plugin structure
*
charset: target charset
*
string: string to convert
Return value: converted string.
Note: result has to be free by a call to “free” after use.
Example:
char *str = plugin->iconv_from_internal (plugin, “ISO-8859-1″, “utf-8 string: é à”);
ascii_strcasecmp
Prototype: int ascii_strcasecmp (t_weechat_plugin *plugin, char *string1, char *string2)
Locale and case independent string comparison.
Arguments:
*
plugin: pointer to plugin structure
*
string1: first string for comparison
*
string2: second string for comparison
Return value: difference between two strings: negative 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:
*
plugin: pointer to plugin struct
*
string1: first string for comparison
*
string2: second string for comparison
*
max: max number of chars for comparison
Return value: difference between two strings: negative 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:
*
plugin: pointer to plugin struct
*
string: string to explode
*
separators: delimiters used for explosion
*
num_items_max: maximum number of items created (0 = no limit)
*
num_items: 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:
*
plugin: pointer to plugin structure
*
string: 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);
mkdir_home
Prototype: int mkdir_home (t_weechat_plugin *plugin, char *directory)
Create a directory in WeeChat home.
Arguments:
*
plugin: pointer to plugin structure
*
directory: directory to create
Return value: 1 if directory was successfully created, 0 if an error occurred.
Example:
if (!plugin->mkdir_home (plugin, “temp”))
plugin->print_server(plugin, “Failed to create ‘temp’ directory in WeeChat home.”);
exec_on_files
Prototype: void exec_on_files (t_weechat_plugin *plugin, char *directory, int (*callback)(t_weechat_plugin *, char *))
Execute a function on all files of a directory.
Arguments:
*
plugin: pointer to plugin structure
*
directory: directory for searching files
*
callback: function called for each file found
Return value: none.
Example:
int callback (t_weechat_plugin *plugin, char *file)
{
plugin->print_server (plugin, “file: %s”, file);
return 1;
}
…
plugin->exec_on_files (plugin, “/tmp”, &callback);
print
Prototype: void print (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:
*
plugin: pointer to plugin structure
*
server: internal name of server to find buffer for message display (may be NULL)
*
channel: name of channel to find buffer for message display (may be NULL)
*
message: message
To display colored text, there are following codes:
Code Description
0×02 bold text
0×03 + “xx” text color “xx” (see the section called “get_irc_color” for colors)
0×03 + “xx,yy” text color “xx” and background “yy” (see the section called “get_irc_color” for colors)
0x0F disable color and attributes
0×12 reverse video (revert text color with background)
0x1F underlined text
Note: the same code (without number for 0×03) may be used to stop the attribute.
Return value: none.
Examples:
plugin->print (plugin, NULL, NULL, “hello”);
plugin->print (plugin, NULL, “#weechat”, “hello”);
plugin->print (plugin, “freenode”, “#weechat”, “hello”);
plugin->print (plugin, NULL, NULL,
“test: x02 bold x0Fx03%02d blue x03%02d green”,
plugin->get_irc_color (plugin, “blue”),
plugin->get_irc_color (plugin, “green”));
print_server
Prototype: void print_server (t_weechat_plugin *plugin, char *message, …)
Display a message on current server buffer.
Arguments:
*
plugin: pointer to plugin structure
*
message: message
To display colored text, see the section called “print”.
Return value: none.
Example:
plugin->print_server (plugin, “hello”);
print_infobar
Prototype: void print_infobar (t_weechat_plugin *plugin, int time, char *message, …)
Display a message in infobar for a specified time.
Arguments:
*
plugin: pointer to plugin structure
*
time: time (in seconds) for displaying message (0 = never erased)
Return value: none.
Example:
plugin->print_infobar (plugin, 5, “hello”);
infobar_remove
Prototype: void infobar_remove (t_weechat_plugin *plugin, int count)
Remove one or more messages in infobar stack.
Arguments:
*
plugin: pointer to plugin structure
*
count: number of messages to remove (if argument is infobar_remove (1);
log
Prototype: void log (t_weechat_plugin *plugin, char *server, char *channel, char *message, …)
Write a message in log file for a server or a channel.
Arguments:
*
plugin: pointer to plugin structure
*
server: internal name of server to find buffer for log (may be NULL)
*
channel: name of channel to find buffer for log (may be NULL)
*
message: message
Return value: none.
Example:
plugin->log (plugin, “freenode”, “#weechat”, “test”);
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:
*
plugin: pointer to plugin structure
*
message: name of IRC message (“*” for all messages). To know list of IRC messages, please consult RFCs 1459 and 2812. Moreover you can use a special name, prefixed by “weechat_” to catch special events, as written in table below:
Name Description
weechat_pv private message received
weechat_highlight message with highlight (on a channel or pv)
weechat_ctcp CTCP message received (VERSION, PING, ..)
weechat_dcc DCC message received (chat or file)
*
function: function called when message is received
It uses following prototype: int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer)
Argument argc is set to 3, following values are set in argv array:
o
argv[0] = server name
o
argv[1] = IRC message
o
argv[2] = command arguments
*
handler_args: arguments given to function when called
*
handler_pointer: 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
*
PLUGIN_RC_OK_WITH_HIGHLIGHT: function successfully completed and make “highlight” on received message
Example:
int msg_kick (t_weechat_plugin *plugin, int argc, char **argv,
char *handler_args, void *handler_pointer)
{
plugin->print (plugin, argv[0], NULL, “KICK received”);
return PLUGIN_RC_OK;
}
…
t_plugin_handler *msg_handler;
msg_handler = 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:
*
plugin: pointer to plugin structure
*
command: the new command name, which may be an existing command (be careful, replaced command will not be available until plugin is unloaded)
*
description: short command description (displayed by /help command)
*
arguments: short description of command arguments (displayed by /help command)
*
arguments_description: long description of command arguments (displayed by /help command)
*
completion_template: 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 or “-” disable completion for all command arguments.
Following codes can be used:
Code Description
%- no completion for argument
%* repeat last completion for all following arguments (this code has to be at the end of completion template, preceded by “|”)
%a alias
%A alias and commands (WeeChat, IRC and plugins)
%c current channel
%C all channels (including queries)
%f file name
%h plugins commands
%i IRC commands (sent)
%I IRC commands (received)
%k key functions
%m nick on current server
%M nicks on current server (on all open channels)
%n nicks of current channel
%N nicks and hostnames of current channel
%o setup options
%O plugin 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
%V plugin option value
%w WeeChat commands
*
function: function called when command is executed
It uses following prototype: int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer)
Argument argc is set to 3, following values are set in argc array:
o
argv[0] = server name
o
argv[1] = command
o
argv[2] = command arguments
*
handler_args: arguments given to function when called
*
handler_pointer: 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 successfully completed
Example:
int cmd_test (t_weechat_plugin *plugin, int argc, char **argv,
char *handler_args, void *handler_pointer)
{
plugin->print (plugin, argv[0], NULL,
“test command, nick: %s”,
(argv[2]) ? argv[2] : “none”);
return PLUGIN_RC_OK;
}
…
t_plugin_handler *cmd_handler;
cmd_handler = plugin->cmd_handler_add (plugin, “test”, “Test command”,
“[nick]“, “nick: nick of channel”,
“%n”, &cmd_test, NULL, NULL);
timer_handler_add
Prototype: t_plugin_handler *timer_handler_add (t_weechat_plugin *plugin, int interval, t_plugin_handler_func *function, char *handler_args, void *handler_pointer)
Add a timer handler which periodically calls a function.
Arguments:
*
plugin: pointer to plugin structure
*
interval: interval (in seconds) between two calls of function.
*
func
