3506 lines
119 KiB
Plaintext
3506 lines
119 KiB
Plaintext
= WeeChat user's guide
|
|
:author: Sébastien Helleu
|
|
:email: flashcode@flashtux.org
|
|
:lang: en
|
|
:toc2:
|
|
:toclevels: 3
|
|
:max-width: 100%
|
|
|
|
|
|
This manual documents WeeChat chat client, it is part of WeeChat.
|
|
|
|
Latest version of this document can be found on this page:
|
|
https://weechat.org/doc
|
|
|
|
|
|
[[introduction]]
|
|
== Introduction
|
|
|
|
WeeChat (Wee Enhanced Environment for Chat) is a free chat client, fast and
|
|
light, designed for many operating systems.
|
|
|
|
[[features]]
|
|
=== Features
|
|
|
|
Main features are:
|
|
|
|
* multi-protocols: IRC and Jabber (with script jabber.py or bitlbee/minbif)
|
|
* multi-servers connection (with SSL, IPv6, proxy)
|
|
* small, fast and light
|
|
* customizable and extensible with plugins and scripts
|
|
* compliant with IRC RFCs http://tools.ietf.org/html/rfc1459[1459],
|
|
http://tools.ietf.org/html/rfc2810[2810],
|
|
http://tools.ietf.org/html/rfc2811[2811],
|
|
http://tools.ietf.org/html/rfc2812[2812] and
|
|
http://tools.ietf.org/html/rfc2813[2813]
|
|
* IRC proxy and relay for remote interfaces
|
|
* multi-platform (GNU/Linux, *BSD, MacOS X, Windows and other)
|
|
* 100% GPL, free software
|
|
|
|
WeeChat homepage is here: https://weechat.org/
|
|
|
|
[[prerequisites]]
|
|
=== Prerequisites
|
|
|
|
In order to install WeeChat, you need:
|
|
|
|
* a running GNU/Linux system (with compiler tools for source
|
|
package), or a compatible OS
|
|
* 'root' privileges (to install WeeChat in a system directory)
|
|
* some libraries (see <<dependencies,dependencies>>).
|
|
|
|
[[install]]
|
|
== Installation
|
|
|
|
[[binary_packages]]
|
|
=== Binary packages
|
|
|
|
Binary packages are available for many distributions, including:
|
|
|
|
* Debian (or any Debian compatible distribution):
|
|
`apt-get install weechat-curses`
|
|
* Mandriva/RedHat (or any RPM compatible distribution):
|
|
`rpm -i /path/to/weechat-x.y.z-1.i386.rpm`
|
|
* Gentoo: `emerge weechat`
|
|
* Arch Linux: `pacman -S weechat`
|
|
* Fedora Core: `yum install weechat`
|
|
* Sourcemage: `cast weechat`
|
|
|
|
Some additional packages may be useful, like weechat-plugins.
|
|
|
|
For other distributions, please look at your manual for installation
|
|
instructions.
|
|
|
|
[[source_package]]
|
|
=== Source package
|
|
|
|
WeeChat can be compiled with cmake or autotools (cmake is recommended way).
|
|
|
|
[NOTE]
|
|
On OS X, you can use http://brew.sh/[Homebrew]:
|
|
`brew install weechat --with-python --with-perl`
|
|
(for help: `brew info weechat`).
|
|
|
|
[[dependencies]]
|
|
==== Dependencies
|
|
|
|
Following table shows list of packages that are required or optional to
|
|
compile WeeChat.
|
|
|
|
[width="100%",cols="5,^3,^3,.^13",options="header"]
|
|
|===
|
|
| Package ^(1)^ | Version | Required | Feature
|
|
|
|
| cmake | | *yes* |
|
|
Build (autotools still possible, but cmake is recommended)
|
|
|
|
| pkg-config | | *yes* |
|
|
Detect installed libraries
|
|
|
|
| libncursesw5-dev ^(2)^ | | *yes* |
|
|
Ncurses interface
|
|
|
|
| libcurl4-gnutls-dev | | *yes* |
|
|
URL transfer
|
|
|
|
| zlib1g-dev | | *yes* |
|
|
Compression of packets in relay plugin (weechat protocol), script plugin
|
|
|
|
| libgcrypt20-dev | | *yes* |
|
|
Secured data, IRC SASL authentication (DH-BLOWFISH/DH-AES), script plugin
|
|
|
|
| libgnutls28-dev | ≥ 2.2.0 ^(3)^ | |
|
|
SSL connection to IRC server, support of SSL in relay plugin,
|
|
IRC SASL authentication (ECDSA-NIST256P-CHALLENGE)
|
|
|
|
| gettext | | |
|
|
Internationalization (translation of messages; base language is English)
|
|
|
|
| ca-certificates | | |
|
|
Certificates for SSL connections
|
|
|
|
| libaspell-dev or libenchant-dev | | |
|
|
Aspell plugin
|
|
|
|
| python-dev | ≥ 2.5 ^(4)^ | |
|
|
Python plugin
|
|
|
|
| libperl-dev | | |
|
|
Perl plugin
|
|
|
|
| ruby2.1-dev | ≥ 1.8 | |
|
|
Ruby plugin
|
|
|
|
| liblua5.2-dev | | |
|
|
Lua plugin
|
|
|
|
| tcl-dev | ≥ 8.5 | |
|
|
Tcl plugin
|
|
|
|
| guile-2.0-dev | ≥ 2.0 | |
|
|
Guile (scheme) plugin
|
|
|
|
| libv8-dev | ≤ 3.24.3 | |
|
|
Javascript plugin
|
|
|
|
| asciidoc | ≥ 8.5.0 | |
|
|
Build man page and documentation
|
|
|
|
| source-highlight | | |
|
|
Syntax highlight for sources in documentation
|
|
|
|
| xsltproc, docbook-xml, docbook-xsl | | |
|
|
Build of man page
|
|
|
|
| libcpputest-dev | ≥ 3.4 | |
|
|
Run tests
|
|
|
|
| C++ compiler | | |
|
|
Run tests, javascript plugin
|
|
|===
|
|
|
|
[NOTE]
|
|
^(1)^ Name comes from the Debian GNU/Linux distribution, versions and package
|
|
names may be different in different distributions and versions. +
|
|
^(2)^ WeeChat can compile with libncurses5-dev, but it is *NOT* recommended (you
|
|
will have display bugs with wide chars). +
|
|
^(3)^ Gnutls ≥ 3.0.21 is required for IRC SASL authentication with mechanism
|
|
ECDSA-NIST256P-CHALLENGE. +
|
|
^(4)^ Recommended Python version is 2.7 (all scripts run fine with version 2.7,
|
|
but not with versions ≤ 2.6 or ≥ 3.0).
|
|
|
|
[[compile_with_cmake]]
|
|
==== Compile with cmake
|
|
|
|
* Installation in system directories (requires 'root' privileges):
|
|
|
|
----
|
|
$ mkdir build
|
|
$ cd build
|
|
$ cmake ..
|
|
$ make
|
|
% make install (as root)
|
|
----
|
|
|
|
* Installation in custom directory:
|
|
|
|
----
|
|
$ mkdir build
|
|
$ cd build
|
|
$ cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/directory
|
|
$ make
|
|
$ make install
|
|
----
|
|
|
|
Options can be used for cmake, with format: "-DOPTION=VALUE".
|
|
|
|
List of commonly used options:
|
|
|
|
[width="100%",cols="2m,2,5m,12",options="header"]
|
|
|===
|
|
| Option | Values | Default value | Description
|
|
|
|
| CMAKE_BUILD_TYPE | `Debug`, `Release`, `RelWithDebInfo`, `MinSizeRel` | |
|
|
The type of build: `Debug` (or `RelWithDebInfo`) is recommended if you are
|
|
running development version of WeeChat.
|
|
|
|
| CMAKE_INSTALL_PREFIX | directory | /usr/local |
|
|
The directory where WeeChat will be installed.
|
|
|
|
| WEECHAT_HOME | directory | ~/.weechat |
|
|
The default home directory when running WeeChat.
|
|
|
|
| CA_FILE | file | /etc/ssl/certs/ca-certificates.crt |
|
|
File containing the certificate authorities.
|
|
This is the default value of option
|
|
<<option_weechat.network.gnutls_ca_file,weechat.network.gnutls_ca_file>>.
|
|
|
|
| ENABLE_ALIAS | `ON`, `OFF` | ON |
|
|
Compile <<alias_plugin,Alias plugin>>.
|
|
|
|
| ENABLE_ASPELL | `ON`, `OFF` | ON |
|
|
Compile <<aspell_plugin,Aspell plugin>>.
|
|
|
|
| ENABLE_CHARSET | `ON`, `OFF` | ON |
|
|
Compile <<charset_plugin,Charset plugin>>.
|
|
|
|
| ENABLE_MAN | `ON`, `OFF` | OFF |
|
|
Compile man page.
|
|
|
|
| ENABLE_DOC | `ON`, `OFF` | OFF |
|
|
Compile documentation (it takes a long time, recommended only if you build
|
|
a binary package embedding documentation or if you can't browse documentation
|
|
online).
|
|
|
|
| ENABLE_ENCHANT | `ON`, `OFF` | OFF |
|
|
Compile <<aspell_plugin,Aspell plugin>> with Enchant.
|
|
|
|
| ENABLE_EXEC | `ON`, `OFF` | ON |
|
|
Compile <<exec_plugin,Exec plugin>>.
|
|
|
|
| ENABLE_FIFO | `ON`, `OFF` | ON |
|
|
Compile <<fifo_plugin,Fifo plugin>>.
|
|
|
|
| ENABLE_GNUTLS | `ON`, `OFF` | ON |
|
|
Enable Gnutls (for SSL).
|
|
|
|
| ENABLE_GUILE | `ON`, `OFF` | ON |
|
|
Compile <<scripts_plugins,Guile plugin>> (Scheme).
|
|
|
|
| ENABLE_IRC | `ON`, `OFF` | ON |
|
|
Compile <<irc_plugin,IRC plugin>>.
|
|
|
|
| ENABLE_JAVASCRIPT | `ON`, `OFF` | ON |
|
|
Compile <<scripts_plugins,Javascript plugin>>.
|
|
|
|
| ENABLE_LARGEFILE | `ON`, `OFF` | ON |
|
|
Support of large files.
|
|
|
|
| ENABLE_LOGGER | `ON`, `OFF` | ON |
|
|
Compile <<logger_plugin,Logger plugin>>.
|
|
|
|
| ENABLE_LUA | `ON`, `OFF` | ON |
|
|
Compile <<scripts_plugins,Lua plugin>>.
|
|
|
|
| ENABLE_NCURSES | `ON`, `OFF` | ON |
|
|
Compile Ncurses interface.
|
|
|
|
| ENABLE_NLS | `ON`, `OFF` | ON |
|
|
Enable NLS (translations).
|
|
|
|
| ENABLE_PERL | `ON`, `OFF` | ON |
|
|
Compile <<scripts_plugins,Perl plugin>>.
|
|
|
|
| ENABLE_PYTHON | `ON`, `OFF` | ON |
|
|
Compile <<scripts_plugins,Python plugin>>.
|
|
|
|
| ENABLE_PYTHON3 | `ON`, `OFF` | OFF |
|
|
Compile <<scripts_plugins,Python plugin>> using Python 3 (*NOT* recommended
|
|
because many scripts are not compatible with Python 3).
|
|
|
|
| ENABLE_RELAY | `ON`, `OFF` | ON |
|
|
Compile <<relay_plugin,Relay plugin>>.
|
|
|
|
| ENABLE_RUBY | `ON`, `OFF` | ON |
|
|
Compile <<scripts_plugins,Ruby plugin>>.
|
|
|
|
| ENABLE_SCRIPT | `ON`, `OFF` | ON |
|
|
Compile <<scripts_plugins,Script plugin>>.
|
|
|
|
| ENABLE_SCRIPTS | `ON`, `OFF` | ON |
|
|
Compile <<scripts_plugins,script plugins>> (Python, Perl, Ruby, Lua, Tcl,
|
|
Guile, Javascript).
|
|
|
|
| ENABLE_TCL | `ON`, `OFF` | ON |
|
|
Compile <<scripts_plugins,Tcl plugin>>.
|
|
|
|
| ENABLE_TRIGGER | `ON`, `OFF` | ON |
|
|
Compile <<trigger_plugin,Trigger plugin>>.
|
|
|
|
| ENABLE_XFER | `ON`, `OFF` | ON |
|
|
Compile <<xfer_plugin,Xfer plugin>>.
|
|
|
|
| ENABLE_TESTS | `ON`, `OFF` | OFF |
|
|
Compile tests.
|
|
|===
|
|
|
|
The other options can be displayed with this command:
|
|
|
|
----
|
|
$ cmake -LA
|
|
----
|
|
|
|
Or with Curses interface:
|
|
|
|
----
|
|
$ ccmake ..
|
|
----
|
|
|
|
[[compile_with_autotools]]
|
|
==== Compile with autotools
|
|
|
|
[WARNING]
|
|
Only cmake is officially supported to build WeeChat. You should use autotools
|
|
only if you are not able to use cmake. +
|
|
Build with autotools requires more dependencies and is slower than with cmake.
|
|
|
|
* Installation in system directories (requires 'root' privileges):
|
|
|
|
----
|
|
$ ./autogen.sh
|
|
$ mkdir build
|
|
$ cd build
|
|
$ ../configure
|
|
$ make
|
|
% make install (as root)
|
|
----
|
|
|
|
* Installation in custom directory:
|
|
|
|
----
|
|
$ ./autogen.sh
|
|
$ mkdir build
|
|
$ cd build
|
|
$ ../configure --prefix=/path/to/directory
|
|
$ make
|
|
$ make install
|
|
----
|
|
|
|
Options can be used for 'configure' script, they can be displayed with this
|
|
command:
|
|
|
|
----
|
|
$ ./configure --help
|
|
----
|
|
|
|
[[git_sources]]
|
|
=== Git sources
|
|
|
|
Warning: git sources are for advanced users: it may not compile or not be
|
|
stable. You're warned!
|
|
|
|
To get git sources, issue this command:
|
|
|
|
----
|
|
$ git clone https://github.com/weechat/weechat.git
|
|
----
|
|
|
|
Then follow instructions for source package (see
|
|
<<source_package,source package>>).
|
|
|
|
[[report_crashes]]
|
|
=== Report crashes
|
|
|
|
If you experienced crashes, or if you want to report any future WeeChat crash,
|
|
you have to:
|
|
|
|
* compile it with debug info (or install binary package with debug info)
|
|
* enable 'core' files on your system
|
|
* install gdb
|
|
|
|
[[debug_info]]
|
|
==== Debug info
|
|
|
|
If you're compiling with cmake:
|
|
|
|
----
|
|
$ cmake .. -DCMAKE_BUILD_TYPE=Debug
|
|
----
|
|
|
|
If you're compiling with autotools, debug is default (`--with-debug=1`).
|
|
|
|
If you installed a binary package, then install package 'weechat-dbg'.
|
|
|
|
[[core_files]]
|
|
==== Core files
|
|
|
|
To enable 'core' files, you can use option
|
|
<<option_weechat.startup.sys_rlimit,weechat.startup.sys_rlimit>>:
|
|
|
|
----
|
|
/set weechat.startup.sys_rlimit "core:-1"
|
|
----
|
|
|
|
For WeeChat ≤ 0.3.8 or if you want to enable core files even before WeeChat
|
|
starts, you can use `ulimit` command.
|
|
|
|
For example under Linux with 'bash' shell, add this line to your `~/.bashrc`:
|
|
|
|
----
|
|
ulimit -c unlimited
|
|
----
|
|
|
|
Or max size:
|
|
|
|
----
|
|
ulimit -c 200000
|
|
----
|
|
|
|
[[gdb_backtrace]]
|
|
==== Get backtrace with gdb
|
|
|
|
When WeeChat crashes, your system will create a file 'core' or 'core.12345'
|
|
('12345' is process id).
|
|
This file is created in directory where you have run WeeChat (this is *not*
|
|
directory where WeeChat is installed!).
|
|
|
|
For example if 'weechat' is installed in '/usr/bin/' and 'core' file is
|
|
in '/home/xxx/', then run gdb with this command:
|
|
|
|
----
|
|
gdb /usr/bin/weechat /home/xxx/core
|
|
----
|
|
|
|
Then under gdb, use command `bt full` to display backtrace.
|
|
You will see something like that:
|
|
|
|
----
|
|
(gdb) set logging file /tmp/crash.txt
|
|
(gdb) set logging on
|
|
Copying output to /tmp/crash.txt.
|
|
(gdb) bt full
|
|
#0 0x00007f9dfb04a465 in raise () from /lib/libc.so.6
|
|
#1 0x00007f9dfb04b8e6 in abort () from /lib/libc.so.6
|
|
#2 0x0000000000437f66 in weechat_shutdown (return_code=1, crash=1)
|
|
at /some_path/src/core/weechat.c:351
|
|
#3 <signal handler called>
|
|
#4 0x000000000044cb24 in hook_process_timer_cb (arg_hook_process=0x254eb90,
|
|
remaining_calls=<value optimized out>) at /some_path/src/core/wee-hook.c:1364
|
|
hook_process = 0x254eb90
|
|
status = <value optimized out>
|
|
#5 0x000000000044cc7d in hook_timer_exec ()
|
|
at /some_path/src/core/wee-hook.c:1025
|
|
tv_time = {tv_sec = 1272693881, tv_usec = 212665}
|
|
ptr_hook = 0x2811f40
|
|
next_hook = 0x0
|
|
#6 0x000000000041b5b0 in gui_main_loop ()
|
|
at /some_path/src/gui/curses/gui-curses-main.c:319
|
|
hook_fd_keyboard = 0x173b600
|
|
tv_timeout = {tv_sec = 0, tv_usec = 0}
|
|
read_fds = {fds_bits = {0 <repeats 16 times>}}
|
|
write_fds = {fds_bits = {0 <repeats 16 times>}}
|
|
except_fds = {fds_bits = {0 <repeats 16 times>}}
|
|
max_fd = <value optimized out>
|
|
----
|
|
|
|
You must report this trace to developers, and tell them what action caused this
|
|
crash.
|
|
|
|
Thank you for your help!
|
|
|
|
[[debug_running_weechat]]
|
|
==== Debug a running WeeChat
|
|
|
|
To debug a running WeeChat (for example if WeeChat seems blocked), you can use
|
|
gdb with process id (replace '12345' with PID of weechat process):
|
|
|
|
----
|
|
gdb /usr/bin/weechat 12345
|
|
----
|
|
|
|
Then like for a crash, use command `bt full`:
|
|
|
|
----
|
|
(gdb) bt full
|
|
----
|
|
|
|
[[usage]]
|
|
== Usage
|
|
|
|
[[running_weechat]]
|
|
=== Running WeeChat
|
|
|
|
Command line arguments:
|
|
|
|
include::cmdline_options.en.asciidoc[]
|
|
|
|
To start WeeChat, issue this command:
|
|
|
|
----
|
|
$ weechat
|
|
----
|
|
|
|
When you run WeeChat for the first time, a default configuration file is
|
|
created, with default options. The default configuration file is:
|
|
'~/.weechat/weechat.conf'.
|
|
|
|
You can edit this file at your convenience to configure WeeChat or you can set
|
|
parameters with `/set` command in WeeChat (see
|
|
<<weechat_commands,WeeChat commands>>).
|
|
|
|
[[screen_layout]]
|
|
=== Screen layout
|
|
|
|
Example of terminal with WeeChat:
|
|
|
|
....
|
|
▼ bar "title"
|
|
┌───────────────────────────────────────────────────────────────────────────┐
|
|
│Welcome to #test, this is a test channel │
|
|
│12:52:27 --> | Flashy (flashcode@weechat.org) has joined #test │@Flashy│
|
|
│12:52:27 -- | Nicks #test: [@Flashy @joe +weebot peter] │@joe │
|
|
│12:52:27 -- | Channel #test: 4 nicks (2 ops, 1 voice, 1 normal) │+weebot│
|
|
│12:52:27 -- | Channel created on Tue Jan 27 06:30:17 2009 │peter │
|
|
│12:54:15 peter | hey! │ │
|
|
│12:55:01 @joe | hello │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│[12:55] [6] [irc/freenode] 3:#test(+n){4}* [H: 4:#abc(2,5), 6] │
|
|
│[@Flashy(i)] hi peter!█ │
|
|
└───────────────────────────────────────────────────────────────────────────┘
|
|
▲ bars "status" and "input" bar "nicklist" ▲
|
|
....
|
|
|
|
Screen is composed by following areas:
|
|
|
|
* chat area (middle of screen) with chat lines, and for each line:
|
|
** time
|
|
** prefix (before "|")
|
|
** message (after "|")
|
|
* bars around chat area, default bars are:
|
|
** 'title' bar, above chat area
|
|
** 'status' bar, below chat area
|
|
** 'input' bar, below status bar
|
|
** 'nicklist' bar, on the right
|
|
|
|
Bar 'status' has following default items:
|
|
|
|
[width="100%",cols="^3,^4,10",options="header"]
|
|
|===
|
|
| Item | Example | Description
|
|
| time | `[12:55]` | Time
|
|
| buffer_last_number | `[6]` | Number of last buffer in list
|
|
| buffer_plugin | `[irc/freenode]` | Plugin of current buffer (irc plugin can add IRC server name used by buffer)
|
|
| buffer_number | `3` | Current buffer number
|
|
| buffer_name | `#test` | Current buffer name
|
|
| buffer_modes | `+n` | IRC channel modes
|
|
| buffer_nicklist_count | `{4}` | Number of nicks in nicklist
|
|
| buffer_zoom | ! | `!` means the merged buffer is zoomed (only this one is displayed), empty value means all merged buffers are displayed
|
|
| buffer_filter | `*` | Filtering indicator: `*` means some lines are filtered (hidden), empty value means all lines are displayed
|
|
| scroll | `-MORE(50)-` | Scroll indicator, with number of lines below last line displayed
|
|
| lag | `[Lag: 2.5]` | Lag indicator, in seconds (hidden if lag is low)
|
|
| hotlist | `[H: 4:#abc(2,5), 6]` | List of buffers with activity (unread messages) (in example, 2 highlights and 5 unread messages on '#abc', one unread message on buffer #6)
|
|
| completion | `abc(2) def(5)` | List of words for completion, with number of possible completions for each word
|
|
|===
|
|
|
|
Bar 'input' has following default items:
|
|
|
|
[width="100%",cols="^3,^4,10",options="header"]
|
|
|===
|
|
| Item | Example | Description
|
|
| input_prompt | `[@Flashy(i)]` | Input prompt, for irc: nick and modes (mode "+i" means invisible on freenode)
|
|
| away | `(away)` | Away indicator
|
|
| input_search | `[Search (~ str,msg)]` | Search indicator ("`~`": case insensitive, "`==`": case sensitive, "`str`": search string, "`regex`": search regular expression, "`msg`": search in messages, "`pre`": search in prefixes, "`pre\|msg`": search in prefixes and messages)
|
|
| input_paste | `[Paste 7 lines ? [ctrl-Y] Yes [ctrl-N] No]` | Question to user for pasting lines
|
|
| input_text | `hi peter!` | Input text
|
|
|===
|
|
|
|
Other items available (not used in bars by default):
|
|
|
|
[width="100%",cols="^3,^4,10",options="header"]
|
|
|===
|
|
| Item | Example | Description
|
|
| aspell_dict | `fr,en` | Spelling dictionaries used on current buffer
|
|
| aspell_suggest | `print,prone,prune` | Spelling suggestions for word under cursor (if misspelled)
|
|
| buffer_count | `10` | Total number of buffers opened
|
|
| buffer_short_name | `#test` | Current buffer short name
|
|
| irc_channel | `#test` | Current IRC channel name
|
|
| irc_nick_modes | `@` | IRC modes for self nick
|
|
| mouse_status | `M` | Mouse status (empty if mouse is disabled)
|
|
| window_number | `2` | Current window number
|
|
|===
|
|
|
|
[[buffers_and_windows]]
|
|
=== Buffers and windows
|
|
|
|
A 'buffer' is composed by a number, a name, lines displayed (and some other
|
|
data).
|
|
|
|
Examples of buffers:
|
|
|
|
* core buffer (created by WeeChat on startup, can not be closed)
|
|
* irc server (displays messages from server)
|
|
* irc channel
|
|
* irc private
|
|
|
|
A 'window' is a screen area which displays a buffer. It is possible to split
|
|
your screen into many windows.
|
|
|
|
Each window displays one buffer. A buffer can be hidden (not displayed by a
|
|
window) or displayed by one or more windows.
|
|
|
|
Example of horizontal split (`/window splith`):
|
|
|
|
....
|
|
▼ window #2 (buffer #4)
|
|
┌───────────────────────────────────────────────────────────────────────────┐
|
|
│Welcome to #abc │
|
|
│12:55:12 Max | hi │@Flashy│
|
|
│12:55:20 @Flashy | hi Max! │Max │
|
|
│12:55:32 Max | how are you? │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│[12:55] [6] [irc/freenode] 4:#abc(+n){2} │
|
|
│[@Flashy] │
|
|
│───────────────────────────────────────────────────────────────────────────│
|
|
│Welcome to #test │
|
|
│12:54:15 peter | hey! │@Flashy│
|
|
│12:55:01 @joe | hello │@joe │
|
|
│ │+weebot│
|
|
│ │peter │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│[12:55] [6] [irc/freenode] 3:#test(+n){4} │
|
|
│[@Flashy] hi peter!█ │
|
|
└───────────────────────────────────────────────────────────────────────────┘
|
|
▲ window #1 (buffer #3)
|
|
....
|
|
|
|
Example of vertical split (`/window splitv`):
|
|
|
|
....
|
|
┌───────────────────────────────────────────────────────────────────────────┐
|
|
│Welcome to #test │Welcome to #abc │
|
|
│12:54:15 peter | hey! │@Flashy│12:55:12 Max | hi │@Flashy│
|
|
│12:55:01 @joe | hello │@joe │12:55:20 @Flashy | hi Max! │Max │
|
|
│ │+weebot│ │ │
|
|
│ │peter │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│[12:55] [irc/oftc] 3:#test(+n){4} │[12:55] [irc/oftc] 4:#abc(+n){2} │
|
|
│[@Flashy] hi peter!█ │[@Flashy] │
|
|
└───────────────────────────────────────────────────────────────────────────┘
|
|
▲ window #1 (buffer #3) ▲ window #2 (buffer #4)
|
|
....
|
|
|
|
Example of vertical + horizontal splits:
|
|
|
|
....
|
|
▼ window #3 (buffer #5)
|
|
┌───────────────────────────────────────────────────────────────────────────┐
|
|
│Welcome to #test │Welcome to #def │
|
|
│12:54:15 peter | hey! │@Flashy│12:55:42 @Flashy | hi │@Flashy│
|
|
│12:55:01 @joe | hello │@joe │12:55:56 alex | hi Flashy │alex │
|
|
│ │+weebot│ │ │
|
|
│ │peter │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │[12:55] [irc/oftc] 5:#def(+n){2} │
|
|
│ │ │[@Flashy] │
|
|
│ │ │─────────────────────────────────────│
|
|
│ │ │Welcome to #abc │
|
|
│ │ │12:55:12 Max | hi │@Flashy│
|
|
│ │ │12:55:20 @Flashy | hi Max! │Max │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│[12:55] [irc/oftc] 3:#test(+n){4} │[12:55] [irc/oftc] 4:#abc(+n){2} │
|
|
│[@Flashy] hi peter!█ │[@Flashy] │
|
|
└───────────────────────────────────────────────────────────────────────────┘
|
|
▲ window #1 (buffer #3) ▲ window #2 (buffer #4)
|
|
....
|
|
|
|
[[bars]]
|
|
=== Bars
|
|
|
|
A 'bar' is an area beside the chat that can contain any type of text.
|
|
|
|
The bar options can be set with options `weechat.bar.name.option` where `name`
|
|
is the name of the bar and `option` the option for this bar.
|
|
|
|
List of bar options:
|
|
|
|
[width="100%",cols="2m,2,10",options="header"]
|
|
|===
|
|
| Option | Values | Description
|
|
|
|
| type | `root`, `window` |
|
|
A bar with type `root` is displayed exactly one time on screen, outside all
|
|
windows. There is no root bar by default, but an example is the bar 'buffers'
|
|
created by script 'buffers.pl' (sidebar with list of buffers). +
|
|
A bar with type `window` is displayed in each window, for example if you
|
|
split one time the screen (with `/window splith` or `/window splitv`), you
|
|
will have one bar in each window. The four default bars ('title', 'status',
|
|
'input', 'nicklist') have type `window`.
|
|
|
|
| position | `top`, `bottom`, `left`, `right` |
|
|
Position of the bar: above/below chat, on the left/right.
|
|
|
|
| priority | integer ≥ 0 |
|
|
Priority for display of bar: this is used for ordering the bars on screen when
|
|
many bars have same type and position. +
|
|
The bars are displayed from the edge of the screen to the center. A higher
|
|
priority will display bar at the beginning, so closer to the edge. +
|
|
Example: 'input' bar has priority 1000, so it is displayed before the 'status'
|
|
bar, which has priority 500.
|
|
|
|
| size | integer ≥ 0 |
|
|
The size of the bar: number of columns for position left/right, number
|
|
of lines for position top/bottom. A size of `0` means automatic, so the size
|
|
will be computed according to content displayed in bar.
|
|
|
|
| size_max | integer ≥ 0 |
|
|
The maximum size for a bar, `0` = no limit (this option is used only if
|
|
`size` = `0`).
|
|
|
|
| color_bg | color |
|
|
The default background color for the bar.
|
|
|
|
| color_fg | color |
|
|
The default text color for the bar.
|
|
|
|
| color_delim | color |
|
|
The color for delimiters in bar.
|
|
|
|
| hidden | `on`, `off` |
|
|
When option is `on`, the bar is hidden. +
|
|
Note: instead of changing this option, the command `/bar` is preferred, for
|
|
example: `/bar toggle nicklist` (see command <<command_weechat_bar,/bar>>).
|
|
|
|
| separator | `on`, `off` |
|
|
When option is `on`, a separator (line) is displayed between this bar and
|
|
other bars (or chat).
|
|
|
|
| items | string |
|
|
A list of 'items' (see <<bar_items,items>> for more info).
|
|
|
|
| filling_left_right | `horizontal`, `vertical`, `columns_horizontal`, `columns_vertical` |
|
|
Type of filling for a bar which has position `left` or `right` (see
|
|
<<bar_filling,filling>> for more info).
|
|
|
|
| filling_top_bottom | `horizontal`, `vertical`, `columns_horizontal`, `columns_vertical` |
|
|
Type of filling for a bar which has position `top` or `bottom` (see
|
|
<<bar_filling,filling>> for more info).
|
|
|
|
| conditions | string |
|
|
The conditions to display the bar (see <<bar_conditions,conditions>> for more
|
|
info).
|
|
|===
|
|
|
|
[[bar_items]]
|
|
==== Items
|
|
|
|
The option 'items' is a string with a list of bar items, separated by a comma
|
|
(space between items on screen) or "+" (glued items).
|
|
|
|
The list of bar items is displayed with command `/bar listitems`.
|
|
|
|
Before or after item name, you can use chars (that are not alphanumeric, "-" or
|
|
"_"). They will be displayed before/after item with the delimiters color
|
|
defined in bar (option 'color_delim').
|
|
|
|
Example of bar with items "[time],buffer_number+:+buffer_plugin+.+buffer_name":
|
|
|
|
....
|
|
┌───────────────────────────────────────────────────────────────────────────┐
|
|
│[12:55] 3:irc/freenode.#weechat │
|
|
└───────────────────────────────────────────────────────────────────────────┘
|
|
....
|
|
|
|
A special syntax can be used to force the buffer used when displaying the bar
|
|
item: "@buffer:item" (where "buffer" is the full name of buffer and "item" is
|
|
the name of a bar item).
|
|
|
|
This is useful in root bars, to display item for a specific buffer which is
|
|
not displayed in the current window (or even not displayed at all).
|
|
|
|
Example: nicklist of bitlbee in a root bar (if the bar is called
|
|
'bitlist' and if bitlbee server is called 'bitlbee'):
|
|
|
|
----
|
|
/set weechat.bar.bitlist.items "@irc.bitlbee.&bitlbee:buffer_nicklist"
|
|
----
|
|
|
|
[[bar_filling]]
|
|
==== Filling
|
|
|
|
There are four types of filling:
|
|
|
|
* `horizontal`: the items are displayed horizontally, from left to right. If
|
|
there are new lines in items, a space is used to separate lines.
|
|
* `vertical`: the items are displayed from top to bottom. If there are new
|
|
lines in items, a new line is used to separate lines.
|
|
* `columns_horizontal`: items are displayed using columns, where text is
|
|
aligned on the left. The first item is on top left, the second is on same
|
|
line, on the right.
|
|
* `columns_vertical`: items are displayed using columns, where text is aligned
|
|
on the left. The first item is on top left, the second is one line below.
|
|
|
|
Default bars 'title', 'status' and 'input' have 'horizontal' filling, and
|
|
default bar 'nicklist' has 'vertical' filling.
|
|
|
|
Some examples of filling for bar 'nicklist':
|
|
|
|
....
|
|
┌───────────────────────────────────────────────────────────────────────┐
|
|
│Welcome to #test, this is a test channel │
|
|
│12:54:15 peter | hey! │@carl │
|
|
│12:55:01 +Max | hello │@jessika│
|
|
│ │@maddy │
|
|
│ │%Diego │
|
|
│ │%Melody │
|
|
│ │+Max │
|
|
│ │ celia │
|
|
│ │ Eva │
|
|
│ │ freddy │
|
|
│ │ Harold^│
|
|
│ │ henry4 │
|
|
│ │ jimmy17│
|
|
│ │ jodie ▼│
|
|
│[12:55] [6] [irc/freenode] 3:#test(+n){24} │
|
|
│[@carl] █ │
|
|
└───────────────────────────────────────────────────────────────────────┘
|
|
filling_left_right = vertical ▲
|
|
|
|
┌───────────────────────────────────────────────────────────────────────┐
|
|
│Welcome to #test, this is a test channel │
|
|
│12:54:15 peter | hey! │@carl lee │
|
|
│12:55:01 +Max | hello │@jessika louise │
|
|
│ │@maddy mario │
|
|
│ │%Diego mark │
|
|
│ │%Melody peter │
|
|
│ │+Max Rachel │
|
|
│ │ celia richard│
|
|
│ │ Eva sheryl │
|
|
│ │ freddy Vince │
|
|
│ │ Harold^ warren │
|
|
│ │ henry4 zack │
|
|
│ │ jimmy17 │
|
|
│ │ jodie │
|
|
│[12:55] [6] [irc/freenode] 3:#test(+n){24} │
|
|
│[@carl] █ │
|
|
└───────────────────────────────────────────────────────────────────────┘
|
|
filling_left_right = columns_vertical ▲
|
|
|
|
┌───────────────────────────────────────────────────────────────────────┐
|
|
│@carl %Diego celia Harold^ jodie mario Rachel Vince │
|
|
│@jessika %Melody Eva henry4 lee mark richard warren │
|
|
│@maddy +Max freddy jimmy17 louise peter sheryl zack │
|
|
│───────────────────────────────────────────────────────────────────────│
|
|
│ │
|
|
filling_top_bottom = columns_vertical ▲
|
|
|
|
┌───────────────────────────────────────────────────────────────────────┐
|
|
│@carl @jessika @maddy %Diego %Melody +Max celia Eva │
|
|
│ freddy Harold^ henry4 jimmy17 jodie lee louise mario │
|
|
│ mark peter Rachel richard sheryl Vince warren zack │
|
|
│───────────────────────────────────────────────────────────────────────│
|
|
│ │
|
|
filling_top_bottom = columns_horizontal ▲
|
|
....
|
|
|
|
[[bar_conditions]]
|
|
==== Conditions
|
|
|
|
The option 'conditions' is a string which is evaluated to know if the bar
|
|
must be displayed or not.
|
|
|
|
The string can be:
|
|
|
|
* 'active': the window must be active
|
|
* 'inactive': the window must be inactive
|
|
* 'nicklist': the buffer displayed in window must have a nicklist
|
|
* an expression: it is evaluated as boolean (see command
|
|
<<command_weechat_eval,/eval>>)
|
|
|
|
For the expression, following variables are available:
|
|
|
|
* `${active}`: true if window is active
|
|
* `${inactive}`: true if window is inactive
|
|
* `${nicklist}`: true if buffer displayed in window has a nicklist
|
|
|
|
Following pointers are available:
|
|
|
|
* `${window}`: the window where condition is evaluated
|
|
* `${buffer}`: the buffer of window where condition is evaluated
|
|
|
|
Example to display nicklist bar in all buffers with a nicklist, and only if
|
|
width of window is > 100 :
|
|
|
|
----
|
|
/set weechat.bar.nicklist.conditions "${nicklist} && ${window.win_width} > 100"
|
|
----
|
|
|
|
Same condition, but always display nicklist on buffer '&bitlbee' (even if window
|
|
is small):
|
|
|
|
----
|
|
/set weechat.bar.nicklist.conditions "${nicklist} && (${window.win_width} > 100 || ${buffer.full_name} == irc.bitlbee.&bitlbee)"
|
|
----
|
|
|
|
[[bare_display]]
|
|
=== Bare display
|
|
|
|
A special display, called "bare display" can be used for easy click on long URLs
|
|
and selection of text (using the mouse).
|
|
|
|
The bare display has following features:
|
|
|
|
* it displays only the content of current buffer: no window split neither bars
|
|
(no title, nicklist, status, input, ...)
|
|
* the WeeChat mouse support is disabled (if it was enabled): you can use your
|
|
mouse like you do in the terminal to click on URLs and select text
|
|
* ncurses is not used, therefore URLs are not cut at the end of lines.
|
|
|
|
The default key to enabled bare display is key[alt-l], and same key to exit (or
|
|
by default anything changing the input will exit the bare display, see option
|
|
<<option_weechat.look.bare_display_exit_on_input,weechat.look.bare_display_exit_on_input>>).
|
|
|
|
The time format can be customized with the option
|
|
<<option_weechat.look.bare_display_time_format,weechat.look.bare_display_time_format>>.
|
|
|
|
The bare display can be enabled for a specific delay using the command
|
|
<<command_weechat_window,/window>>.
|
|
|
|
If WeeChat looks like that:
|
|
|
|
....
|
|
┌───────────────────────────────────────────────────────────────────────────┐
|
|
│Welcome to #test, this is a test channel │
|
|
│12:52:27 --> | Flashy (flashcode@weechat.org) has joined #test │@Flashy│
|
|
│12:52:27 -- | Nicks #test: [@Flashy @joe +weebot peter] │@joe │
|
|
│12:52:27 -- | Channel #test: 4 nicks (2 ops, 1 voice, 1 normal) │+weebot│
|
|
│12:52:27 -- | Channel created on Tue Jan 27 06:30:17 2009 │peter │
|
|
│12:54:15 peter | hey! │ │
|
|
│12:55:01 @joe | peter: hook_process: https://weechat.org/files/do │ │
|
|
│ | c/devel/weechat_plugin_api.en.html#_weechat_hook_ │ │
|
|
│ | process │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│[12:55] [6] [irc/freenode] 3:#test(+n){4}* [H: 4:#abc(2,5), 6] │
|
|
│[@Flashy(i)] hi peter!█ │
|
|
└───────────────────────────────────────────────────────────────────────────┘
|
|
....
|
|
|
|
The screen will look like that in bare display:
|
|
|
|
....
|
|
┌───────────────────────────────────────────────────────────────────────────┐
|
|
│ │
|
|
│ │
|
|
│ │
|
|
│ │
|
|
│ │
|
|
│ │
|
|
│ │
|
|
│ │
|
|
│ │
|
|
│ │
|
|
│ │
|
|
│ │
|
|
│ │
|
|
│12:52 --> Flashy (flashcode@weechat.org) has joined #test │
|
|
│12:52 -- Nicks #test: [@Flashy @joe +weebot peter] │
|
|
│12:52 -- Channel #test: 4 nicks (2 ops, 1 voice, 1 normal) │
|
|
│12:52 -- Channel created on Tue Jan 27 06:30:17 2009 │
|
|
│12:54 <peter> hey! │
|
|
│12:55 <@joe> peter: hook_process: https://weechat.org/files/doc/devel/weech│
|
|
│at_plugin_api.en.html#_weechat_hook_process │
|
|
└───────────────────────────────────────────────────────────────────────────┘
|
|
....
|
|
|
|
So you can click the URL from 'joe' without any problem in your terminal (of
|
|
course this supposes that your terminal supports click on URLs).
|
|
|
|
[[notify_levels]]
|
|
=== Notify levels
|
|
|
|
Four levels are possible in messages displayed in buffers, from lower to higher:
|
|
|
|
* 'low': message with low importance (for example irc join/part/quit)
|
|
* 'message': message from a user
|
|
* 'private': message in a private buffer
|
|
* 'highlight': message with highlight
|
|
|
|
Each buffer has a notify level, which is used to decide what messages will add
|
|
buffer in hotlist.
|
|
|
|
The default notify level can be set using option
|
|
<<option_weechat.look.buffer_notify_default,weechat.look.buffer_notify_default>>,
|
|
default is 'all'.
|
|
|
|
[width="50%",cols="3m,10",options="header"]
|
|
|===
|
|
| Notify level | Level of messages added to hotlist
|
|
| none | (none)
|
|
| highlight | 'highlight' + 'private'
|
|
| message | 'highlight' + 'private' + 'message'
|
|
| all | 'highlight' + 'private' + 'message' + 'low'
|
|
|===
|
|
|
|
Notify level can be defined for a set of buffers, for example all buffers of
|
|
irc server "freenode":
|
|
|
|
----
|
|
/set weechat.notify.irc.freenode message
|
|
----
|
|
|
|
Set notify level 'highlight' on channel "#weechat" only:
|
|
|
|
----
|
|
/set weechat.notify.irc.freenode.#weechat highlight
|
|
----
|
|
|
|
The notify level for a buffer can be set with command `/buffer`:
|
|
|
|
----
|
|
/buffer notify highlight
|
|
----
|
|
|
|
[[key_bindings]]
|
|
=== Default key bindings
|
|
|
|
[[key_bindings_command_line]]
|
|
==== Keys for command line
|
|
|
|
[width="100%",cols="^.^3,.^10,.^5",options="header"]
|
|
|===
|
|
| Key | Description | Command
|
|
| key[←] .2+| Go to previous char in command line .2+| `/input move_previous_char`
|
|
| key[ctrl-b]
|
|
| key[→] .2+| Go to next char in command line .2+| `/input move_next_char`
|
|
| key[ctrl-f]
|
|
| key[ctrl-←] .2+| Go to previous word in command line .2+| `/input move_previous_word`
|
|
| key[alt-b]
|
|
| key[ctrl-→] .2+| Go to next word in command line .2+| `/input move_next_word`
|
|
| key[alt-f]
|
|
| key[Home] .2+| Go to the beginning of command line .2+| `/input move_beginning_of_line`
|
|
| key[ctrl-a]
|
|
| key[End] .2+| Go to the end of command line .2+| `/input move_end_of_line`
|
|
| key[ctrl-e]
|
|
| key[ctrl-c,b] | Insert code for bold text | `/input insert \x02`
|
|
| key[ctrl-c,c] | Insert code for colored text | `/input insert \x03`
|
|
| key[ctrl-c,i] | Insert code for italic text | `/input insert \x1D`
|
|
| key[ctrl-c,o] | Insert code for color reset | `/input insert \x0F`
|
|
| key[ctrl-c,v] | Insert code for reverse color | `/input insert \x16`
|
|
| key[ctrl-c,_] | Insert code for underlined text | `/input insert \x1F`
|
|
| key[Del] .2+| Delete next char in command line .2+| `/input delete_next_char`
|
|
| key[ctrl-d]
|
|
| key[Backsp.] .2+| Delete previous char in command line .2+| `/input delete_previous_char`
|
|
| key[ctrl-h]
|
|
| key[ctrl-k] | Delete from cursor until end of command line (deleted string is copied to clipboard) | `/input delete_end_of_line`
|
|
| key[ctrl-r] | Search for text in buffer history (see <<key_bindings_search_context,keys for search context>>) | `/input search_text`
|
|
| key[ctrl-t] | Transpose chars | `/input transpose_chars`
|
|
| key[ctrl-u] | Delete from cursor until beginning of command line (deleted string is copied to clipboard) | `/input delete_beginning_of_line`
|
|
| key[ctrl-w] | Delete previous word of command line (deleted string is copied to clipboard) | `/input delete_previous_word`
|
|
| key[ctrl-y] | Paste clipboard content | `/input clipboard_paste`
|
|
| key[ctrl-_] | Undo last action on command line | `/input undo`
|
|
| key[alt-_] | Redo last action on command line | `/input redo`
|
|
| key[Tab] | Complete command or nick (key[Tab] again: find next completion) | `/input complete_next`
|
|
| key[shift-Tab] | Without completion: do a partial completion, with pending completion: complete with previous completion | `/input complete_previous`
|
|
| key[Enter] .3+| Execute command or send message (in search mode: stop search) .3+| `/input return`
|
|
| key[ctrl-j]
|
|
| key[ctrl-m]
|
|
| key[↑] | Call previous command/message (in search mode: search up) | `/input history_previous`
|
|
| key[↓] | Call next command/message (in search mode: search down) | `/input history_next`
|
|
| key[ctrl-↑] | Call previous command/message in global history (common for all buffers) | `/input history_global_previous`
|
|
| key[ctrl-↓] | Call next command/message in global history (common for all buffers) | `/input history_global_next`
|
|
| key[alt-d] | Delete next word in command line (deleted string is copied to clipboard) | `/input delete_next_word`
|
|
| key[alt-k] | Grab a key and insert its code (and command bound if key exists) in command line | `/input grab_key_command`
|
|
| key[alt-r] | Delete entire command line | `/input delete_line`
|
|
| key[alt-s] | Toggle aspell | `/mute aspell toggle`
|
|
|===
|
|
|
|
[[key_bindings_buffers_windows]]
|
|
==== Keys for buffers / windows
|
|
|
|
[width="100%",cols="^.^3,.^10,.^5",options="header"]
|
|
|===
|
|
| Key | Description | Command
|
|
| key[ctrl-l] | Redraw whole window | `/window refresh`
|
|
| key[ctrl-s,ctrl-u] | Set unread marker on all buffers | `/input set_unread`
|
|
| key[ctrl-x] | Switch current buffer if buffers are attached with same number | `/input switch_active_buffer`
|
|
| key[alt-x] | Zoom on merged buffer (key[alt-x] again: display all merged buffers) | `/input zoom_merged_buffer`
|
|
| key[PgUp] | Scroll up one page in buffer history | `/window page_up`
|
|
| key[PgDn] | Scroll down one page in buffer history | `/window page_down`
|
|
| key[alt-PgUp] | Scroll up a few lines in buffer history | `/window scroll_up`
|
|
| key[alt-PgDn] | Scroll down a few lines in buffer history | `/window scroll_down`
|
|
| key[alt-Home] | Scroll to top of buffer | `/window scroll_top`
|
|
| key[alt-End] | Scroll to bottom of buffer | `/window scroll_bottom`
|
|
| key[alt-←] .4+| Switch to previous buffer .4+| `/buffer -1`
|
|
| key[alt-↑]
|
|
| key[ctrl-p]
|
|
| key[F5]
|
|
| key[alt-→] .4+| Switch to next buffer .4+| `/buffer +1`
|
|
| key[alt-↓]
|
|
| key[ctrl-n]
|
|
| key[F6]
|
|
| key[F7] | Switch to previous window | `/window -1`
|
|
| key[F8] | Switch to next window | `/window +1`
|
|
| key[F9] | Scroll buffer's title on the left | `/bar scroll title * -30%`
|
|
| key[F10] | Scroll buffer's title on the right | `/bar scroll title * +30%`
|
|
| key[F11] | Scroll up one page in nicklist | `/bar scroll nicklist * -100%`
|
|
| key[F12] | Scroll down one page in nicklist | `/bar scroll nicklist * +100%`
|
|
| key[alt-F11] | Go to the beginning of nicklist | `/bar scroll nicklist * b`
|
|
| key[alt-F12] | Go to the end of nicklist | `/bar scroll nicklist * e`
|
|
| key[alt-a] | Switch to next buffer with activity (with priority: highlight, message, other) | `/input jump_smart`
|
|
| key[alt-h] | Clear hotlist (activity notification on other buffers) | `/input hotlist_clear`
|
|
| key[alt-j,alt-f] | Switch to first buffer | `/buffer -`
|
|
| key[alt-j,alt-l] | Switch to last buffer | `/buffer +`
|
|
| key[alt-j,alt-r] | Switch to IRC raw buffer | `/server raw`
|
|
| key[alt-j,alt-s] | Switch to IRC server buffer | `/server jump`
|
|
| key[alt-0...9] | Switch to buffer by number (0 = 10) | `/buffer *N`
|
|
| key[alt-j,01...99] | Switch to buffer by number | `/buffer NN`
|
|
| key[alt-l] | Toggle bare display on/off | `/window bare`
|
|
| key[alt-m] | Toggle mouse | `/mouse toggle`
|
|
| key[alt-n] | Scroll to next highlight | `/window scroll_next_highlight`
|
|
| key[alt-p] | Scroll to previous highlight | `/window scroll_previous_highlight`
|
|
| key[alt-u] | Scroll to first unread line in buffer | `/window scroll_unread`
|
|
| key[alt-w,alt-↑] | Switch to window above | `/window up`
|
|
| key[alt-w,alt-↓] | Switch to window below | `/window down`
|
|
| key[alt-w,alt-←] | Switch to window on the left | `/window left`
|
|
| key[alt-w,alt-→] | Switch to window on the right | `/window right`
|
|
| key[alt-w,alt-b] | Balance the sizes of all windows | `/window balance`
|
|
| key[alt-w,alt-s] | Swap buffers of two windows | `/window swap`
|
|
| key[alt-z] | Zoom on current window (key[alt-z] again: restore initial windows state, before zoom) | `/window zoom`
|
|
| key[alt-]key[<] | Switch to previous buffer in list of visited buffers | `/input jump_previously_visited_buffer`
|
|
| key[alt-]key[>] | Switch to next buffer in list of visited buffers | `/input jump_next_visited_buffer`
|
|
| key[alt-/] | Switch to last buffer displayed (before last jump to a buffer) | `/input jump_last_buffer_displayed`
|
|
| key[alt-=] | Toggle filters on/off | `/filter toggle`
|
|
| key[alt--] | Toggle filters on/off in current buffer | `/filter toggle @`
|
|
|===
|
|
|
|
[[key_bindings_search_context]]
|
|
==== Keys for "search" context
|
|
|
|
These keys are used in context "search" (when key[ctrl-r] is pressed to search
|
|
text in buffer).
|
|
|
|
[width="100%",cols="^.^3,.^10,.^5",options="header"]
|
|
|===
|
|
| Key | Description | Command
|
|
| key[ctrl-r] | Switch search type: string (default), regular expression | `/input search_switch_regex`
|
|
| key[alt-c] | Switch exact case for search | `/input search_switch_case`
|
|
| key[Tab] | Switch search in: messages (default), prefixes, prefixes + messages | `/input search_switch_where`
|
|
| key[↑] | Search previous line | `/input search_previous`
|
|
| key[↓] | Search next line | `/input search_next`
|
|
| key[Enter] .3+| Stop search .3+| `/input search_stop`
|
|
| key[ctrl-j]
|
|
| key[ctrl-m]
|
|
|===
|
|
|
|
[[key_bindings_cursor_context]]
|
|
==== Keys for "cursor" context
|
|
|
|
These keys are used in context "cursor" (free movement of cursor on screen).
|
|
|
|
[width="100%",cols="^.^3,^.^3,.^10,.^8",options="header"]
|
|
|===
|
|
| Key | Area | Description | Command
|
|
| key[↑] | - | Move cursor one line up | `/cursor move up`
|
|
| key[↓] | - | Move cursor one line down | `/cursor move down`
|
|
| key[←] | - | Move cursor one column left | `/cursor move left`
|
|
| key[→] | - | Move cursor one column right | `/cursor move right`
|
|
| key[alt-↑] | - | Move cursor one area up | `/cursor move area_up`
|
|
| key[alt-↓] | - | Move cursor one area down | `/cursor move area_down`
|
|
| key[alt-←] | - | Move cursor one area left | `/cursor move area_left`
|
|
| key[alt-→] | - | Move cursor one area right | `/cursor move area_right`
|
|
| key[m] | chat | Quote message | `hsignal:chat_quote_message;/cursor stop`
|
|
| key[q] | chat | Quote prefix + message | `hsignal:chat_quote_prefix_message;/cursor stop`
|
|
| key[Q] | chat | Quote time + prefix + message | `hsignal:chat_quote_time_prefix_message;/cursor stop`
|
|
| key[b] | nicklist | Ban nick | `/window ${_window_number};/ban ${nick}`
|
|
| key[k] | nicklist | Kick nick | `/window ${_window_number};/kick ${nick}`
|
|
| key[K] | nicklist | Kick and ban nick | `/window ${_window_number};/kickban ${nick}`
|
|
| key[q] | nicklist | Open query with nick | `/window ${_window_number};/query ${nick};/cursor stop`
|
|
| key[w] | nicklist | Do a whois on nick | `/window ${_window_number};/whois ${nick}`
|
|
| key[Enter] .3+| - .3+| Stop cursor mode .3+| `/cursor stop`
|
|
| key[ctrl-j]
|
|
| key[ctrl-m]
|
|
|===
|
|
|
|
[[key_bindings_mouse_context]]
|
|
==== Keys for "mouse" context
|
|
|
|
These keys are used in context "mouse", namely when a mouse event occurs.
|
|
|
|
[width="100%",cols="^.^3,^.^3,^.^3,.^10,.^8",options="header"]
|
|
|===
|
|
| Button ^(1)^ | Gesture | Area | Description | Command
|
|
| ◾◽◽ | - | chat | Switch to window | `/window ${_window_number}`
|
|
| ◾◽◽ | left | chat | Switch to previous buffer | `/window ${_window_number};/buffer +1`
|
|
| ◾◽◽ | right | chat | Switch to next buffer | `/window ${_window_number};/buffer +1`
|
|
| ◾◽◽ | left (long) | chat | Switch to first buffer | `/window ${_window_number};/buffer 1`
|
|
| ◾◽◽ | right (long) | chat | Switch to last buffer | `/window ${_window_number};/input jump_last_buffer`
|
|
| ◾◽◽ | - | chat (script buffer) | Select line in script buffer | `/script go ${_chat_line_y}`
|
|
| ◽◽◾ | - | chat (script buffer) | Install/remove script | `/script go ${_chat_line_y};/script installremove -q ${script_name_with_extension}`
|
|
| ⇑ | - | chat | Scroll up a few lines in buffer history | `/window scroll_up -window ${_window_number}`
|
|
| ⇓ | - | chat | Scroll down a few lines in buffer history | `/window scroll_down -window ${_window_number}`
|
|
| ⇑ | - | chat (script buffer) | Move 5 lines up in script buffer | `/script up 5`
|
|
| ⇓ | - | chat (script buffer) | Move 5 lines down in script buffer | `/script down 5`
|
|
| key[ctrl-]⇑ | - | chat | Scroll horizontally to the left | `/window scroll_horiz -window ${_window_number} -10%`
|
|
| key[ctrl-]⇓ | - | chat | Scroll horizontally to the right | `/window scroll_horiz -window ${_window_number} +10%`
|
|
| ◾◽◽ | up | nicklist | Scroll up one page in nicklist | `/bar scroll nicklist ${_window_number} -100%`
|
|
| ◾◽◽ | down | nicklist | Scroll down one page in nicklist | `/bar scroll nicklist ${_window_number} +100%`
|
|
| ◾◽◽ | up (long) | nicklist | Go to the beginning of nicklist | `/bar scroll nicklist ${_window_number} b`
|
|
| ◾◽◽ | down (long) | nicklist | Go to the end of nicklist | `/bar scroll nicklist ${_window_number} e`
|
|
| ◾◽◽ | - | nicklist | Open query with nick | `/window ${_window_number};/query ${nick}`
|
|
| ◽◽◾ | - | nicklist | Do a whois on nick | `/window ${_window_number};/whois ${nick}`
|
|
| ◾◽◽ | left | nicklist | Kick nick | `/window ${_window_number};/kick ${nick}`
|
|
| ◾◽◽ | left (long) | nicklist | Kick and ban nick | `/window ${_window_number};/kickban ${nick}`
|
|
| ◽◽◾ | left | nicklist | Ban nick | `/window ${_window_number};/ban ${nick}`
|
|
| ◽◽◾ | - | input | Grab a mouse event and insert its code in command line | `/input grab_mouse_area`
|
|
| ⇑ | - | any bar | Scroll bar by -20% | `/bar scroll ${_bar_name} ${_window_number} -20%`
|
|
| ⇓ | - | any bar | Scroll bar by +20% | `/bar scroll ${_bar_name} ${_window_number} +20%`
|
|
| ◽◾◽ | - | anywhere | Start cursor mode at this point | `/cursor go ${_x},${_y}`
|
|
|===
|
|
|
|
[NOTE]
|
|
^(1)^ "⇑" and "⇓" are wheel up and down.
|
|
|
|
[[mouse]]
|
|
=== Mouse support
|
|
|
|
WeeChat supports mouse clicks and gestures. It is working with local terminal,
|
|
and remotely via ssh connection with or without screen/tmux.
|
|
|
|
[[mouse_enable]]
|
|
==== Enable mouse
|
|
|
|
To enable mouse at startup:
|
|
|
|
----
|
|
/set weechat.look.mouse on
|
|
----
|
|
|
|
To enable mouse now, press key[alt-m] or do following command:
|
|
|
|
----
|
|
/mouse enable
|
|
----
|
|
|
|
It is possible to temporarily disable mouse, and bind that on a key. For example
|
|
key key[alt-x] to disable mouse for 10 seconds:
|
|
|
|
----
|
|
/key bind meta-x /mouse toggle 10
|
|
----
|
|
|
|
When mouse is enabled in WeeChat, you can use key[shift] modifier to select or
|
|
click in terminal, as if the mouse was disabled (on some terminals like iTerm,
|
|
you have to use key[alt] instead of key[shift]).
|
|
|
|
[NOTE]
|
|
For any problem with mouse, please look at 'WeeChat FAQ'.
|
|
|
|
[[mouse_bind_events]]
|
|
==== Bind mouse events to commands
|
|
|
|
Many default mouse events are already defined by WeeChat (see
|
|
<<key_bindings_mouse_context,keys for "mouse" context>>).
|
|
|
|
You can change or add bindings with the command `/key` using context "mouse"
|
|
(for syntax, see command <<command_weechat_key,/key>>).
|
|
|
|
Event name consists of a modifier (optional), a button/wheel name and a gesture
|
|
(optional). Different elements are separated by "-".
|
|
|
|
List of modifiers:
|
|
|
|
[width="50%",cols="3m,4",options="header"]
|
|
|===
|
|
| Modifier | Description
|
|
| ctrl | Key key[ctrl]
|
|
| alt | Key key[alt]
|
|
| ctrl-alt | Keys key[ctrl-]key[alt]
|
|
|===
|
|
|
|
List of buttons/wheel:
|
|
|
|
[width="50%",cols="3m,4",options="header"]
|
|
|===
|
|
| Button/wheel | Description
|
|
| button1 | Click on left button
|
|
| button2 | Click on right button
|
|
| button3 | Click on middle button (often click on wheel)
|
|
| button4 ... button9 | Click on extra buttons
|
|
| wheelup | Wheel (up)
|
|
| wheeldown | Wheel (down)
|
|
|===
|
|
|
|
List of gestures (only for buttons, not wheel):
|
|
|
|
[width="50%",cols="3m,4",options="header"]
|
|
|===
|
|
| Gesture | Distance
|
|
| gesture-up | 3 ... 19
|
|
| gesture-up-long | ≥ 20
|
|
| gesture-down | 3 ... 19
|
|
| gesture-down-long | ≥ 20
|
|
| gesture-left | 3 ... 39
|
|
| gesture-left-long | ≥ 40
|
|
| gesture-right | 3 ... 39
|
|
| gesture-right-long | ≥ 40
|
|
|===
|
|
|
|
List of incomplete events (only for buttons, useful for plugins/scripts):
|
|
|
|
[width="50%",cols="3m,4",options="header"]
|
|
|===
|
|
| Event | Description
|
|
| event-down | Button was pressed but not released yet
|
|
| event-drag | Mouse was moved with button pressed down
|
|
|===
|
|
|
|
Example of events:
|
|
|
|
* `button1`
|
|
* `ctrl-button1`
|
|
* `button1-gesture-right`
|
|
* `button1-event-down`
|
|
* `button1-event-drag`
|
|
* `alt-button2-gesture-down-long`
|
|
* `wheelup`
|
|
* `ctrl-alt-wheeldown`
|
|
* ...
|
|
|
|
[TIP]
|
|
When binding a key in context "mouse", it's possible to match many events using
|
|
`*` at beginning or end of name, for example `button1-gesture-*` will match any
|
|
gesture made using left button.
|
|
|
|
[TIP]
|
|
You can find an event name with command `/input grab_mouse` then doing event
|
|
with mouse. This will insert event name on command line.
|
|
|
|
[[command_line]]
|
|
=== Command line
|
|
|
|
WeeChat command line (at the bottom of window) lets you execute commands or
|
|
send text to buffer.
|
|
|
|
[[command_line_syntax]]
|
|
==== Syntax
|
|
|
|
Commands begin with "/" char, followed by name of command. For example, to see
|
|
list of all options:
|
|
|
|
----
|
|
/set
|
|
----
|
|
|
|
Text sent to a buffer is any text that does not begin with "/" char.
|
|
For example, to send text 'hello' on current buffer:
|
|
|
|
----
|
|
hello
|
|
----
|
|
|
|
However, it is possible to start with "/" char, by adding another.
|
|
For example, to send text '/set' on current buffer:
|
|
|
|
----
|
|
//set
|
|
----
|
|
|
|
[[command_line_colors]]
|
|
==== Color codes
|
|
|
|
For some plugins like IRC, you can use color codes and attributes, as
|
|
follow (press key[ctrl-c] then following letter, with optional value):
|
|
|
|
key[ctrl-c,b]::
|
|
bold text
|
|
|
|
key[ctrl-c,c], key[xx]::
|
|
text color `xx` (see list of colors below)
|
|
|
|
key[ctrl-c,c], key[xx]key[,]key[yy]::
|
|
text color `xx` and background `yy` (see list of colors below)
|
|
|
|
key[ctrl-c,i]::
|
|
italic text
|
|
|
|
key[ctrl-c,o]::
|
|
disable color and attributes
|
|
|
|
key[ctrl-c,v]::
|
|
reverse video (revert text color with background)
|
|
|
|
key[ctrl-c,_]::
|
|
underlined text
|
|
|
|
[NOTE]
|
|
The same code (without number for key[ctrl-c,c]) may be used to stop the
|
|
attribute.
|
|
|
|
Color codes for key[ctrl-c,c] are:
|
|
|
|
include::autogen/user/irc_colors.asciidoc[]
|
|
|
|
[NOTE]
|
|
To show all available colors in your terminal, you can do `/color` then
|
|
key[alt-c] in WeeChat or run this command in terminal: `weechat --colors`.
|
|
|
|
Example: display of "hello everybody!" with "hello" in light blue bold and
|
|
"everybody" in light red underlined:
|
|
|
|
----
|
|
^Cc12^Cbhello ^Cb^Cc04^C_everybody^C_^Cc!
|
|
----
|
|
|
|
[NOTE]
|
|
In irc plugin, you can remap these colors using option
|
|
<<option_irc.color.mirc_remap,irc.color.mirc_remap>>.
|
|
|
|
[[colors]]
|
|
=== Colors
|
|
|
|
WeeChat can use up to 256 color pairs to display text in bars and chat area
|
|
(your terminal must support 256 colors to use them in WeeChat).
|
|
|
|
According to value of 'TERM' environment variable, you may have following limits
|
|
for colors in WeeChat:
|
|
|
|
[width="50%",cols="8,>2,>2",options="header"]
|
|
|===
|
|
| $TERM | Colors | Pairs ^(1)^
|
|
| "rxvt-unicode", "xterm", ... | 88 | 256
|
|
| "rxvt-256color", "xterm-256color", ... | 256 | 32767
|
|
| "screen" | 8 | 64
|
|
| "screen-256color" | 256 | 32767
|
|
|===
|
|
|
|
[NOTE]
|
|
^(1)^ Even if your terminal supports more than 256 pairs, only 256 pairs can be
|
|
used in WeeChat, because of a ncurses limitation.
|
|
|
|
You can run `weechat --colors` or use command `/color` in WeeChat to
|
|
display limits for your environment.
|
|
|
|
Some recommended values for 'TERM' if you want 256 colors:
|
|
|
|
* under screen: 'screen-256color'
|
|
* outside screen: 'xterm-256color', 'rxvt-256color', 'putty-256color', ...
|
|
|
|
[NOTE]
|
|
You may have to install package "ncurses-term" to use these values in 'TERM'
|
|
variable.
|
|
|
|
If you are using screen, you can add this line to your '~/.screenrc':
|
|
|
|
----
|
|
term screen-256color
|
|
----
|
|
|
|
If your 'TERM' variable has wrong value and that WeeChat is already running,
|
|
you can change it with these two commands:
|
|
|
|
----
|
|
/set env TERM screen-256color
|
|
/upgrade
|
|
----
|
|
|
|
[[colors_basic]]
|
|
==== Basic colors
|
|
|
|
Basic colors in WeeChat are:
|
|
|
|
[width="50%",cols="^3m,8",options="header"]
|
|
|===
|
|
| Name | Color
|
|
| default | Default terminal color (transparent for background)
|
|
| black | Black
|
|
| darkgray | Dark gray
|
|
| 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
|
|
| gray | Gray
|
|
| white | White
|
|
|===
|
|
|
|
[[colors_extended]]
|
|
==== Extended colors
|
|
|
|
WeeChat dynamically allocates color pairs when colors are used on screen (to
|
|
display buffers and bars).
|
|
|
|
In addition to basic colors, you can use a color number between 1 and the limit
|
|
of your terminal.
|
|
|
|
Use command `/color` to see current colors and limits. With key[alt-c] you can
|
|
temporarily switch to terminal colors to choose a color.
|
|
|
|
For example if you want to display time in orange in buffer, do:
|
|
|
|
----
|
|
/set weechat.color.chat_time 214
|
|
----
|
|
|
|
Or if you want a very dark green background for status bar:
|
|
|
|
----
|
|
/set weechat.bar.status.color_bg 22
|
|
----
|
|
|
|
[[colors_aliases]]
|
|
==== Aliases
|
|
|
|
You can add color aliases with command `/color alias` and then use this alias
|
|
in any color option.
|
|
|
|
For example:
|
|
|
|
----
|
|
/color alias 214 orange
|
|
/set weechat.color.chat_delimiters orange
|
|
----
|
|
|
|
[[colors_attributes]]
|
|
==== Attributes
|
|
|
|
It is possible to use some attributes for colors. One or more attributes can be
|
|
added before color name or number:
|
|
|
|
* `*` : bold text
|
|
* `!` : reverse video
|
|
* `/` : italic
|
|
* `_` : underlined text
|
|
* `|` : keep attributes: do not reset bold/reverse/italic/underlined when
|
|
changing color
|
|
|
|
For example if you want self nick as white underlined, do:
|
|
|
|
----
|
|
/set weechat.color.chat_nick_self _white
|
|
----
|
|
|
|
Or if you want time in status bar as orange underlined with bold:
|
|
|
|
----
|
|
/set weechat.color.status_time *_214
|
|
----
|
|
|
|
To use an attribute with default terminal color (-1), you must use a number
|
|
greater than last terminal color, for example max color in WeeChat: 99999.
|
|
|
|
Example of bold with terminal foreground color:
|
|
|
|
----
|
|
/set weechat.color.status_time *99999
|
|
----
|
|
|
|
[[secured_data]]
|
|
=== Secured data
|
|
|
|
[[secured_data_storage]]
|
|
==== Storage
|
|
|
|
WeeChat can encrypt passwords or private data using secured data, stored in file
|
|
'sec.conf'.
|
|
|
|
This configuration file is read before any other file, and the values stored
|
|
inside can be used in various WeeChat or plugins/scripts options.
|
|
|
|
You can set a passphrase to encrypt data in 'sec.conf'. This is not mandatory
|
|
but highly recommended, otherwise data is stored as plain text in file.
|
|
|
|
----
|
|
/secure passphrase this is my passphrase
|
|
----
|
|
|
|
When a passphrase is set, WeeChat will ask you to enter it on startup (but not
|
|
on `/upgrade`).
|
|
|
|
You can change this behavior and use a file with the passphrase (see option
|
|
<<option_sec.crypt.passphrase_file,sec.crypt.passphrase_file>>).
|
|
|
|
[[secured_data_encryption]]
|
|
===== Encryption
|
|
|
|
The encryption of data is made in 3 steps:
|
|
|
|
. Derive a key from the passphrase (with optional salt).
|
|
. Compute hash of data to encrypt.
|
|
. Encrypt the hash + data (output is: salt + encrypted hash/data).
|
|
|
|
[NOTE]
|
|
The cipher block mode is 'CFB'.
|
|
|
|
The result is put as hexadecimal string in file 'sec.conf', for example:
|
|
|
|
----
|
|
[data]
|
|
__passphrase__ = on
|
|
freenode = "53B1C86FCDA28FC122A95B0456ABD79B5AB74654F21C3D099A6CCA8173239EEA59533A1D83011251F96778AC3F5166A394"
|
|
----
|
|
|
|
[[secured_data_decryption]]
|
|
===== Decryption
|
|
|
|
The decryption of data is made in 3 steps:
|
|
|
|
. Derive a key using salt and passphrase.
|
|
. Decrypt hash + data.
|
|
. Check that decrypted hash == hash of data.
|
|
|
|
[[secured_data_manage]]
|
|
==== Manage secured data
|
|
|
|
To add secured data, use `/secure set`, for example a password for 'freenode'
|
|
IRC server:
|
|
|
|
----
|
|
/secure set freenode mypassword
|
|
----
|
|
|
|
For comfort, secured data can be displayed in a dedicated buffer (key[alt-v] on
|
|
buffer to see values), just do:
|
|
|
|
----
|
|
/secure
|
|
----
|
|
|
|
Secured data can be used in some options that can contain private data like
|
|
password, using this format: "${sec.data.xxx}" where "xxx" is the name of
|
|
secured data (used with `/secure set xxx ...`). +
|
|
For a complete list of supported options, see `/help secure`.
|
|
|
|
To use the 'freenode' password, for example with
|
|
<<irc_sasl_authentication,SASL authentication>>:
|
|
|
|
----
|
|
/set irc.server.freenode.sasl_password "${sec.data.freenode}"
|
|
----
|
|
|
|
[[options_and_commands]]
|
|
=== Options and commands
|
|
|
|
[[sec_options]]
|
|
==== Secured data options (sec.conf)
|
|
|
|
Sections:
|
|
|
|
[width="100%",cols="3m,6m,16",options="header"]
|
|
|===
|
|
| Section | Control command | Description
|
|
| crypt | /set sec.crypt.* | Options for encryption
|
|
| data | <<command_weechat_secure,/secure>> | Secured data
|
|
|===
|
|
|
|
Options:
|
|
|
|
include::autogen/user/sec_options.asciidoc[]
|
|
|
|
[[weechat_options]]
|
|
==== WeeChat options (weechat.conf)
|
|
|
|
Sections:
|
|
|
|
[width="100%",cols="3m,6m,16",options="header"]
|
|
|===
|
|
| Section | Control command | Description
|
|
| debug | <<command_weechat_debug,/debug set>> +
|
|
/set weechat.debug.* | Debug level, for core and plugins (options can be added/removed in section)
|
|
| startup | /set weechat.startup.* | Startup options
|
|
| look | /set weechat.look.* | Look and feel
|
|
| palette | <<command_weechat_color,/color alias>> +
|
|
/set weechat.palette.* | Color aliases (options can be added/removed in section)
|
|
| color | /set weechat.color.* | Colors
|
|
| completion | /set weechat.completion.* | Completion options
|
|
| history | /set weechat.history.* | History options (commands and buffers)
|
|
| proxy | <<command_weechat_proxy,/proxy>> +
|
|
/set weechat.proxy.* | Proxy options
|
|
| network | /set weechat.network.* | Network/SSL options
|
|
| bar | <<command_weechat_bar,/bar>> +
|
|
/set weechat.bar.* | Bar options
|
|
| layout | <<command_weechat_layout,/layout>> | Layouts
|
|
| notify | <<command_weechat_buffer,/buffer notify>> | Notify levels for buffers (options can be added/removed in section)
|
|
| filter | <<command_weechat_filter,/filter>> | Filters
|
|
| key | <<command_weechat_key,/key>> | Keys in default context
|
|
| key_search | <<command_weechat_key,/key>> | Keys in search context
|
|
| key_cursor | <<command_weechat_key,/key>> | Keys in cursor context
|
|
| key_mouse | <<command_weechat_key,/key>> | Keys in mouse context
|
|
|===
|
|
|
|
Options:
|
|
|
|
include::autogen/user/weechat_options.asciidoc[]
|
|
|
|
[[weechat_commands]]
|
|
==== WeeChat commands
|
|
|
|
include::autogen/user/weechat_commands.asciidoc[]
|
|
|
|
[[plugins]]
|
|
== Plugins
|
|
|
|
A plugin is a dynamic library, written in C and compiled, which is loaded by
|
|
WeeChat.
|
|
Under GNU/Linux, the file has ".so" extension, ".dll" under Windows.
|
|
|
|
Plugins found are automatically loaded when WeeChat is starting, and it is
|
|
possible to load or unload plugins while WeeChat is running.
|
|
|
|
It's important to make difference between a 'plugin' and a 'script': a
|
|
'plugin' is a binary file compiled and loaded with command `/plugin`, whereas
|
|
a 'script' is a text file loaded with a plugin like 'python' with command
|
|
`/python`.
|
|
|
|
You can use command `/plugin` to load/unload a plugin, or list all loaded
|
|
plugins.
|
|
When a plugin is unloaded, all buffers created by this plugin are
|
|
automatically closed.
|
|
|
|
Examples to load, unload or list plugins:
|
|
|
|
----
|
|
/plugin load irc
|
|
/plugin unload irc
|
|
/plugin list
|
|
----
|
|
|
|
Default plugins are:
|
|
|
|
[width="100%",cols="^1,5",options="header"]
|
|
|===
|
|
| Plugin | Description
|
|
| alias | Define alias for commands
|
|
| aspell | Spell checking for command line
|
|
| charset | Charset decoding/encoding for buffers
|
|
| exec | Execution of external commands in WeeChat
|
|
| fifo | FIFO pipe used to remotely send commands to WeeChat
|
|
| irc | IRC chat protocol
|
|
| logger | Log buffers to files
|
|
| relay | Relay data via network
|
|
| script | Scripts manager
|
|
| python | Python scripting API
|
|
| perl | Perl scripting API
|
|
| ruby | Ruby scripting API
|
|
| lua | Lua scripting API
|
|
| tcl | Tcl scripting API
|
|
| guile | Guile (scheme) scripting API
|
|
| javascript | Javascript scripting API
|
|
| trigger | Text replacement and command execution on events triggered by WeeChat/plugins
|
|
| xfer | File transfer and direct chat
|
|
|===
|
|
|
|
To learn more about plugin or script development (through API), please read
|
|
'WeeChat Plugin API Reference' or 'WeeChat Scripting Guide'.
|
|
|
|
[[alias_plugin]]
|
|
=== Alias plugin
|
|
|
|
Alias plugin lets you create alias for commands (from WeeChat or other
|
|
plugins).
|
|
|
|
[[alias_commands]]
|
|
==== Commands
|
|
|
|
include::autogen/user/alias_commands.asciidoc[]
|
|
|
|
[[aspell_plugin]]
|
|
=== Aspell plugin
|
|
|
|
Aspell plugin lets you check spelling in command line. It is possible to use
|
|
many languages by buffer.
|
|
|
|
[[aspell_options]]
|
|
==== Options (aspell.conf)
|
|
|
|
Sections:
|
|
|
|
[width="100%",cols="3m,6m,16",options="header"]
|
|
|===
|
|
| Section | Control command | Description
|
|
| color | /set aspell.color.* | Colors
|
|
| check | /set aspell.check.* | Options to control spell checking
|
|
| dict | <<command_aspell_aspell,/aspell setdict>> +
|
|
/set aspell.dict.* | Dictionaries used by buffer (options can be added/removed in section)
|
|
| option | /set aspell.option.* | <<aspell_speller_options,Speller options>> (options can be added/removed in section)
|
|
|===
|
|
|
|
Options:
|
|
|
|
include::autogen/user/aspell_options.asciidoc[]
|
|
|
|
[[aspell_commands]]
|
|
==== Commands
|
|
|
|
include::autogen/user/aspell_commands.asciidoc[]
|
|
|
|
[[aspell_speller_options]]
|
|
==== Speller options
|
|
|
|
Speller options can be defined by adding options in section "option" of aspell
|
|
configuration.
|
|
|
|
The option name is an aspell configuration option. List of options can be found
|
|
in a shell with following command:
|
|
|
|
----
|
|
$ aspell config
|
|
----
|
|
|
|
For example, to enable option "ignore-case":
|
|
|
|
----
|
|
/set aspell.option.ignore-case "true"
|
|
----
|
|
|
|
[[aspell_suggestions]]
|
|
==== Suggestions
|
|
|
|
Suggestions are displayed in a bar item called "aspell_suggest". The number of
|
|
suggestions is set in option 'aspell.check.suggestions'.
|
|
|
|
To enable suggestions you must set option 'aspell.check.suggestions' to an
|
|
integer ≥ 0 and add the bar item "aspell_suggest" to a bar, like 'status'.
|
|
|
|
Example of suggestions with English dictionary (`en`):
|
|
|
|
....
|
|
│[12:55] [6] [irc/freenode] 3:#test(+n){4} [print,prone,prune] │
|
|
│[@Flashy] prinr █ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
....
|
|
|
|
Example of suggestions with English and French dictionaries (`en,fr`):
|
|
|
|
....
|
|
│[12:55] [6] [irc/freenode] 3:#test(+n){4} [print,prone,prune/prime,primer,primé] │
|
|
│[@Flashy] prinr █ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
....
|
|
|
|
[[charset_plugin]]
|
|
=== Charset plugin
|
|
|
|
Charset plugin lets you decode or encode data using charsets.
|
|
|
|
There is default charset for decode/encode, and specific charsets for buffers
|
|
(or group of buffers).
|
|
|
|
This plugin is optional, but recommended: if it's not loaded, WeeChat
|
|
can only read/write UTF-8 data.
|
|
|
|
Charset plugin should be autoloaded by WeeChat. To be sure plugin is loaded,
|
|
try:
|
|
|
|
----
|
|
/charset
|
|
----
|
|
|
|
If command is not found, then load plugin with command:
|
|
|
|
----
|
|
/plugin load charset
|
|
----
|
|
|
|
If plugin is not found, then you should compile again WeeChat with
|
|
plugins and Charset support.
|
|
|
|
When Charset plugin starts, it displays terminal and internal charsets.
|
|
Terminal charset depends on your locale, and internal is UTF-8.
|
|
|
|
For example:
|
|
|
|
....
|
|
charset: terminal: ISO-8859-15, internal: UTF-8
|
|
....
|
|
|
|
[[charset_options]]
|
|
==== Options (charset.conf)
|
|
|
|
Sections:
|
|
|
|
[width="100%",cols="3m,6m,16",options="header"]
|
|
|===
|
|
| Section | Control command | Description
|
|
| default | /set charset.default.* | Default decoding/encoding charset
|
|
| decode | <<command_charset_charset,/charset decode>> +
|
|
/set charset.decode.* | Decoding charset by buffer (options can be added/removed in section)
|
|
| encode | <<command_charset_charset,/charset encode>> +
|
|
/set charset.encode.* | Encoding charset by buffer (options can be added/removed in section)
|
|
|===
|
|
|
|
Options:
|
|
|
|
include::autogen/user/charset_options.asciidoc[]
|
|
|
|
[[charset_commands]]
|
|
==== Commands
|
|
|
|
include::autogen/user/charset_commands.asciidoc[]
|
|
|
|
[[charset_set]]
|
|
==== Set charset
|
|
|
|
To set global decode and encode charsets, use command `/set`.
|
|
|
|
For example:
|
|
|
|
----
|
|
/set charset.default.decode ISO-8859-15
|
|
/set charset.default.encode ISO-8859-15
|
|
----
|
|
|
|
If global decode charset is not set (for example during first
|
|
load of Charset plugin), it will be automatically set to terminal
|
|
charset (if it's different from UTF-8), or by default to 'ISO-8859-1'.
|
|
|
|
Default encode value is empty, so it sends by default with
|
|
internal charset (UTF-8).
|
|
|
|
To set IRC server charset, use command `/charset` on server buffer.
|
|
If you give only charset, then it will set decoding and encoding values.
|
|
|
|
For example:
|
|
|
|
----
|
|
/charset ISO-8859-15
|
|
----
|
|
|
|
It's equivalent to:
|
|
|
|
----
|
|
/charset decode ISO-8859-15
|
|
/charset encode ISO-8859-15
|
|
----
|
|
|
|
To set IRC channel (or private) charset, use same commands as server,
|
|
but on channel (or private) buffer.
|
|
|
|
To set charset for all channels/privates of an IRC server:
|
|
|
|
----
|
|
/set charset.encode.irc.freenode ISO-8859-15
|
|
----
|
|
|
|
To see all charsets used, use following command:
|
|
|
|
----
|
|
/set charset.*
|
|
----
|
|
|
|
[[charset_troubleshooting]]
|
|
==== Troubleshooting
|
|
|
|
For any problem with charsets, please look at 'WeeChat FAQ'.
|
|
|
|
[[exec_plugin]]
|
|
=== Exec plugin
|
|
|
|
The `/exec` command lets you execute external commands inside WeeChat and
|
|
display the output locally, or send it to a buffer.
|
|
|
|
[[exec_options]]
|
|
==== Options (exec.conf)
|
|
|
|
Sections:
|
|
|
|
[width="100%",cols="3m,6m,16",options="header"]
|
|
|===
|
|
| Section | Control command | Description
|
|
| command | /set exec.command.* | Options for commands
|
|
| color | /set exec.color.* | Colors
|
|
|===
|
|
|
|
Options:
|
|
|
|
include::autogen/user/exec_options.asciidoc[]
|
|
|
|
[[exec_commands]]
|
|
==== Commands
|
|
|
|
include::autogen/user/exec_commands.asciidoc[]
|
|
|
|
[[fifo_plugin]]
|
|
=== Fifo plugin
|
|
|
|
You can remote control WeeChat, by sending commands or text to a FIFO pipe (if
|
|
option "plugins.var.fifo.fifo" is enabled, it is by default).
|
|
|
|
The FIFO pipe is located in '~/.weechat/' and is called 'weechat_fifo_xxxx'
|
|
(where 'xxxx' is the process ID (PID) of running WeeChat).
|
|
|
|
Syntax for the FIFO pipe commands/text is one of following:
|
|
|
|
....
|
|
plugin.buffer *text or command here
|
|
*text or command here
|
|
....
|
|
|
|
Some examples:
|
|
|
|
* nick change on IRC server freenode to "newnick":
|
|
|
|
----
|
|
$ echo 'irc.server.freenode */nick newnick' >~/.weechat/weechat_fifo_12345
|
|
----
|
|
|
|
* display text on IRC #weechat channel:
|
|
|
|
----
|
|
$ echo 'irc.freenode.#weechat *hello!' >~/.weechat/weechat_fifo_12345
|
|
----
|
|
|
|
* display text on current buffer:
|
|
|
|
----
|
|
$ echo '*hello!' >~/.weechat/weechat_fifo_12345
|
|
----
|
|
|
|
* send two commands to unload/reload Python scripts (you have to separate them
|
|
with "\n"):
|
|
|
|
----
|
|
$ printf '%b' '*/python unload\n*/python autoload\n' >~/.weechat/weechat_fifo_12345
|
|
----
|
|
|
|
You can write a script to send command to all running WeeChat at same time,
|
|
for example:
|
|
|
|
[source,shell]
|
|
----
|
|
#!/bin/sh
|
|
if [ $# -eq 1 ]; then
|
|
for fifo in ~/.weechat/weechat_fifo_*
|
|
do
|
|
printf '%b\n' "$1" >"$fifo"
|
|
done
|
|
fi
|
|
----
|
|
|
|
If the script is called "auto_weechat_command", you can run it with:
|
|
|
|
----
|
|
$ ./auto_weechat_command 'irc.freenode.#weechat *hello'
|
|
----
|
|
|
|
[[irc_plugin]]
|
|
=== IRC plugin
|
|
|
|
The IRC plugin is designed to chat through IRC protocol with other people.
|
|
|
|
It is multi-servers, and offers all supported IRC commands including DCC chat
|
|
and file transfer (via xfer plugin, see <<xfer_plugin,Xfer plugin>>).
|
|
|
|
[[irc_command_line_options]]
|
|
==== Command line options
|
|
|
|
It is possible to give URL for one or many IRC servers, as follow:
|
|
|
|
----
|
|
irc[6][s]://[nick[:password]@]irc.example.org[:port][/channel][,channel[...]]
|
|
----
|
|
|
|
Example to join '#weechat' and '#toto' on server 'chat.freenode.net' server,
|
|
default port (6667), with nick 'nono':
|
|
|
|
----
|
|
$ weechat irc://nono@chat.freenode.net/#weechat,#toto
|
|
----
|
|
|
|
[[irc_options]]
|
|
==== Options (irc.conf)
|
|
|
|
Sections:
|
|
|
|
[width="100%",cols="3m,6m,16",options="header"]
|
|
|===
|
|
| Section | Control command | Description
|
|
| look | /set irc.look.* | Look and feel
|
|
| color | /set irc.color.* | Colors
|
|
| network | /set irc.network.* | Network options
|
|
| msgbuffer | /set irc.msgbuffer.* | <<irc_target_buffer,Target buffer for IRC messages>> (options can be added/removed in section)
|
|
| ctcp | /set irc.ctcp.* | <<irc_ctcp_replies,CTCP replies>> (options can be added/removed in section)
|
|
| ignore | <<command_irc_ignore,/ignore>> | Ignore people
|
|
| server_default | /set irc.server_default.* | Default values for servers (used when options in server are not defined)
|
|
| server | <<command_irc_server,/server>> +
|
|
/set irc.server.* | Servers
|
|
|===
|
|
|
|
Options:
|
|
|
|
include::autogen/user/irc_options.asciidoc[]
|
|
|
|
[[irc_commands]]
|
|
==== Commands
|
|
|
|
include::autogen/user/irc_commands.asciidoc[]
|
|
|
|
[[irc_ssl_certificates]]
|
|
==== SSL certificates
|
|
|
|
When connecting to IRC server with SSL, WeeChat checks by default that the
|
|
connection is fully trusted.
|
|
|
|
Some options are used to control SSL connection:
|
|
|
|
weechat.network.gnutls_ca_file::
|
|
path to file with certificate authorities (by default: "%h/ssl/CAs.pem")
|
|
|
|
irc.server.xxx.ssl_cert::
|
|
SSL certificate file used to automatically identify your nick (for example
|
|
CertFP on oftc, see below)
|
|
|
|
irc.server.xxx.ssl_dhkey_size::
|
|
size of the key used during the Diffie-Hellman Key Exchange (by default:
|
|
2048)
|
|
|
|
irc.server.xxx.ssl_verify::
|
|
check that the SSL connection is fully trusted (on by default)
|
|
|
|
[NOTE]
|
|
Option "ssl_verify" is on by default, so verification is strict and may fail,
|
|
even if it was OK with versions prior to 0.3.1.
|
|
|
|
[[irc_connect_oftc_with_certificate]]
|
|
===== First example: connect to oftc and check certificate
|
|
|
|
* Import certificate in shell:
|
|
|
|
----
|
|
$ mkdir -p ~/.weechat/ssl
|
|
$ wget -O ~/.weechat/ssl/CAs.pem http://www.spi-inc.org/ca/spi-cacert.crt
|
|
----
|
|
|
|
Note: it is possible to concatenate many certificates in file CAs.pem.
|
|
|
|
* In WeeChat, with "oftc" server already added:
|
|
|
|
----
|
|
/connect oftc
|
|
----
|
|
|
|
[[irc_connect_oftc_with_certfp]]
|
|
===== Second example: connect to oftc using CertFP
|
|
|
|
* Create certificate in shell:
|
|
|
|
----
|
|
$ mkdir -p ~/.weechat/ssl
|
|
$ cd ~/.weechat/ssl
|
|
$ openssl req -nodes -newkey rsa:2048 -keyout nick.pem -x509 -days 365 -out nick.pem
|
|
----
|
|
|
|
* In WeeChat, with "oftc" server already added:
|
|
|
|
----
|
|
/set irc.server.oftc.ssl_cert "%h/ssl/nick.pem"
|
|
/connect oftc
|
|
/msg nickserv cert add
|
|
----
|
|
|
|
For more information, look at http://www.oftc.net/oftc/NickServ/CertFP
|
|
|
|
[[irc_sasl_authentication]]
|
|
==== SASL authentication
|
|
|
|
WeeChat supports SASL authentication, using different mechanisms:
|
|
|
|
* 'plain': plain text password (default)
|
|
* 'ecdsa-nist256p-challenge': challenge with public/private key
|
|
* 'external': client side SSL cert
|
|
* 'dh-blowfish': blowfish encrypted password
|
|
* 'dh-aes': AES encrypted password
|
|
|
|
[NOTE]
|
|
The "gcrypt" library is required when compiling WeeChat in order to use
|
|
"dh-blowfish" and "dh-aes" mechanisms (see <<dependencies,dependencies>>).
|
|
|
|
Options in servers are:
|
|
|
|
* 'sasl_mechanism': mechanism to use (see above)
|
|
* 'sasl_timeout': timeout (in seconds) for authentication
|
|
* 'sasl_fail': action to perform if authentication fails
|
|
* 'sasl_username': username (nick)
|
|
* 'sasl_password': password
|
|
* 'sasl_key': file with ECC private key (for mechanism
|
|
'ecdsa-nist256p-challenge')
|
|
|
|
[[irc_sasl_ecdsa_nist256p_challenge]]
|
|
===== SASL ECDSA-NIST256P-CHALLENGE
|
|
|
|
You must generate a private key in order to authentify with the
|
|
ECDSA-NIST256P-CHALLENGE mechanism (no password is required on connection).
|
|
|
|
You can generate the key with this command:
|
|
|
|
----
|
|
$ openssl ecparam -genkey -name prime256v1 >~/.weechat/ecdsa.pem
|
|
----
|
|
|
|
Get the public key (encoded as base64) with this command:
|
|
|
|
----
|
|
$ openssl ec -noout -text -conv_form compressed -in ~/.weechat/ecdsa.pem | grep '^pub:' -A 3 | tail -n 3 | tr -d ' \n:' | xxd -r -p | base64
|
|
----
|
|
|
|
Connect to the server, identify (for example with "nickserv identify") and set
|
|
your public key in your account, using nickserv (replace the base64 value with
|
|
your public key):
|
|
|
|
----
|
|
/connect freenode
|
|
/msg nickserv identify your_password
|
|
/msg nickserv set pubkey Av8k1FOGetUDq7sPMBfufSIZ5c2I/QYWgiwHtNXkVe/q
|
|
----
|
|
|
|
Configure the SASL options in the server:
|
|
|
|
----
|
|
/set irc.server.freenode.sasl_mechanism ecdsa-nist256p-challenge
|
|
/set irc.server.freenode.sasl_username "your_nickname"
|
|
/set irc.server.freenode.sasl_key "%h/ecdsa.pem"
|
|
----
|
|
|
|
Reconnect to the server:
|
|
|
|
----
|
|
/reconnect freenode
|
|
----
|
|
|
|
[[irc_tor_freenode]]
|
|
==== Connect to Freenode with TOR/SASL
|
|
|
|
In addition to SSL, Freenode servers support connections with TOR
|
|
(https://www.torproject.org/), a network of virtual tunnels that allows people
|
|
and groups to improve their privacy and security on the Internet.
|
|
|
|
In first place, install TOR. For Debian (and derived):
|
|
|
|
----
|
|
$ sudo apt-get install tor
|
|
----
|
|
|
|
In WeeChat you need to add a socks5 proxy for TOR service (hostname/IP and
|
|
port depend on your TOR configuration):
|
|
|
|
----
|
|
/proxy add tor socks5 127.0.0.1 9050
|
|
----
|
|
|
|
Now, add a new server, for example:
|
|
|
|
----
|
|
/server add freenode-tor p4fsi4ockecnea7l.onion
|
|
----
|
|
|
|
Set proxy for TOR:
|
|
|
|
----
|
|
/set irc.server.freenode-tor.proxy "tor"
|
|
----
|
|
|
|
Set SASL authentication:
|
|
|
|
----
|
|
/set irc.server.freenode-tor.sasl_username "your_nickname"
|
|
/set irc.server.freenode-tor.sasl_password "your_password"
|
|
----
|
|
|
|
And finally, connection to server:
|
|
|
|
----
|
|
/connect freenode-tor
|
|
----
|
|
|
|
For more info about Freenode and TOR: http://freenode.net/irc_servers.shtml#tor
|
|
|
|
[[irc_smart_filter_join_part_quit]]
|
|
==== Smart filter for join/part/quit messages
|
|
|
|
A smart filter is available to filter join/part/quit messages when nick did not
|
|
say something during past X minutes on channel.
|
|
|
|
Smart filter is enabled by default, but you must add a filter to hide lines on
|
|
buffers, for example:
|
|
|
|
----
|
|
/filter add irc_smart * irc_smart_filter *
|
|
----
|
|
|
|
It is possible to create filter for one channel only or channels beginning with
|
|
same name (see `/help filter`):
|
|
|
|
----
|
|
/filter add irc_smart_weechat irc.freenode.#weechat irc_smart_filter *
|
|
/filter add irc_smart_weechats irc.freenode.#weechat* irc_smart_filter *
|
|
----
|
|
|
|
You can hide only join or part/quit with following options:
|
|
|
|
----
|
|
/set irc.look.smart_filter_join on
|
|
/set irc.look.smart_filter_quit on
|
|
----
|
|
|
|
You can setup delay (in minutes):
|
|
|
|
----
|
|
/set irc.look.smart_filter_delay 5
|
|
----
|
|
|
|
If a nick did not speak during last 5 minutes, its join and/or part/quit will be
|
|
hidden on channel.
|
|
|
|
[[irc_ctcp_replies]]
|
|
==== CTCP replies
|
|
|
|
It is possible to customize CTCP replies, or block some CTCP queries (do not
|
|
reply).
|
|
|
|
For example, to customize reply to CTCP "VERSION", use following command:
|
|
|
|
----
|
|
/set irc.ctcp.version "I'm running WeeChat $version, it rocks!"
|
|
----
|
|
|
|
If you want to block CTCP "VERSION" (do not reply to a query), then set empty
|
|
string:
|
|
|
|
----
|
|
/set irc.ctcp.version ""
|
|
----
|
|
|
|
Even unknown CTCP can be customized, for example you can reply to
|
|
CTCP "BLABLA":
|
|
|
|
----
|
|
/set irc.ctcp.blabla "This is my answer to CTCP BLABLA"
|
|
----
|
|
|
|
It is possible to customize CTCP for one server only, using its internal name
|
|
before CTCP name:
|
|
|
|
----
|
|
/set irc.ctcp.freenode.version "WeeChat $version (for freenode)"
|
|
----
|
|
|
|
If you want to restore standard CTCP reply, then remove option:
|
|
|
|
----
|
|
/unset irc.ctcp.version
|
|
----
|
|
|
|
Following codes can be used in strings and are automatically expanded by WeeChat
|
|
when replying to CTCP:
|
|
|
|
[width="100%",cols="^2l,4,8",options="header"]
|
|
|===
|
|
| Code | Description | Value/example
|
|
| $clientinfo | List of supported CTCP | `ACTION DCC CLIENTINFO FINGER PING SOURCE TIME USERINFO VERSION`
|
|
| $version | WeeChat version | `0.4.0-dev`
|
|
| $versiongit | WeeChat version + git version ^(1)^ | `0.4.0-dev (git: v0.3.9-104-g7eb5cc4)`
|
|
| $git | Git version ^(1)^ | `v0.3.9-104-g7eb5cc4`
|
|
| $compilation | WeeChat compilation date | `Dec 16 2012`
|
|
| $osinfo | Info about OS | `Linux 2.6.32-5-amd64 / x86_64`
|
|
| $site | WeeChat site | `https://weechat.org/`
|
|
| $download | WeeChat site, download page | `https://weechat.org/download`
|
|
| $time | Current date/time | `Sun, 16 Dec 2012 10:40:48 +0100`
|
|
| $username | User name on IRC server | `name`
|
|
| $realname | Real name on IRC server | `John Doe`
|
|
|===
|
|
|
|
[NOTE]
|
|
^(1)^ The git version is the output of command `git describe`. It is known only
|
|
if WeeChat has been compiled inside the git repository and if git was installed.
|
|
|
|
If CTCP options are not defined (by default), CTCP replies are:
|
|
|
|
[width="100%",cols="^2,4,8",options="header"]
|
|
|===
|
|
| CTCP | Reply format | Example
|
|
| CLIENTINFO | `$clientinfo` | `ACTION DCC CLIENTINFO FINGER PING SOURCE TIME USERINFO VERSION`
|
|
| FINGER | `WeeChat $versiongit` | `WeeChat 0.4.0-dev (git: v0.3.9-104-g7eb5cc4)`
|
|
| SOURCE | `$download` | `https://weechat.org/download`
|
|
| TIME | `$time` | `Sun, 16 Dec 2012 10:40:48 +0100`
|
|
| USERINFO | `$username ($realname)` | `name (John Doe)`
|
|
| VERSION | `WeeChat $versiongit ($compilation)` | `WeeChat 0.4.0-dev (git: v0.3.9-104-g7eb5cc4) (Dec 16 2012)`
|
|
|===
|
|
|
|
[[irc_target_buffer]]
|
|
==== Target buffer for IRC messages
|
|
|
|
It is possible to customize target buffer for IRC messages (buffer used to
|
|
display message) with options `irc.msgbuffer.*`.
|
|
|
|
For some IRC messages (see list below), you can use value:
|
|
|
|
current::
|
|
current buffer (if it's IRC buffer, or on server buffer by default)
|
|
|
|
private::
|
|
private buffer for nick, or current/server buffer if not found (according
|
|
to option 'irc.look.msgbuffer_fallback')
|
|
|
|
server::
|
|
server buffer
|
|
|
|
weechat::
|
|
WeeChat "core" buffer
|
|
|
|
When option is not set (default), WeeChat chooses appropriate buffer, commonly
|
|
server or channel buffer.
|
|
|
|
Non-comprehensive list of IRC messages or alias that you can customize:
|
|
|
|
[width="60%",cols="^1m,^3m,8",options="header"]
|
|
|===
|
|
| message | alias | description
|
|
| error | | error
|
|
| invite | | invited on a channel
|
|
| join | | join
|
|
| kick | | kick
|
|
| kill | | kill
|
|
| mode | | mode
|
|
| notice | | notice
|
|
| part | | part
|
|
| quit | | quit
|
|
| topic | | topic
|
|
| wallops | | wallops
|
|
| | ctcp | ctcp (sent or received, in a privmsg or notice message)
|
|
| 221 | | user mode string
|
|
| 275 | whois | whois (secure connection)
|
|
| 301 | whois | whois (away)
|
|
| 303 | | ison
|
|
| 305 | unaway | unaway
|
|
| 306 | away | away
|
|
| 307 | whois | whois (registered nick)
|
|
| 310 | whois | whois (help mode)
|
|
| 311 | whois | whois (user)
|
|
| 312 | whois | whois (server)
|
|
| 313 | whois | whois (operator)
|
|
| 314 | whowas | whowas
|
|
| 315 | who | who (end)
|
|
| 317 | whois | whois (idle)
|
|
| 318 | whois | whois (end)
|
|
| 319 | whois | whois (channels)
|
|
| 320 | whois | whois (identified user)
|
|
| 321 | list | list (start)
|
|
| 322 | list | list (channel)
|
|
| 323 | list | list (end)
|
|
| 326 | whois | whois (has oper privs)
|
|
| 327 | whois | whois (host)
|
|
| 328 | | channel URL
|
|
| 329 | | channel creation date
|
|
| 330 | whois | whois (logged in as)
|
|
| 331 | | no topic for channel
|
|
| 332 | | topic of channel
|
|
| 333 | | infos about topic
|
|
| 335 | whois | whois (is a bot on)
|
|
| 338 | whois | whois (host)
|
|
| 341 | | inviting
|
|
| 343 | whois | whois (is opered as)
|
|
| 344 | reop | channel reop
|
|
| 345 | reop | channel reop (end)
|
|
| 346 | invitelist | invite list
|
|
| 347 | invitelist | invite list (end)
|
|
| 348 | exceptionlist | exception list
|
|
| 349 | exceptionlist | exception list (end)
|
|
| 351 | | server version
|
|
| 352 | who | who
|
|
| 353 | names | list of users on channel
|
|
| 366 | names | end of /names list
|
|
| 367 | banlist | ban list
|
|
| 368 | banlist | end of ban list
|
|
| 369 | whowas | whowas (end)
|
|
| 378 | whois | whois (connecting from)
|
|
| 379 | whois | whois (using modes)
|
|
| 401 | whois | no such nick/channel
|
|
| 402 | whois | no such server
|
|
| 432 | | erroneous nickname
|
|
| 433 | | nickname already in use
|
|
| 438 | | not authorized to change nickname
|
|
| 671 | whois | whois (secure connection)
|
|
| 728 | quietlist | quiet list
|
|
| 729 | quietlist | end of quiet list
|
|
| 732 | monitor | list of monitored nicks
|
|
| 733 | monitor | list of monitored nicks (end)
|
|
| 901 | | you are now logged in
|
|
|===
|
|
|
|
Other numeric commands can be customized as well.
|
|
|
|
Message can be prefixed by server name to be specific to an irc server
|
|
(for example: `freenode.whois`).
|
|
|
|
Some examples:
|
|
|
|
* display result of `/whois` on private buffer:
|
|
|
|
----
|
|
/set irc.msgbuffer.whois private
|
|
----
|
|
|
|
* restore default buffer for whois (server buffer):
|
|
|
|
----
|
|
/unset irc.msgbuffer.whois
|
|
----
|
|
|
|
* display invitation on current buffer, only for "freenode" server:
|
|
|
|
----
|
|
/set irc.msgbuffer.freenode.invite current
|
|
----
|
|
|
|
* display message "303" (ison) on WeeChat "core" buffer:
|
|
|
|
----
|
|
/set irc.msgbuffer.303 weechat
|
|
----
|
|
|
|
[[logger_plugin]]
|
|
=== Logger plugin
|
|
|
|
The Logger plugin lets you save content of buffers to files, with options
|
|
about what and how it is saved.
|
|
|
|
[[logger_options]]
|
|
==== Options (logger.conf)
|
|
|
|
Sections:
|
|
|
|
[width="100%",cols="3m,6m,16",options="header"]
|
|
|===
|
|
| Section | Control command | Description
|
|
| look | /set logger.look.* | Look and feel
|
|
| color | /set logger.color.* | Colors
|
|
| file | /set logger.file.* | Options for log files
|
|
| level | /set logger.level.* | Log level by buffer (options can be added/removed in section)
|
|
| mask | /set logger.mask.* | Filename mask by buffer (options can be added/removed in section)
|
|
|===
|
|
|
|
Options:
|
|
|
|
include::autogen/user/logger_options.asciidoc[]
|
|
|
|
[[logger_commands]]
|
|
==== Commands
|
|
|
|
include::autogen/user/logger_commands.asciidoc[]
|
|
|
|
[[logger_log_levels]]
|
|
==== Log levels
|
|
|
|
Logging is made with a level for each buffer. Default level is 9 (log
|
|
all messages displayed on buffer).
|
|
You can change level for one buffer, or a group of buffers.
|
|
|
|
Possible levels are 0 to 9. Zero means "do not log anything" and 9 means
|
|
"log all messages".
|
|
|
|
Plugins are using different levels for messages displayed.
|
|
IRC plugin uses following levels:
|
|
|
|
* level 1: message from user (on channel or private)
|
|
* level 2: nick change (you or someone else)
|
|
* level 3: any server message (except join/part/quit)
|
|
* level 4: server message join/part/quit
|
|
|
|
So if you set level 3 for an IRC channel, WeeChat will log all messages,
|
|
but not join/part/quit.
|
|
|
|
Some examples:
|
|
|
|
* set level 3 for IRC channel #weechat:
|
|
|
|
----
|
|
/set logger.level.irc.freenode.#weechat 3
|
|
----
|
|
|
|
* set level 3 for freenode server buffer:
|
|
|
|
----
|
|
/set logger.level.irc.server.freenode 3
|
|
----
|
|
|
|
* set level 3 for all channels on server freenode:
|
|
|
|
----
|
|
/set logger.level.irc.freenode 3
|
|
----
|
|
|
|
* set level 2 for all IRC buffers:
|
|
|
|
----
|
|
/set logger.level.irc 2
|
|
----
|
|
|
|
[[logger_filenames_masks]]
|
|
==== Filenames masks
|
|
|
|
It is possible to define a filename mask for each buffer, and use local buffer
|
|
variables to build filename. To see local variables for current buffer:
|
|
|
|
----
|
|
/buffer localvar
|
|
----
|
|
|
|
For example, on buffer "irc.freenode.#weechat", WeeChat will search a mask with
|
|
option name, in this order:
|
|
|
|
----
|
|
logger.mask.irc.freenode.#weechat
|
|
logger.mask.irc.freenode
|
|
logger.mask.irc
|
|
logger.file.mask
|
|
----
|
|
|
|
That means you can have masks specific for some IRC servers
|
|
("logger.mask.irc.freenode") or for a plugin ("logger.mask.irc").
|
|
|
|
[[logger_files_by_date]]
|
|
===== Log files by date
|
|
|
|
To have log files by date, you can use date/time specifiers in mask (see
|
|
`man strftime` for formats), for example:
|
|
|
|
----
|
|
/set logger.file.mask "%Y/%m/$plugin.$name.weechatlog"
|
|
----
|
|
|
|
You'll have following files:
|
|
|
|
....
|
|
~/.weechat/
|
|
|--- logs/
|
|
|--- 2010/
|
|
|--- 11/
|
|
| irc.server.freenode.weechatlog
|
|
| irc.freenode.#weechat.weechatlog
|
|
|--- 2010/
|
|
|--- 12/
|
|
| irc.server.freenode.weechatlog
|
|
| irc.freenode.#weechat.weechatlog
|
|
....
|
|
|
|
[[logger_irc_files_by_server_channel]]
|
|
===== IRC log files by server and channel
|
|
|
|
If you want one directory by IRC server and one file by channel inside:
|
|
|
|
----
|
|
/set logger.mask.irc "irc/$server/$channel.weechatlog"
|
|
----
|
|
|
|
You'll have following files:
|
|
|
|
....
|
|
~/.weechat/
|
|
|--- logs/
|
|
|--- irc/
|
|
|--- freenode/
|
|
| freenode.weechatlog
|
|
| #weechat.weechatlog
|
|
| #mychan.weechatlog
|
|
|--- oftc/
|
|
| oftc.weechatlog
|
|
| #chan1.weechatlog
|
|
| #chan2.weechatlog
|
|
....
|
|
|
|
[[relay_plugin]]
|
|
=== Relay plugin
|
|
|
|
The Relay plugin is used to relay data via network, using different protocols:
|
|
|
|
* 'irc': IRC proxy: used to share connections to IRC servers with one or many
|
|
other IRC clients
|
|
* 'weechat': protocol used by remote interfaces to display and interact with
|
|
WeeChat (for example QWeeChat or weechat-android)
|
|
|
|
[[relay_options]]
|
|
==== Options (relay.conf)
|
|
|
|
Sections:
|
|
|
|
[width="100%",cols="3m,6m,16",options="header"]
|
|
|===
|
|
| Section | Control command | Description
|
|
| look | /set relay.look.* | Look and feel
|
|
| color | /set relay.color.* | Colors
|
|
| network | /set relay.network.* | Network options
|
|
| irc | /set relay.irc.* | Options specific to irc protocol (irc proxy)
|
|
| port | <<command_relay_relay,/relay add>> +
|
|
/set relay.port.* | Ports used for relay (irc and weechat protocols) (options can be added/removed in section)
|
|
|===
|
|
|
|
Options:
|
|
|
|
include::autogen/user/relay_options.asciidoc[]
|
|
|
|
[[relay_commands]]
|
|
==== Commands
|
|
|
|
include::autogen/user/relay_commands.asciidoc[]
|
|
|
|
[[relay_password]]
|
|
==== Password
|
|
|
|
It is highly recommended to set a password for relay, with command:
|
|
|
|
----
|
|
/set relay.network.password "mypassword"
|
|
----
|
|
|
|
This password is used for 'irc' and 'weechat' protocols.
|
|
|
|
[[relay_ssl]]
|
|
==== SSL
|
|
|
|
You can use SSL by creating a certificate and private key, and by using prefix
|
|
"ssl." in the name of protocol.
|
|
|
|
The default file for certificate/key is '~/.weechat/ssl/relay.pem'
|
|
(option <<option_relay.network.ssl_cert_key,relay.network.ssl_cert_key>>).
|
|
|
|
You can create a certificate and private key with following commands:
|
|
|
|
----
|
|
$ mkdir -p ~/.weechat/ssl
|
|
$ cd ~/.weechat/ssl
|
|
$ openssl req -nodes -newkey rsa:2048 -keyout relay.pem -x509 -days 365 -out relay.pem
|
|
----
|
|
|
|
If WeeChat is already running, you can reload the certificate and private key
|
|
with command:
|
|
|
|
----
|
|
/relay sslcertkey
|
|
----
|
|
|
|
[[relay_irc_proxy]]
|
|
==== IRC proxy
|
|
|
|
The Relay plugin can act as an IRC proxy: it will simulate an IRC server, and
|
|
you can connect to WeeChat with any other IRC client (including WeeChat itself).
|
|
|
|
You can define one port by IRC server, or one generic port for all servers.
|
|
|
|
When using one port for all servers, the client must send the internal name of
|
|
server in the IRC "PASS" command, with this format:
|
|
|
|
----
|
|
PASS server:password
|
|
----
|
|
|
|
Example: IRC proxy with SSL for any server (client will choose):
|
|
|
|
----
|
|
/relay add ssl.irc 8000
|
|
----
|
|
|
|
Example: IRC proxy without SSL only for server "freenode":
|
|
|
|
----
|
|
/relay add irc.freenode 8000
|
|
----
|
|
|
|
Now you can connect on port 8000 with any IRC client using server password
|
|
"mypassword" (or "freenode:mypassword" if no server was specified in the relay).
|
|
|
|
[[relay_weechat_protocol]]
|
|
==== WeeChat protocol
|
|
|
|
The Relay plugin can send data to remote interface using WeeChat protocol.
|
|
|
|
You can connect with a remote interface, see the list on download page:
|
|
https://weechat.org/download
|
|
|
|
[IMPORTANT]
|
|
WeeChat itself can NOT connect to another WeeChat with this protocol.
|
|
|
|
For example:
|
|
|
|
----
|
|
/relay add weechat 9000
|
|
----
|
|
|
|
Now you can connect on port 9000 with a remote interface using password
|
|
"mypassword".
|
|
|
|
[[relay_websocket]]
|
|
==== WebSocket
|
|
|
|
WebSocket protocol (http://tools.ietf.org/html/rfc6455[RFC 6455]) is supported
|
|
in Relay plugin for all protocols.
|
|
|
|
The WebSocket handshake is automatically detected and socket becomes ready for
|
|
WebSocket if required headers are found in handshake and if origin is allowed
|
|
(see option
|
|
<<option_relay.network.websocket_allowed_origins,relay.network.websocket_allowed_origins>>).
|
|
|
|
A WebSocket can be opened in a HTML5 with a single line of JavaScript:
|
|
|
|
[source,js]
|
|
----
|
|
websocket = new WebSocket("ws://server.com:9000/weechat");
|
|
----
|
|
|
|
The port (9000 in example) is the port defined in Relay plugin.
|
|
The URI must always end with "/weechat" (for 'irc' and 'weechat' protocols).
|
|
|
|
[[scripts_plugins]]
|
|
=== Scripts plugins
|
|
|
|
WeeChat provides 7 scripting plugins: Python, Perl, Ruby, Lua, Tcl, Guile
|
|
(scheme) and Javascript.
|
|
These plugins can load, execute and unload scripts for these languages.
|
|
|
|
Another plugin called "script" is a scripts manager and is used to load/unload
|
|
scripts of any language, and install/remove scripts of WeeChat scripts
|
|
repository, which are visible at this URL: https://weechat.org/scripts
|
|
|
|
For more information about how to write scripts, or WeeChat API for
|
|
scripts, please read 'WeeChat Scripting Guide'.
|
|
|
|
[[script_options]]
|
|
==== Script options (script.conf)
|
|
|
|
Sections:
|
|
|
|
[width="100%",cols="3m,6m,16",options="header"]
|
|
|===
|
|
| Section | Control command | Description
|
|
| look | /set script.look.* | Look and feel
|
|
| color | /set script.color.* | Colors
|
|
| scripts | /set script.scripts.* | Options for download of scripts
|
|
|===
|
|
|
|
Options:
|
|
|
|
include::autogen/user/script_options.asciidoc[]
|
|
|
|
[[script_commands]]
|
|
==== Script commands
|
|
|
|
include::autogen/user/script_commands.asciidoc[]
|
|
|
|
[[python_commands]]
|
|
==== Python commands
|
|
|
|
include::autogen/user/python_commands.asciidoc[]
|
|
|
|
[[perl_commands]]
|
|
==== Perl commands
|
|
|
|
include::autogen/user/perl_commands.asciidoc[]
|
|
|
|
[[ruby_commands]]
|
|
==== Ruby commands
|
|
|
|
include::autogen/user/ruby_commands.asciidoc[]
|
|
|
|
[[lua_commands]]
|
|
==== Lua commands
|
|
|
|
include::autogen/user/lua_commands.asciidoc[]
|
|
|
|
[[tcl_commands]]
|
|
==== Tcl commands
|
|
|
|
include::autogen/user/tcl_commands.asciidoc[]
|
|
|
|
[[guile_commands]]
|
|
==== Guile commands
|
|
|
|
include::autogen/user/guile_commands.asciidoc[]
|
|
|
|
[[javascript_commands]]
|
|
==== Javascript commands
|
|
|
|
include::autogen/user/javascript_commands.asciidoc[]
|
|
|
|
[[trigger_plugin]]
|
|
=== Trigger plugin
|
|
|
|
Trigger is the Swiss Army knife for WeeChat: it can hook many things (signal,
|
|
modifier, print, ...), change the content of data, and execute one or more
|
|
commands. A condition can be used to prevent the trigger to run in some
|
|
circumstances.
|
|
|
|
Using triggers require you to know how the signals, modifiers, ... are working.
|
|
So you might consider reading the 'Hooks' chapter in the
|
|
'WeeChat Plugin API Reference'.
|
|
|
|
[[trigger_options]]
|
|
==== Options (trigger.conf)
|
|
|
|
Sections:
|
|
|
|
[width="100%",cols="3m,6m,16",options="header"]
|
|
|===
|
|
| Section | Control command | Description
|
|
| look | /set trigger.look.* | Look and feel
|
|
| color | /set trigger.color.* | Colors
|
|
| trigger | <<command_trigger_trigger,/trigger add>> +
|
|
<<command_trigger_trigger,/trigger set>> +
|
|
/set trigger.trigger.* | Trigger options
|
|
|===
|
|
|
|
Options:
|
|
|
|
include::autogen/user/trigger_options.asciidoc[]
|
|
|
|
[[trigger_commands]]
|
|
==== Commands
|
|
|
|
include::autogen/user/trigger_commands.asciidoc[]
|
|
|
|
[[trigger_anatomy]]
|
|
==== Anatomy of a trigger
|
|
|
|
A trigger has the following options (names are
|
|
`trigger.trigger.<name>.<option>`):
|
|
|
|
[width="100%",cols="2m,2,10",options="header"]
|
|
|===
|
|
| Option | Values | Description
|
|
|
|
| enabled | `on`, `off` |
|
|
When option is `off`, the trigger is disabled and actions are not executed
|
|
any more.
|
|
|
|
| hook | `signal`, `hsignal`, `modifier`, `print`, `command`, `command_run`,
|
|
`timer`, `config`, `focus` |
|
|
The hook used in trigger. For more information, see
|
|
'WeeChat Plugin API Reference', chapter 'Hooks'.
|
|
|
|
| arguments | string |
|
|
The arguments for the hook, it depends on the hook type used.
|
|
|
|
| conditions | string |
|
|
Conditions to execute the trigger; they are evaluated (see command
|
|
<<command_weechat_eval,/eval>>).
|
|
|
|
| regex | string |
|
|
One or more POSIX extended regular expressions, to change data received in the
|
|
hook callback (and some stuff added by trigger plugin), see
|
|
<<trigger_regex,regular expression>>.
|
|
|
|
| command | string |
|
|
Command to execute (many commands can be separated by semicolons); it is
|
|
evaluated (see command <<command_weechat_eval,/eval>>).
|
|
|
|
| return_code | `ok`, `ok_eat`, `error` |
|
|
The return code of callback (default is `ok`, which should be used in almost
|
|
all triggers, the other values are rarely used).
|
|
|===
|
|
|
|
For example, the default 'beep' trigger has following options:
|
|
|
|
----
|
|
trigger.trigger.beep.enabled = on
|
|
trigger.trigger.beep.hook = print
|
|
trigger.trigger.beep.arguments = ""
|
|
trigger.trigger.beep.conditions = "${tg_highlight} || ${tg_msg_pv}"
|
|
trigger.trigger.beep.regex = ""
|
|
trigger.trigger.beep.command = "/print -beep"
|
|
trigger.trigger.beep.return_code = ok
|
|
----
|
|
|
|
[[trigger_execution]]
|
|
==== Execution
|
|
|
|
When a trigger callback is called, following actions are executed, in this
|
|
order, if triggers are globally enabled and if the trigger itself is enabled:
|
|
|
|
. check trigger conditions: if false, exit
|
|
. replace text in trigger using regular expression(s)
|
|
. execute command(s)
|
|
. exit with a return code (except for hooks 'modifier' and 'focus').
|
|
|
|
[[trigger_hook_arguments]]
|
|
==== Hook arguments
|
|
|
|
The arguments depend on the hook used. They are separated by semicolons.
|
|
|
|
[width="100%",cols="2,6,7",options="header"]
|
|
|===
|
|
| Hook | Arguments | Examples
|
|
|
|
| signal |
|
|
1. signal name (priority allowed) (required) +
|
|
2. signal name (priority allowed) +
|
|
3. ... |
|
|
`*,irc_in_privmsg` +
|
|
`*,irc_in_privmsg;*,irc_in_notice` +
|
|
`signal_sigwinch`
|
|
|
|
| hsignal |
|
|
1. signal name (priority allowed) (required) +
|
|
2. signal name (priority allowed) +
|
|
3. ... |
|
|
`nicklist_nick_added`
|
|
|
|
| modifier |
|
|
1. modifier name (priority allowed) (required) +
|
|
2. modifier name (priority allowed) +
|
|
3. ... |
|
|
`weechat_print` +
|
|
`5000\|input_text_display;5000\|history_add`
|
|
|
|
| print |
|
|
1. buffer name +
|
|
2. tags +
|
|
3. message +
|
|
4. strip colors (0/1) |
|
|
`irc.freenode.*` +
|
|
`irc.freenode.#weechat` +
|
|
`irc.freenode.#weechat;irc_notice` +
|
|
`*;;;1`
|
|
|
|
| command |
|
|
1. command name (priority allowed) (required) +
|
|
2. description +
|
|
3. arguments +
|
|
4. description of arguments +
|
|
5. completion |
|
|
`test` +
|
|
`5000\|test`
|
|
|
|
| command_run |
|
|
1. command (priority allowed) (required) +
|
|
2. command (priority allowed) +
|
|
3. ... |
|
|
`/cmd arguments`
|
|
|
|
| timer |
|
|
1. interval in milliseconds (required) +
|
|
2. alignment on second (default: 0) +
|
|
3. max number of calls (default: 0, which means "no end") |
|
|
`3600000` +
|
|
`60000;0;5`
|
|
|
|
| config |
|
|
1. option name (priority allowed) (required) +
|
|
2. option name (priority allowed) +
|
|
3. ... |
|
|
`weechat.look.*`
|
|
|
|
| focus |
|
|
1. area name (priority allowed) (required) +
|
|
2. area name (priority allowed) +
|
|
3. ... |
|
|
`buffer_nicklist`
|
|
|===
|
|
|
|
[[trigger_conditions]]
|
|
==== Conditions
|
|
|
|
The conditions are used to continue processing in trigger, or stop everything.
|
|
|
|
They are evaluated, and data available in callback can be used
|
|
(see <<trigger_callback_data,data in callbacks>> and command
|
|
<<command_weechat_eval,/eval>>).
|
|
|
|
Example: the default 'beep' trigger uses this condition to make a beep only on
|
|
highlight or private message:
|
|
|
|
----
|
|
${tg_highlight} || ${tg_msg_pv}
|
|
----
|
|
|
|
[[trigger_regex]]
|
|
==== Regular expression
|
|
|
|
The regular expression is used to change variables in callback hashtable.
|
|
|
|
The format is: "/regex/replace" or "/regex/replace/var" (where 'var' is a
|
|
variable of the hashtable). +
|
|
If 'var' is not specified, the default variable is used, it depends on hook
|
|
type:
|
|
|
|
[width="50%",cols="4,5m",options="header"]
|
|
|===
|
|
| Hook | Default variable
|
|
| signal | tg_signal_data
|
|
| hsignal |
|
|
| modifier | tg_string
|
|
| print | tg_message
|
|
| command | tg_argv_eol1
|
|
| command_run | tg_command
|
|
| timer | tg_remaining_calls
|
|
| config | tg_value
|
|
| focus |
|
|
|===
|
|
|
|
Many regular expressions can be separated by a space, for example:
|
|
"/regex1/replace1/var1 /regex2/replace2/var2".
|
|
|
|
The char "/" can be replaced by any char (one or more identical chars).
|
|
|
|
Matching groups can be used in "replace":
|
|
|
|
* `${re:0}` to `${re:99}`: `${re:0}` is the whole match, `${re:1}` to
|
|
`${re:99}` are groups captured
|
|
* `${re:+}`: the last match (with highest number)
|
|
* `${hide:c,${re:N}}`: match "N" with all chars replaced by "c"
|
|
(example: `${hide:*,${re:2}}` is the group #2 with all chars replaced by
|
|
`*`).
|
|
|
|
Example: use bold for words between "*":
|
|
|
|
----
|
|
/\*(\S+)\*/*${color:bold}${re:1}${color:-bold}*/
|
|
----
|
|
|
|
Example: default trigger 'server_pass' uses this regular expression to hide
|
|
password in commands `/server` and `/connect` (chars in passwords are replaced
|
|
by `*`):
|
|
|
|
----
|
|
==^(/(server|connect) .*-(sasl_)?password=)(\S+)(.*)==${re:1}${hide:*,${re:4}}${re:5}
|
|
----
|
|
|
|
[NOTE]
|
|
In this example, the delimiter used is "==" because there is a "/" in the
|
|
regular expression.
|
|
|
|
[[trigger_command]]
|
|
==== Command
|
|
|
|
The command is executed after replacement of text with the regular expression.
|
|
Many commands can be separated by semicolons.
|
|
|
|
It is evaluated (see command <<command_weechat_eval,/eval>>) and text replaced
|
|
with a regular expression can be used in the command.
|
|
|
|
Example: default 'beep' trigger uses this command to make a beep (BEL):
|
|
|
|
----
|
|
/print -beep
|
|
----
|
|
|
|
[[trigger_callback_data]]
|
|
==== Data in callbacks
|
|
|
|
Data received in callbacks are stored in hashtables (pointers and strings) and
|
|
can be used in following options:
|
|
|
|
* 'conditions'
|
|
* 'regex'
|
|
* 'command'
|
|
|
|
The content of hashtables depend on the hook type.
|
|
|
|
A convenient way to see data in a trigger is to open trigger monitor buffer,
|
|
using the command:
|
|
|
|
----
|
|
/trigger monitor
|
|
----
|
|
|
|
[[trigger_data_signal]]
|
|
===== Signal
|
|
|
|
The "signal" callback sets following variables in hashtable:
|
|
|
|
[width="100%",cols="3m,2,14",options="header"]
|
|
|===
|
|
| Variable | Type | Description
|
|
| tg_signal | string | Name of signal
|
|
| tg_signal_data | string | Data sent with the signal
|
|
|===
|
|
|
|
If the signal contains an IRC message, the message is parsed and following data
|
|
is added in hashtable:
|
|
|
|
[width="100%",cols="3m,2,14",options="header"]
|
|
|===
|
|
| Variable | Type | Description
|
|
| server | string | Name of server (example: "freenode")
|
|
| tags | string | Tags in message (rarely used)
|
|
| message_without_tags | string | Message without tags
|
|
| nick | string | Nick
|
|
| host | string | Hostname
|
|
| command | string | IRC command (example: "PRIVMSG", "NOTICE", ...)
|
|
| channel | string | IRC channel
|
|
| arguments | string | Arguments of command (includes value of 'channel')
|
|
| text | string | Text (for example user message)
|
|
| pos_text | string | The index of text in message ("-1" if text was not found)
|
|
|===
|
|
|
|
When the data is a pointer, the variable `tg_signal_data` can be used like this
|
|
to read a hdata property (in this example this is a pointer on a buffer):
|
|
|
|
----
|
|
${buffer[${tg_signal_data}].full_name}
|
|
----
|
|
|
|
[[trigger_data_hsignal]]
|
|
===== Hsignal
|
|
|
|
The "hsignal" callback sets following variables in hashtable:
|
|
|
|
[width="100%",cols="3m,2,14",options="header"]
|
|
|===
|
|
| Variable | Type | Description
|
|
| tg_signal | string | Name of signal
|
|
|===
|
|
|
|
The hashtable contains all keys/values from hashtable received (type:
|
|
string/string).
|
|
|
|
[[trigger_data_modifier]]
|
|
===== Modifier
|
|
|
|
The "modifier" callback sets following variables in hashtable:
|
|
|
|
[width="100%",cols="3m,2,14",options="header"]
|
|
|===
|
|
| Variable | Type | Description
|
|
| tg_modifier | string | Name of modifier
|
|
| tg_modifier_data | string | Data sent with modifier
|
|
| tg_string | string | The string that can be modified
|
|
| tg_string_nocolor | string | The string without color codes
|
|
|===
|
|
|
|
For the 'weechat_print' modifier, variables using message tags are added (see
|
|
<<trigger_data_print,hook print>> below), and following variables:
|
|
|
|
[width="100%",cols="3m,2,14",options="header"]
|
|
|===
|
|
| Variable | Type | Description
|
|
| buffer | pointer | Buffer where message is printed
|
|
| tg_plugin | string | Plugin of buffer where message is printed
|
|
| tg_buffer | string | Full name of buffer where message is printed
|
|
| tg_prefix | string | Prefix of message printed
|
|
| tg_prefix_nocolor | string | Prefix without color codes
|
|
| tg_message | string | Message printed
|
|
| tg_message_nocolor | string | Message without color codes
|
|
|===
|
|
|
|
If the modifier contains an IRC message, the message is parsed and extra data is
|
|
added in hashtable (see <<trigger_data_signal,hook signal>>).
|
|
|
|
[[trigger_data_print]]
|
|
===== Print
|
|
|
|
The "print" callback sets following variables in hashtable:
|
|
|
|
[width="100%",cols="3m,2,14",options="header"]
|
|
|===
|
|
| Variable | Type | Description
|
|
| buffer | pointer | Buffer
|
|
| tg_date | string | Message date/time (format: `YYYY-MM-DD hh:mm:ss`)
|
|
| tg_displayed | string | "1" if displayed, "0" if line filtered
|
|
| tg_highlight | string | "1" if highlight, otherwise "0"
|
|
| tg_prefix | string | Prefix
|
|
| tg_prefix_nocolor | string | Prefix without color codes
|
|
| tg_message | string | Message
|
|
| tg_message_nocolor | string | Message without color codes
|
|
|===
|
|
|
|
Variables set using tags in message (they are set in modifier 'weechat_print'
|
|
too):
|
|
|
|
[width="100%",cols="3m,2,14",options="header"]
|
|
|===
|
|
| Variable | Type | Description
|
|
| tg_tags | string | Tags of message (with comma added at beginning/end of string)
|
|
| tg_tags_count | string | Number of tags in message
|
|
| tg_tag_nick | string | Nick (from tag "nick_xxx")
|
|
| tg_tag_prefix_nick | string | Color of nick in prefix (from tag "prefix_nick_ccc")
|
|
| tg_tag_host | string | User name and host, format: username@host (from tag "host_xxx")
|
|
| tg_tag_notify | string | Notify level ('none', 'message', 'private', 'highlight')
|
|
| tg_notify | string | Notify level, if different from 'none'
|
|
| tg_msg_pv | string | "1" for a private message, otherwise "0"
|
|
|===
|
|
|
|
[[trigger_data_command]]
|
|
===== Command
|
|
|
|
The "command" callback sets following variables in hashtable:
|
|
|
|
[width="100%",cols="3m,2,14",options="header"]
|
|
|===
|
|
| Variable | Type | Description
|
|
| buffer | pointer | Buffer
|
|
| tg_argvN | string | Argument #N
|
|
| tg_argv_eolN | string | From argument #N until end of arguments
|
|
|===
|
|
|
|
[[trigger_data_command_run]]
|
|
===== Command_run
|
|
|
|
The "command_run" callback sets following variables in hashtable:
|
|
|
|
[width="100%",cols="3m,2,14",options="header"]
|
|
|===
|
|
| Variable | Type | Description
|
|
| buffer | pointer | Buffer
|
|
| tg_command | string | Command executed
|
|
|===
|
|
|
|
[[trigger_data_timer]]
|
|
===== Timer
|
|
|
|
The "timer" callback sets following variables in hashtable:
|
|
|
|
[width="100%",cols="3m,2,14",options="header"]
|
|
|===
|
|
| Variable | Type | Description
|
|
| tg_remaining_calls | string | Number of remaining calls
|
|
| tg_date | string | Current date/time (format: `YYYY-MM-DD hh:mm:ss`)
|
|
|===
|
|
|
|
[[trigger_data_config]]
|
|
===== Config
|
|
|
|
The "config" callback sets following variables in hashtable:
|
|
|
|
[width="100%",cols="3m,2,14",options="header"]
|
|
|===
|
|
| Variable | Type | Description
|
|
| tg_option | string | Option
|
|
| tg_value | string | Value
|
|
|===
|
|
|
|
[[trigger_data_focus]]
|
|
===== Focus
|
|
|
|
The "focus" callback sets following variables in hashtable:
|
|
|
|
[width="100%",cols="3m,2,14",options="header"]
|
|
|===
|
|
| Variable | Type | Description
|
|
| window | pointer | Window
|
|
| buffer | pointer | Buffer
|
|
|===
|
|
|
|
The hashtable contains all keys/values from hashtable received (type:
|
|
string/string).
|
|
|
|
[[trigger_examples]]
|
|
==== Examples
|
|
|
|
[[trigger_example_url_color]]
|
|
===== Color for URLs
|
|
|
|
Display URLs in green:
|
|
|
|
----
|
|
/trigger add url_color modifier weechat_print "${tg_notify}" "==\S+://\S+==${color:green}${re:0}${color:reset}=="
|
|
----
|
|
|
|
[NOTE]
|
|
The simple regex used to detect URL may not catch well all URLs, but it is
|
|
faster than a complex regex.
|
|
|
|
[[trigger_example_auto_pong]]
|
|
===== Auto pong on ping queries
|
|
|
|
When someone sends a "ping" in a private buffer, this trigger will auto-reply
|
|
with `pong`:
|
|
|
|
----
|
|
/trigger add pong print "" "${type} == private && ${tg_message} == ping" "" "pong"
|
|
----
|
|
|
|
[[trigger_example_responsive_layout]]
|
|
===== Responsive layout
|
|
|
|
Following triggers can be used to customize things displayed when the size of
|
|
terminal is changed:
|
|
|
|
----
|
|
/trigger add resize_small signal signal_sigwinch "${info:term_width} < 100" "" "/bar hide nicklist"
|
|
/trigger add resize_big signal signal_sigwinch "${info:term_width} >= 100" "" "/bar show nicklist"
|
|
----
|
|
|
|
The triggers catch the signal "signal_sigwinch", which is sent by WeeChat when
|
|
signal SIGWINCH is received (when terminal size is changed).
|
|
|
|
The condition with `${info:term_width}` checks the width of terminal (you can
|
|
also use `${info:term_height}` if needed).
|
|
|
|
In the example, when the terminal becomes small, the nicklist is hidden. And the
|
|
bar is restored when the width is greater or equal to 100 chars.
|
|
|
|
[[trigger_example_config_save]]
|
|
===== Automatic save of configuration
|
|
|
|
You can automatically save configuration files (`*.conf`), for example each
|
|
hour:
|
|
|
|
----
|
|
/trigger add cfgsave timer 3600000;0;0 "" "" "/mute /save"
|
|
----
|
|
|
|
Arguments for the timer hook are:
|
|
|
|
* '3600000': 3600 * 1000 milliseconds, the callback is called each hour
|
|
* '0': alignment on second (not aligned here)
|
|
* '0': max number of calls (0 = no end for the timer)
|
|
|
|
The command `/mute /save` will silently save configuration files (nothing
|
|
displayed on core buffer).
|
|
|
|
[[xfer_plugin]]
|
|
=== Xfer plugin
|
|
|
|
Xfer plugin brings:
|
|
|
|
* direct chat (between two hosts, without server): for example "DCC Chat" via
|
|
IRC plugin
|
|
* file transfer, for example "DCC" via IRC plugin
|
|
|
|
[[xfer_options]]
|
|
==== Options (xfer.conf)
|
|
|
|
Sections:
|
|
|
|
[width="100%",cols="3m,6m,16",options="header"]
|
|
|===
|
|
| Section | Control command | Description
|
|
| look | /set xfer.look.* | Look and feel
|
|
| color | /set xfer.color.* | Colors
|
|
| network | /set xfer.network.* | Network options
|
|
| file | /set xfer.file.* | Options for files sent/received
|
|
|===
|
|
|
|
Options:
|
|
|
|
include::autogen/user/xfer_options.asciidoc[]
|
|
|
|
[[xfer_commands]]
|
|
==== Commands
|
|
|
|
include::autogen/user/xfer_commands.asciidoc[]
|
|
|
|
[[support]]
|
|
== Support
|
|
|
|
Before asking for support, be sure you've read documentation and FAQ provided
|
|
with WeeChat.
|
|
|
|
For support with IRC, on server 'chat.freenode.net':
|
|
|
|
* official channels (with developers):
|
|
** '#weechat' (English)
|
|
** '#weechat-fr' (French)
|
|
* non-official channels:
|
|
** '#weechat-de' (German)
|
|
|
|
For other ways of support, see: https://weechat.org/dev/support
|