WeeChat scripting guide

# display "hello" on core buffer
weechat.prnt("", "hello")

# display "hello" on core buffer, but do not write it to log file
# (version ≥ 0.3.3 only)
weechat.prnt_date_tags("", 0, "no_log", "hello")

# display prefix "==>" and message "hello" on current buffer
# (prefix and message must be separated by tab)
weechat.prnt(weechat.current_buffer(), "==>\thello")

# display error message on core buffer (with error prefix)
weechat.prnt("", "%swrong arguments" % weechat.prefix("error"))

# display message with color on core buffer
weechat.prnt("", "text %syellow on blue" % weechat.color("yellow,blue"))

# search buffer and display message
# (full name of buffer is plugin.name, for example: "irc.libera.#weechat")
buffer = weechat.buffer_search("irc", "libera.#weechat")
weechat.prnt(buffer, "message on #weechat channel")

# other solution to find an IRC buffer (better)
# (note that server and channel are separated by a comma)
buffer = weechat.info_get("irc_buffer", "libera,#weechat")
weechat.prnt(buffer, "message on #weechat channel")

# execute command "/help" on current buffer (result is on core buffer)
weechat.command("", "/help")

# send "hello" to #weechat IRC channel (users on channel will see message)
buffer = weechat.info_get("irc_buffer", "libera,#weechat")
weechat.command(buffer, "hello")

# callback for data received in input
def buffer_input_cb(data, buffer, input_data):
    # ...
    return weechat.WEECHAT_RC_OK

# callback called when buffer is closed
def buffer_close_cb(data, buffer):
    # ...
    return weechat.WEECHAT_RC_OK

# create buffer
buffer = weechat.buffer_new("mybuffer", "buffer_input_cb", "", "buffer_close_cb", "")

# set title
weechat.buffer_set(buffer, "title", "This is title for my buffer.")

# disable logging, by setting local variable "no_log" to "1"
weechat.buffer_set(buffer, "localvar_set_no_log", "1")

buffer = weechat.current_buffer()

number = weechat.buffer_get_integer(buffer, "number")
name = weechat.buffer_get_string(buffer, "name")
short_name = weechat.buffer_get_string(buffer, "short_name")

# add local variable
weechat.buffer_set(buffer, "localvar_set_myvar", "my_value")

# read local variable
myvar = weechat.buffer_get_string(buffer, "localvar_myvar")

# delete local variable
weechat.buffer_set(buffer, "localvar_del_myvar", "")

/buffer listvar

def my_command_cb(data, buffer, args):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_command("myfilter", "description of myfilter",
    "[list] | [enable|disable|toggle [name]] | [add name plugin.buffer tags regex] | [del name|-all]",
    "description of arguments...",
    "list"
    " || enable %(filters_names)"
    " || disable %(filters_names)"
    " || toggle %(filters_names)"
    " || add %(filters_names) %(buffers_plugins_names)|*"
    " || del %(filters_names)|-all",
    "my_command_cb", "")

/help myfilter

/myfilter arguments...

def timer_cb(data, remaining_calls):
    # ...
    return weechat.WEECHAT_RC_OK

# timer called each minute when second is 00
weechat.hook_timer(60 * 1000, 60, 0, "timer_cb", "")

def my_process_cb(data, command, return_code, out, err):
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Error with command '%s'" % command)
        return weechat.WEECHAT_RC_OK
    if return_code >= 0:
        weechat.prnt("", "return_code = %d" % return_code)
    if out:
        weechat.prnt("", "stdout: %s" % out)
    if err:
        weechat.prnt("", "stderr: %s" % err)
    return weechat.WEECHAT_RC_OK

weechat.hook_process("/bin/ls -l /etc", 10 * 1000, "my_process_cb", "")

def get_status(data):
    # do something blocking...
    # ...
    return "this is the result"

def my_process_cb(data, command, return_code, out, err):
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Error with command '%s'" % command)
        return weechat.WEECHAT_RC_OK
    if return_code >= 0:
        weechat.prnt("", "return_code = %d" % return_code)
    if out:
        weechat.prnt("", "stdout: %s" % out)
    if err:
        weechat.prnt("", "stderr: %s" % err)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process("func:get_status", 5000, "my_process_cb", "")

# Display latest stable version of WeeChat.
weechat_latest_version = ""

def weechat_process_cb(data, command, return_code, out, err):
    global weechat_latest_version
    if out:
        weechat_latest_version += out
    if return_code >= 0:
        weechat.prnt("", "Latest WeeChat version: %s" % weechat_latest_version)
    return weechat.WEECHAT_RC_OK

weechat.hook_process("url:https://weechat.org/dev/info/stable/",
                     30 * 1000, "weechat_process_cb", "")

def my_process_cb(data, command, return_code, out, err):
    if return_code >= 0:
        weechat.prnt("", "End of transfer (return code = %d)" % return_code)
    return weechat.WEECHAT_RC_OK

weechat.hook_process_hashtable("url:https://weechat.org/files/src/weechat-devel.tar.gz",
                               {"file_out": "/tmp/weechat-devel.tar.gz"},
                               30 * 1000, "my_process_cb", "")

script_options = {
    "option1": "value1",
    "option2": "value2",
    "option3": "value3",
}
for option, default_value in script_options.items():
    if not weechat.config_is_set_plugin(option):
        weechat.config_set_plugin(option, default_value)

SCRIPT_NAME = "myscript"

# ...

def config_cb(data, option, value):
    """Callback called when a script option is changed."""
    # for example, read all script options to script variables...
    # ...
    return weechat.WEECHAT_RC_OK

# ...

weechat.hook_config("plugins.var.python." + SCRIPT_NAME + ".*", "config_cb", "")
# for other languages, change "python" with your language (perl/ruby/lua/tcl/guile/javascript)

# string
weechat.prnt("", "value of option weechat.look.item_time_format is: %s"
                 % (weechat.config_string(weechat.config_get("weechat.look.item_time_format"))))

# boolean
weechat.prnt("", "value of option weechat.look.day_change is: %d"
                 % (weechat.config_boolean(weechat.config_get("weechat.look.day_change"))))

# integer
weechat.prnt("", "value of option weechat.look.scroll_page_percent is: %d"
                 % (weechat.config_integer(weechat.config_get("weechat.look.scroll_page_percent"))))

# color
weechat.prnt("", "value of option weechat.color.chat_delimiters is: %s"
                 % (weechat.config_color(weechat.config_get("weechat.color.chat_delimiters"))))

def join_cb(data, signal, signal_data):
    # signal is for example: "libera,irc_in2_join"
    # signal_data is IRC message, for example: ":nick!user@host JOIN :#channel"
    server = signal.split(",")[0]
    msg = weechat.info_get_hashtable("irc_message_parse", {"message": signal_data})
    buffer = weechat.info_get("irc_buffer", "%s,%s" % (server, msg["channel"]))
    if buffer:
        weechat.prnt(buffer, "%s (%s) has joined this channel!" % (msg["nick"], msg["host"]))
    return weechat.WEECHAT_RC_OK

# it is useful here to use "*" as server, to catch JOIN messages on all IRC
# servers
weechat.hook_signal("*,irc_in2_join", "join_cb", "")

def modifier_cb(data, modifier, modifier_data, string):
    # add server name to all messages received
    # (OK that's not very useful, but that's just an example!)
    return "%s %s" % (string, modifier_data)

weechat.hook_modifier("irc_in2_privmsg", "modifier_cb", "")

dict = weechat.info_get_hashtable(
    "irc_message_parse",
    {"message": "@time=2015-06-27T16:40:35.000Z;tag2=value\\sspace :nick!user@host PRIVMSG #weechat :hello!"})

# dict == {
#     "tags": "time=2015-06-27T16:40:35.000Z;tag2=value\\sspace",
#     "tag_time": "2015-06-27T16:40:35.000Z",
#     "tag_tag2": "value space",
#     "message_without_tags": ":nick!user@host PRIVMSG #weechat :hello!",
#     "nick": "nick",
#     "user": "user",
#     "host": "nick!user@host",
#     "command": "PRIVMSG",
#     "channel": "#weechat",
#     "arguments": "#weechat :hello!",
#     "text": "hello!",
#     "param1": "#weechat",
#     "param2": "hello!",
#     "num_params": "2",
#     "pos_command": "65",
#     "pos_arguments": "73",
#     "pos_channel": "73",
#     "pos_text": "83",
# }

version = weechat.info_get("version_number", "") or 0
if int(version) >= 0x00030200:
    weechat.prnt("", "This is WeeChat 0.3.2 or newer")
else:
    weechat.prnt("", "This is WeeChat 0.3.1 or older")

# this will display for example "Version 0.3.2"
weechat.prnt("", "Version %s" % weechat.info_get("version", ""))

# WeeChat config directory, for example: "/home/user/.config/weechat"
weechat.prnt("", "WeeChat config dir: %s" % weechat.info_get("weechat_config_dir", ""))

# keyboard inactivity
weechat.prnt("", "Inactivity since %s seconds" % weechat.info_get("inactivity", ""))

# read infolist "buffer", to get list of buffers
infolist = weechat.infolist_get("buffer", "", "")
if infolist:
    while weechat.infolist_next(infolist):
        name = weechat.infolist_string(infolist, "name")
        weechat.prnt("", "buffer: %s" % name)
    weechat.infolist_free(infolist)