468 lines
17 KiB
XML
468 lines
17 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<!--
|
|
|
|
WeeChat documentation (english version)
|
|
|
|
Copyright (c) 2003-2009 by FlashCode <flashcode@flashtux.org>
|
|
|
|
This manual is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 3 of the License, or
|
|
(at your option) any later version.
|
|
|
|
This manual is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
-->
|
|
|
|
<section id="secScriptPluginAPI">
|
|
<title>Script plugin API</title>
|
|
|
|
<para>
|
|
Five plugins are provided with WeeChat to use script languages:
|
|
Perl, Python, Ruby, Lua and Tcl.
|
|
</para>
|
|
|
|
<section id="secLoadUnloadScripts">
|
|
<title>Load / unload scripts</title>
|
|
|
|
<para>
|
|
Scripts are loaded and unloaded with <command>/perl</command>,
|
|
<command>/python</command>, <command>/ruby</command>,
|
|
<command>/lua</command> and <command>/tcl</command> commands
|
|
(type <command>/help</command> in WeeChat for help about commands).
|
|
</para>
|
|
|
|
<para>
|
|
Examples:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Load a Perl script:
|
|
<command><userinput>/perl load /tmp/test.pl</userinput></command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
List all loaded Perl scripts:
|
|
<command><userinput>/perl</userinput></command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Load a Python script:
|
|
<command><userinput>/python load /tmp/test.py</userinput></command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
List all loaded Python scripts:
|
|
<command><userinput>/python</userinput></command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Load a Ruby script:
|
|
<command><userinput>/ruby load /tmp/test.rb</userinput></command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
List all loaded Ruby scripts:
|
|
<command><userinput>/ruby</userinput></command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Load a Lua script:
|
|
<command><userinput>/lua load /tmp/test.lua</userinput></command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
List all loaded Lua scripts:
|
|
<command><userinput>/lua</userinput></command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Load a Tcl script:
|
|
<command><userinput>/tcl load /tmp/test.tcl</userinput></command>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
List all loaded Tcl scripts:
|
|
<command><userinput>/tcl</userinput></command>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="secSyntaxByLanguage">
|
|
<title>Syntax by language</title>
|
|
|
|
<section id="secScriptPerl">
|
|
<title>Perl</title>
|
|
|
|
<para>
|
|
In a WeeChat Perl script, all API functions and variables are
|
|
prefixed by "<literal>weechat::</literal>".
|
|
Example:
|
|
<screen>
|
|
weechat::register("test", "Author <author\@domain.com>", "1.0",
|
|
"GPL3", "Script description", "bye_bye", "");
|
|
</screen>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="secScriptPython">
|
|
<title>Python</title>
|
|
|
|
<para>
|
|
A WeeChat Python script has to start by importing weechat:
|
|
<screen>import weechat</screen>
|
|
</para>
|
|
|
|
<para>
|
|
All API functions and variables are prefixed by
|
|
"<literal>weechat.</literal>".
|
|
Example:
|
|
<screen>
|
|
weechat.register("test", "Author <author@domain.com>", "1.0",
|
|
"GPL3", "Script description", "bye_bye", "")
|
|
</screen>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="secScriptRuby">
|
|
<title>Ruby</title>
|
|
|
|
<para>
|
|
In a WeeChat Ruby script, all code has to be in functions.
|
|
So for main code, you have to define a
|
|
"<literal>weechat_init</literal>" function, which is automatically
|
|
called when script is loaded by WeeChat. Example:
|
|
<screen>
|
|
def weechat_init
|
|
Weechat.register("test", "Author <author@domain.com>", "1.0",
|
|
"GPL3", "Script description", "bye_bye", "")
|
|
return Weechat::WEECHAT_RC_OK
|
|
end
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
All API functions are prefixed by
|
|
"<literal>Weechat.</literal>" and variables by
|
|
"<literal>Weechat::</literal>".
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="secScriptLua">
|
|
<title>Lua</title>
|
|
|
|
<para>
|
|
In a WeeChat Lua script, all API functions are prefixed by
|
|
"<literal>weechat.</literal>".
|
|
Variables are prefixed by "<literal>weechat.</literal>" and
|
|
suffixed by "<literal>()</literal>".
|
|
Example:
|
|
<screen>
|
|
weechat.register("test", "Author <author@domain.com>", "1.0",
|
|
"GPL3", "Script description", "bye_bye", "")
|
|
</screen>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="secScriptTcl">
|
|
<title>Tcl</title>
|
|
|
|
<para>
|
|
In a WeeChat Tcl script, all API functions are prefixed by
|
|
"<literal>weechat::</literal>".
|
|
Variables are prefixed by "<literal>$weechat::</literal>".
|
|
Example:
|
|
<screen>
|
|
weechat::register "test" "Author <author@domain.com>" "1.0" "GPL3" "Script description" "bye_bye" ""
|
|
</screen>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="secWeeChatScriptsAPI">
|
|
<title>WeeChat / scripts API</title>
|
|
|
|
<section id="secScript_register">
|
|
<title>register</title>
|
|
|
|
<para>
|
|
Perl prototype:
|
|
<command>
|
|
weechat::register(name, author, version, license, description,
|
|
end_function, charset);
|
|
</command>
|
|
</para>
|
|
<para>
|
|
Python prototype:
|
|
<command>
|
|
weechat.register(name, author, version, license, description,
|
|
end_function, charset)
|
|
</command>
|
|
</para>
|
|
<para>
|
|
Ruby prototype:
|
|
<command>
|
|
Weechat.register(name, author, version, license, description,
|
|
end_function, charset)
|
|
</command>
|
|
</para>
|
|
<para>
|
|
Lua prototype:
|
|
<command>
|
|
weechat.register(name, author, version, license, description,
|
|
end_function, charset)
|
|
</command>
|
|
</para>
|
|
<para>
|
|
Tcl prototype:
|
|
<command>
|
|
weechat::register name author version license description
|
|
end_function charset
|
|
</command>
|
|
</para>
|
|
<para>
|
|
This is first function to call in script.
|
|
All WeeChat scripts have to call this function.
|
|
</para>
|
|
<para>
|
|
Arguments:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<option>name</option>: unique name to identify script
|
|
(each script must have unique name)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<option>author</option>: string with author (may include name,
|
|
nick, e-mail, ..)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<option>version</option>: script version
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<option>description</option>: short description of script
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<option>end_function</option>: function called when script is
|
|
unloaded (optional parameter, empty string means nothing is
|
|
called at the end)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<option>charset</option>: charset used by script, you should
|
|
set this if script is NOT written with UTF-8 (you can use blank
|
|
value for UTF-8 script, which is default charset)
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Return value: 1 if script was registered, 0 if an error occured.
|
|
</para>
|
|
<para>
|
|
Examples:
|
|
<screen>
|
|
# perl
|
|
weechat::register("test", "Author <author\@domain.com>", "1.0",
|
|
"GPL3", "Script description", "bye_bye", "");
|
|
|
|
# python
|
|
weechat.register("test", "Author <author@domain.com>", "1.0",
|
|
"GPL3", "Script description", "bye_bye", "")
|
|
|
|
# ruby
|
|
Weechat.register("test", "Author <author@domain.com>", "1.0",
|
|
"GPL3", "Script description", "bye_bye", "")
|
|
|
|
-- lua
|
|
weechat.register("test", "Author <author@domain.com>", "1.0",
|
|
"GPL3", "Script description", "bye_bye", "")
|
|
|
|
# tcl
|
|
weechat::register "test" "Author <author@domain.com>" "1.0" "GPL3" "Script description" "bye_bye" ""
|
|
</screen>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="secOther_functions">
|
|
<title>Other functions</title>
|
|
|
|
<para>
|
|
Following functions are in script API (for description, see
|
|
<xref linkend="secPluginCApi" />).
|
|
<itemizedlist>
|
|
<listitem><para>plugin_get_name</para></listitem>
|
|
<listitem><para>set_charset</para></listitem>
|
|
<listitem><para>plugin_get_name</para></listitem>
|
|
<listitem><para>charset_set</para></listitem>
|
|
<listitem><para>iconv_to_internal</para></listitem>
|
|
<listitem><para>iconv_from_internal</para></listitem>
|
|
<listitem><para>gettext</para></listitem>
|
|
<listitem><para>ngettext</para></listitem>
|
|
<listitem><para>string_remove_color</para></listitem>
|
|
<listitem><para>mkdir_home</para></listitem>
|
|
<listitem><para>mkdir</para></listitem>
|
|
<listitem><para>mkdir_parents</para></listitem>
|
|
<listitem><para>list_new</para></listitem>
|
|
<listitem><para>list_add</para></listitem>
|
|
<listitem><para>list_search</para></listitem>
|
|
<listitem><para>list_casesearch</para></listitem>
|
|
<listitem><para>list_get</para></listitem>
|
|
<listitem><para>list_set</para></listitem>
|
|
<listitem><para>list_next</para></listitem>
|
|
<listitem><para>list_prev</para></listitem>
|
|
<listitem><para>list_string</para></listitem>
|
|
<listitem><para>list_size</para></listitem>
|
|
<listitem><para>list_remove</para></listitem>
|
|
<listitem><para>list_remove_all</para></listitem>
|
|
<listitem><para>list_free</para></listitem>
|
|
<listitem><para>config_new</para></listitem>
|
|
<listitem><para>config_new_section</para></listitem>
|
|
<listitem><para>config_search_section</para></listitem>
|
|
<listitem><para>config_new_option</para></listitem>
|
|
<listitem><para>config_search_option</para></listitem>
|
|
<listitem><para>config_string_to_boolean</para></listitem>
|
|
<listitem><para>config_option_reset</para></listitem>
|
|
<listitem><para>config_option_set</para></listitem>
|
|
<listitem><para>config_option_set_null</para></listitem>
|
|
<listitem><para>config_option_unset</para></listitem>
|
|
<listitem><para>config_option_rename</para></listitem>
|
|
<listitem><para>config_option_is_null</para></listitem>
|
|
<listitem><para>config_option_default_is_null</para></listitem>
|
|
<listitem><para>config_boolean</para></listitem>
|
|
<listitem><para>config_boolean_default</para></listitem>
|
|
<listitem><para>config_integer</para></listitem>
|
|
<listitem><para>config_integer_default</para></listitem>
|
|
<listitem><para>config_string</para></listitem>
|
|
<listitem><para>config_string_default</para></listitem>
|
|
<listitem><para>config_color</para></listitem>
|
|
<listitem><para>config_color_default</para></listitem>
|
|
<listitem><para>config_write_option</para></listitem>
|
|
<listitem><para>config_write_line</para></listitem>
|
|
<listitem><para>config_write</para></listitem>
|
|
<listitem><para>config_read</para></listitem>
|
|
<listitem><para>config_reload</para></listitem>
|
|
<listitem><para>config_option_free</para></listitem>
|
|
<listitem><para>config_section_free_options</para></listitem>
|
|
<listitem><para>config_section_free</para></listitem>
|
|
<listitem><para>config_free</para></listitem>
|
|
<listitem><para>config_get</para></listitem>
|
|
<listitem><para>config_get_plugin</para></listitem>
|
|
<listitem><para>config_set_plugin</para></listitem>
|
|
<listitem><para>config_unset_plugin</para></listitem>
|
|
<listitem><para>prefix</para></listitem>
|
|
<listitem><para>color</para></listitem>
|
|
<listitem><para>print</para></listitem>
|
|
<listitem><para>print_date_tags</para></listitem>
|
|
<listitem><para>print_y</para></listitem>
|
|
<listitem><para>log_print</para></listitem>
|
|
<listitem><para>hook_command</para></listitem>
|
|
<listitem><para>hook_command_run</para></listitem>
|
|
<listitem><para>hook_timer</para></listitem>
|
|
<listitem><para>hook_fd</para></listitem>
|
|
<listitem><para>hook_process</para></listitem>
|
|
<listitem><para>hook_connect</para></listitem>
|
|
<listitem><para>hook_print</para></listitem>
|
|
<listitem><para>hook_signal</para></listitem>
|
|
<listitem><para>hook_signal_send</para></listitem>
|
|
<listitem><para>hook_config</para></listitem>
|
|
<listitem><para>hook_completion</para></listitem>
|
|
<listitem><para>hook_completion_list_add</para></listitem>
|
|
<listitem><para>hook_modifier</para></listitem>
|
|
<listitem><para>hook_modifier_exec</para></listitem>
|
|
<listitem><para>hook_info</para></listitem>
|
|
<listitem><para>hook_infolist</para></listitem>
|
|
<listitem><para>unhook</para></listitem>
|
|
<listitem><para>unhook_all</para></listitem>
|
|
<listitem><para>buffer_new</para></listitem>
|
|
<listitem><para>buffer_search</para></listitem>
|
|
<listitem><para>current_buffer</para></listitem>
|
|
<listitem><para>buffer_clear</para></listitem>
|
|
<listitem><para>buffer_close</para></listitem>
|
|
<listitem><para>buffer_get_integer</para></listitem>
|
|
<listitem><para>buffer_get_string</para></listitem>
|
|
<listitem><para>buffer_get_pointer</para></listitem>
|
|
<listitem><para>buffer_set</para></listitem>
|
|
<listitem><para>current_window</para></listitem>
|
|
<listitem><para>window_get_integer</para></listitem>
|
|
<listitem><para>window_get_string</para></listitem>
|
|
<listitem><para>window_get_pointer</para></listitem>
|
|
<listitem><para>nicklist_add_group</para></listitem>
|
|
<listitem><para>nicklist_search_group</para></listitem>
|
|
<listitem><para>nicklist_add_nick</para></listitem>
|
|
<listitem><para>nicklist_search_nick</para></listitem>
|
|
<listitem><para>nicklist_remove_group</para></listitem>
|
|
<listitem><para>nicklist_remove_nick</para></listitem>
|
|
<listitem><para>nicklist_remove_all</para></listitem>
|
|
<listitem><para>bar_item_search</para></listitem>
|
|
<listitem><para>bar_item_new</para></listitem>
|
|
<listitem><para>bar_item_update</para></listitem>
|
|
<listitem><para>bar_item_remove</para></listitem>
|
|
<listitem><para>bar_search</para></listitem>
|
|
<listitem><para>bar_new</para></listitem>
|
|
<listitem><para>bar_set</para></listitem>
|
|
<listitem><para>bar_update</para></listitem>
|
|
<listitem><para>bar_remove</para></listitem>
|
|
<listitem><para>command</para></listitem>
|
|
<listitem><para>info_get</para></listitem>
|
|
<listitem><para>infolist_new</para></listitem>
|
|
<listitem><para>infolist_new_var_integer</para></listitem>
|
|
<listitem><para>infolist_new_var_string</para></listitem>
|
|
<listitem><para>infolist_new_var_pointer</para></listitem>
|
|
<listitem><para>infolist_new_var_time</para></listitem>
|
|
<listitem><para>infolist_get</para></listitem>
|
|
<listitem><para>infolist_next</para></listitem>
|
|
<listitem><para>infolist_prev</para></listitem>
|
|
<listitem><para>infolist_fields</para></listitem>
|
|
<listitem><para>infolist_integer</para></listitem>
|
|
<listitem><para>infolist_string</para></listitem>
|
|
<listitem><para>infolist_pointer</para></listitem>
|
|
<listitem><para>infolist_time</para></listitem>
|
|
<listitem><para>infolist_free</para></listitem>
|
|
<listitem><para>upgrade_new</para></listitem>
|
|
<listitem><para>upgrade_write_object</para></listitem>
|
|
<listitem><para>upgrade_read</para></listitem>
|
|
<listitem><para>upgrade_close</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</section>
|