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 <http://www.gnu.org/licenses/>.
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
Table of Contents
This chapter describes WeeChat and pre-requisites for its installation.
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
multi-platform (GNU/Linux, *BSD, MacOS X, Windows and other)
100% GPL, free software
WeeChat homepage is here: http://weechat.flashtux.org
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 ***
Table of Contents
This chapter explains how to install WeeChat.
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.
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
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”)
Table of Contents
This chapter explains how to run WeeChat, the default key bindings used, internal and IRC commands, setup file, and FIFO pipe use.
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 <path> |
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 | 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 |
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!
This chapter lists all WeeChat and IRC 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 <pct> 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
| 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 |
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
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 |
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 ~/.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"
Table of Contents
This chapter describes WeeChat plugins interface (API) and the default scripts plugins (Perl, Python, Ruby, Lua), provided with 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.
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 |
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");
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: é à");
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: é à");
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, zero if string1 == string2, positive if string1 > string2
Example:
if (plugin->ascii_strcasecmp (plugin, "abc", "def") != 0) ...
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, zero if string1 == string2, positive if string1 > string2
Example:
if (plugin->ascii_strncasecmp (plugin, "abc", "def", 2) != 0) ...
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);
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);
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.");
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);
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 |
|---|---|
| 0x02 | bold text |
| 0x03 + "xx" |
text color "xx"
(see the section called “get_irc_color” for colors)
|
| 0x03 + "xx,yy" |
text color "xx"
and background "yy"
(see the section called “get_irc_color” for colors)
|
| 0x0F | disable color and attributes |
| 0x12 | reverse video (revert text color with background) |
| 0x1F | underlined text |
Note: the same code (without number for 0x03) 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 \x0F\x03%02d blue \x03%02d green",
plugin->get_irc_color (plugin, "blue"),
plugin->get_irc_color (plugin, "green"));
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");
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");
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 <= 0, then all messages are removed)
Return value: none.
Example:
plugin->infobar_remove (1);
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");
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:
argv[0] = server name
argv[1] = IRC message
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