/[weechat]/weechat/doc/weechat_doc_en.texi
ViewVC logotype

Diff of /weechat/doc/weechat_doc_en.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.42 by flashcode, Sun Oct 2 20:52:40 2005 UTC revision 1.43 by flashcode, Mon Oct 17 20:54:30 2005 UTC
# Line 35  Line 35 
35    
36  @title WeeChat - User guide  @title WeeChat - User guide
37  @subtitle Fast, light and extensible IRC client  @subtitle Fast, light and extensible IRC client
38  @subtitle Documentation for WeeChat v0.1.6-cvs - October, 02 2005  @subtitle Documentation for WeeChat v0.1.6-cvs - October, 17 2005
39    
40  @author FlashCode <@email{flashcode@@flashtux.org, flashcode AT flashtux.org}>  @author FlashCode <@email{flashcode@@flashtux.org, flashcode AT flashtux.org}>
41    
# Line 64  version 2 or higher. Line 64  version 2 or higher.
64  * Introduction:: What is WeeChat ?  * Introduction:: What is WeeChat ?
65  * Installation:: WeeChat installation  * Installation:: WeeChat installation
66  * Usage:: WeeChat usage  * Usage:: WeeChat usage
67  * Extensions:: WeeChat extensions  * Plugins:: WeeChat plugins
68  * Authors / Support:: Contact authors and get support  * Authors / Support:: Contact authors and get support
69  @end menu  @end menu
70    
# Line 199  Then follow instructions for source pack Line 199  Then follow instructions for source pack
199    
200  @c ********************************** Usage ***********************************  @c ********************************** Usage ***********************************
201    
202  @node Usage, Extensions, Installation, Top  @node Usage, Plugins, Installation, Top
203  @chapter Usage  @chapter Usage
204    
205  @menu  @menu
# Line 429  Color for input text (nick name)@* Line 429  Color for input text (nick name)@*
429  Type: color (Curses or Gtk color), default value: 'lightcyan'@*  Type: color (Curses or Gtk color), default value: 'lightcyan'@*
430  @item col_input_delimiters  @item col_input_delimiters
431  Color for input text (delimiters)@*  Color for input text (delimiters)@*
432  Type: color (Curses or Gtk color), default value: 'cyan'@*  Type: color (Curses or Gtk color), default value: 'lightgreen'@*
433  @item col_input_bg  @item col_input_bg
434  Background for input window@*  Background for input window@*
435  Type: color (Curses or Gtk color), default value: 'default'@*  Type: color (Curses or Gtk color), default value: 'default'@*
# Line 628  Type: string (any string), default value Line 628  Type: string (any string), default value
628  @item proxy_password  @item proxy_password
629  Password for proxy server@*  Password for proxy server@*
630  Type: string (any string), default value: ''@*  Type: string (any string), default value: ''@*
631    @item plugins_path
632    Path for searching plugins@*
633    Type: string (any string), default value: '~/.weechat/plugins'@*
634    @item plugins_autoload
635    Comma separated list of plugins to load automatically at startup, "*" means all plugins found (names may be partial, for example "perl" is ok for "libperl.so")@*
636    Type: string (any string), default value: '*'@*
637    @item plugins_extension
638    Standard plugins extension in filename, used for autoload (if empty, then all files are loaded when autoload is "*")@*
639    Type: string (any string), default value: '.so'@*
640  @item server_name  @item server_name
641  Name associated to IRC server (for display only)@*  Name associated to IRC server (for display only)@*
642  Type: string (any string), default value: ''@*  Type: string (any string), default value: ''@*
# Line 906  unbind: unbind a key (if "all", default Line 915  unbind: unbind a key (if "all", default
915  functions: list internal functions for key bindings@*  functions: list internal functions for key bindings@*
916  reset: restore bindings to the default values and delete ALL personal binding (use carefully!)@*  reset: restore bindings to the default values and delete ALL personal binding (use carefully!)@*
917  @*  @*
918  @item perl  [load filename] | [autoload] | [reload] | [unload]  @item plugin  [load filename] | [autoload] | [reload] | [unload]
 @*  
 list/load/unload Perl scripts@*  
 @*  
 filename: Perl script (file) to load@*  
 @*  
 Without argument, /perl command lists all loaded Perl scripts.@*  
 @*  
 @item python  [load filename] | [autoload] | [reload] | [unload]  
919  @*  @*
920  list/load/unload Python scripts@*  list/load/unload plugins@*
921  @*  @*
922  filename: Python script (file) to load@*  filename: WeeChat plugin (file) to load@*
923  @*  @*
924  Without argument, /python command lists all loaded Python scripts.@*  Without argument, /plugin command lists all loaded plugins.@*
 @*  
 @item ruby  [load filename] | [autoload] | [reload] | [unload]  
 @*  
 list/load/unload Ruby scripts@*  
 @*  
 filename: Ruby script (file) to load@*  
 @*  
 Without argument, /ruby command lists all loaded Ruby scripts.@*  
925  @*  @*
926  @item server  [servername] | [servername hostname port [-auto | -noauto] [-ipv6] [-ssl] [-pwd password] [-nicks nick1 nick2 nick3] [-username username] [-realname realname] [-command command] [-autojoin channel[,channel]] ] | [del servername]  @item server  [servername] | [servername hostname port [-auto | -noauto] [-ipv6] [-ssl] [-pwd password] [-nicks nick1 nick2 nick3] [-username username] [-realname realname] [-command command] [-autojoin channel[,channel]] ] | [del servername]
927  @*  @*
# Line 1152  channel modes:@* Line 1145  channel modes:@*
1145    m: moderated channel@*    m: moderated channel@*
1146    l: set the user limit to channel@*    l: set the user limit to channel@*
1147    b: set a ban mask to keep users out@*    b: set a ban mask to keep users out@*
1148      e: set exception mask@*
1149    v: give/take the ability to speak on a moderated channel@*    v: give/take the ability to speak on a moderated channel@*
1150    k: set a channel key (password)@*    k: set a channel key (password)@*
1151  user modes:@*  user modes:@*
# Line 1499  If the script is called "auto_weechat_co Line 1493  If the script is called "auto_weechat_co
1493  @command{./auto_weechat_command "freenode,#weechat *hello"}  @command{./auto_weechat_command "freenode,#weechat *hello"}
1494    
1495    
1496  @c ******************************* Extensions *********************************  @c ******************************** Plugins ***********************************
1497    
1498  @node Extensions, Authors / Support, Usage, Top  @node Plugins, Authors / Support, Usage, Top
1499  @chapter Extensions  @chapter Plugins
1500    
1501  @menu  @menu
1502  * Perl scripts::  * Plugins in WeeChat::
1503  * Python scripts::  * Write a plugin::
1504  * Ruby scripts::  * Plugin example::
1505    * Scripts plugins::
1506  @end menu  @end menu
1507    
1508  @node Perl scripts, Python scripts, Extensions, Extensions  @node Plugins in WeeChat, Write a plugin, Plugins, Plugins
1509  @section Perl scripts  @section Plugins in WeeChat
1510    
1511    A plugin is a C program which can call WeeChat functions defined in an
1512    interface.@*
1513    @*
1514    This C program does not need WeeChat sources to compile and can be
1515    dynamically loaded into WeeChat with command @command{/plugin}.@*
1516    @*
1517    The plugin has to be a dynamic library, for dynamic loading by
1518    operating system.
1519    Under GNU/Linux, the file has ``.so'' extension.
1520    
1521    @node Write a plugin, Plugin example, Plugins in WeeChat, Plugins
1522    @section Write a plugin
1523    
1524    @subsection Base rules
1525    
1526    The plugin should include ``weechat-plugin.h'' file (available in
1527    WeeChat source code).@*
1528    This file defines structures and types used to communicate with WeeChat.@*
1529    @*
1530    The plugin must have some variables and functions (mandatory, without
1531    them the plugin can't load):@*
1532    @itemize @bullet
1533    @item variables for plugin description:
1534    @itemize @minus
1535    @item plugin_name[]: plugin name
1536    @item plugin_version[]: plugin version
1537    @item plugin_description[]: short description of plugin
1538    @end itemize
1539    @item functions for init and end of plugin:
1540    @itemize @minus
1541    @item weechat_plugin_init: function called when plugin is loaded
1542    @item weechat_plugin_end: function called when plugin is unloaded
1543    @end itemize
1544    @end itemize
1545    
1546    @subsection API functions
1547    
1548  @subsection Load/unload Perl scripts  The plugin can call some functions defined in t_weechat_plugin structure.@*
1549    These functions are detailed below:
1550    
1551    @itemize @bullet
1552    @item
1553    @command{int ascii_strcasecmp (t_weechat_plugin *plugin,
1554    char *string1, char *string2)}@*
1555    @*
1556    locale and case independent string comparison.@*
1557    
1558    @emph{Arguments:}
1559    @itemize @minus
1560    @item @option{plugin}: pointer to plugin structure
1561    @item @option{string1}: first string for comparison
1562    @item @option{string2}: second string for comparison
1563    @end itemize
1564    @*
1565    @emph{Return value:}@*
1566    @*
1567    Difference between two strings: negative if chaine1 < chaine2,
1568    nul if chaine1 == chaine 2, positive if chaine1 > chaine2@*
1569    @*
1570    @emph{Example:}@*
1571    @*
1572    @code{if (plugin->ascii_strcasecmp (plugin, "abc", "def") != 0) ...}@*
1573    
1574    @*
1575    
1576    @item
1577    @command{char **explode_string (t_weechat_plugin *plugin,
1578    char *string, char *separators, int num_items_max, int *num_items)}@*
1579    @*
1580    Explode a string according to one or more delimiter(s).@*
1581    
1582    @emph{Param@`etres :}
1583    @itemize @minus
1584    @item @option{plugin}: pointer to plugin structure
1585    @item @option{string}: string to explode
1586    @item @option{separators}: delimiters used for explosion
1587    @item @option{num_items_max}: maximum number of items created (0 means
1588    no limit)
1589    @item @option{num_items}: pointer to int which will contain number of
1590    items created
1591    @end itemize
1592    @*
1593    @emph{Return value:}@*
1594    @*
1595    Array of strings, NULL if problem.@*
1596    Note: the result has to be free by a call to ``free_exploded_string''
1597    function after use.@*
1598    @*
1599    @emph{Example:}@*
1600    @*
1601    @code{char *argv;}@*
1602    @code{int argc;}@*
1603    @code{argv = plugin->explode_string (plugin, string, " ", 0, &argc);}@*
1604    @code{...}@*
1605    @code{if (argv != NULL)}@*
1606    @code{plugin->free_exploded_string (plugin, argv);}@*
1607    @*
1608    
1609    @item
1610    @command{char **free_exploded_string (t_weechat_plugin *plugin,
1611    char **string)}@*
1612    @*
1613    Free memory used by a string explosion.@*
1614    
1615    @emph{Arguments:}
1616    @itemize @minus
1617    @item @option{plugin}: pointer to plugin structure
1618    @item @option{string}: string exploded by ``explode_string'' function
1619    @end itemize
1620    @*
1621    @emph{Return value:}@*
1622    @*
1623    None.@*
1624    @*
1625    @emph{Example:}@*
1626    @*
1627    @code{char *argv;}@*
1628    @code{int argc;}@*
1629    @code{argv = plugin->explode_string (plugin, string, " ", 0, &argc);}@*
1630    @code{...}@*
1631    @code{if (argv != NULL)}@*
1632    @code{plugin->free_exploded_string (plugin, argv);}@*
1633    @*
1634    
1635    @item
1636    @command{void exec_on_files (t_weechat_plugin *plugin, char *directory,
1637    int (*callback)(t_weechat_plugin *, char *))}@*
1638    @*
1639    Execute a function on all files of a directory.@*
1640    
1641    @emph{Arguments:}
1642    @itemize @minus
1643    @item @option{plugin}: pointer to plugin structure
1644    @item @option{directory}: directory for searching files
1645    @item @option{callback}: function called for each file found
1646    @end itemize
1647    @*
1648    @emph{Return value:}@*
1649    @*
1650    Aucune.@*
1651    @*
1652    @emph{Exemple :}@*
1653    @*
1654    @code{int callback (t_weechat_plugin *plugin, char *file)}@*
1655    @code{@{}@*
1656    @code{@ @ @ @ plugin->printf_server (plugin, "file: %s", file);}@*
1657    @code{@ @ @ @ return 1;}@*
1658    @code{@}}@*
1659    @code{}@*
1660    @code{...}@*
1661    @code{plugin->exec_on_files (plugin, "/tmp", &callback);}@*
1662    @*
1663    
1664    @item
1665    @command{void printf (t_weechat_plugin *plugin,
1666    char *server, char *channel, char *message, ...)}@*
1667    @*
1668    Display a message on a WeeChat buffer, identified by server and
1669    channel (both may be NULL).@*
1670    
1671    @emph{Arguments:}
1672    @itemize @minus
1673    @item @option{plugin}: pointer to plugin structure
1674    @item @option{server}: name of server to find buffer for message
1675    display (may be NULL)
1676    @item @option{channel}: name of channel to find buffer for message
1677    display (may be NULL)
1678    @item @option{message}: message
1679    @end itemize
1680    @*
1681    @emph{Return value:}@*
1682    @*
1683    None.@*
1684    @*
1685    @emph{Examples:}@*
1686    @*
1687    @code{plugin->printf (NULL, NULL, "hello");}@*
1688    @code{plugin->printf (NULL, "#weechat", "hello");}@*
1689    @code{plugin->printf ("freenode", "#weechat", "hello");}@*
1690    @*
1691    
1692    @item
1693    @command{void printf_server (t_weechat_plugin *plugin,
1694    char *message, ...)}@*
1695    @*
1696    Display a message on server buffer.@*
1697    
1698    @emph{Param@`etres :}
1699    @itemize @minus
1700    @item @option{plugin}: pointer to plugin structure
1701    @item @option{message}: message
1702    @end itemize
1703    @*
1704    @emph{Return value:}@*
1705    @*
1706    None.@*
1707    @*
1708    @emph{Example:}@*
1709    @*
1710    @code{plugin->printf_server ("hello");}@*
1711    @*
1712    
1713    @item
1714    @command{void printf_infobar (t_weechat_plugin *plugin,
1715    int time, char *message, ...)}@*
1716    @*
1717    Display a message in infobar for a specified time.@*
1718    
1719    @emph{Arguments:}
1720    @itemize @minus
1721    @item @option{plugin}: pointer to plugin structure
1722    @item @option{time}: time in seconds for displaying message (0 means
1723    never erased)
1724    @item @option{message}: message
1725    @end itemize
1726    @*
1727    @emph{Return value:}@*
1728    @*
1729    None.@*
1730    @*
1731    @emph{Example:}@*
1732    @*
1733    @code{plugin->printf_infobar (5, "hello");}@*
1734    @*
1735    
1736    @item
1737    @command{t_plugin_msg_handler *msg_handler_add (t_weechat_plugin
1738    *plugin, char *message, t_plugin_handler_func *handler_func,
1739    char *handler_args, void *handler_pointer)}@*
1740    @*
1741    Add an IRC message handler, called when an IRC message is received.@*
1742    
1743    @emph{Arguments:}
1744    @itemize @minus
1745    @item @option{plugin}: pointer to plugin structure
1746    @item @option{message}: IRC message (for example: ``PRIVMSG'')
1747    @item @option{handler_func}: function called when message is received
1748    @item @option{handler_args}: arguments given to function when called
1749    @item @option{handler_pointer}: pointer given to function when called
1750    @end itemize
1751    @*
1752    @emph{Return value:}@*
1753    @*
1754    Pointer to new message handler.@*
1755    @*
1756    @emph{Example:}@*
1757    @*
1758    @code{int msg_kick (t_weechat_plugin *plugin, char *server,
1759    char *command, char *arguments, char *handler_args,
1760    void *handler_pointer)}@*
1761    @code{@{}@*
1762    @code{@ @ @ @ plugin->printf (plugin, server, NULL, "KICK received");}@*
1763    @code{@}}@*
1764    @code{...}@*
1765    @code{plugin->msg_handler_add (plugin, "KICK", &msg_kick, NULL, NULL);}@*
1766    @*
1767    
1768    @item
1769    @command{void msg_handler_remove (t_weechat_plugin *plugin,
1770    t_plugin_msg_handler *msg_handler)}@*
1771    @*
1772    Remove an IRC message handler.@*
1773    
1774    @emph{Param@`etres :}
1775    @itemize @minus
1776    @item @option{plugin}: pointer to plugin structure
1777    @item @option{msg_handler}: handler to remove
1778    @end itemize
1779    @*
1780    @emph{Return value:}@*
1781    @*
1782    None.@*
1783    @*
1784    @emph{Example:}@*
1785    @*
1786    @code{plugin->msg_handler_remove (plugin, my_msg_handler);}@*
1787    @*
1788    
1789    @item
1790    @command{void msg_handler_remove_all (t_weechat_plugin *plugin)}@*
1791    @*
1792    Remove all IRC message handlers for a plugin.@*
1793    
1794    @emph{Arguments:}
1795    @itemize @minus
1796    @item @option{plugin}: pointer to plugin structure
1797    @end itemize
1798    @*
1799    @emph{Return value:}@*
1800    @*
1801    None.@*
1802    @*
1803    @emph{Example:}@*
1804    @*
1805    @code{plugin->msg_handler_remove_all (plugin);}@*
1806    @*
1807    
1808    @item
1809    @command{t_plugin_cmd_handler *cmd_handler_add (t_weechat_plugin
1810    *plugin, char *command, char *description, char *arguments,
1811    char *arguments_description, t_plugin_handler_func *handler_func,
1812    char *handler_args, void *handler_pointer)}@*
1813    @*
1814    Add a WeeChat command handler, called when user uses command
1815    (for example /command).@*
1816    
1817    @emph{Arguments:}
1818    @itemize @minus
1819    @item @option{plugin}: pointer to plugin structure
1820    @item @option{commande}: the new command
1821    @item @option{description}: command description (displayed by /help
1822    command)
1823    @item @option{arguments}: short description of command arguments
1824    (displayed by /help command)
1825    @item @option{arguments_description}: long description of command
1826    arguments (displayed by /help command)
1827    @item @option{handler_func}: function called when comand is executed
1828    @item @option{handler_args}: arguments given to function when called
1829    @item @option{handler_pointer}: pointer given to function when called
1830    @end itemize
1831    @*
1832    @emph{Return value:}@*
1833    @*
1834    Pointer to new command handler.@*
1835    @*
1836    @emph{Example:}@*
1837    @*
1838    @code{int cmd_test (t_weechat_plugin *plugin, char *server,
1839    char *command, char *arguments, char *handler_args,
1840    void *handler_pointer)}@*
1841    @code{@{}@*
1842    @code{@ @ @ @ plugin->printf (plugin, server, NULL, "test command,
1843    file: %s", (arguments) ? arguments : "none");}@*
1844    @code{@}}@*
1845    @code{...}@*
1846    @code{plugin->cmd_handler_add (plugin, "test", "Test command",
1847    "[file]", "file: a file name", &cmd_test, NULL, NULL);}@*
1848    @*
1849    
1850    @item
1851    @command{void cmd_handler_remove (t_weechat_plugin *plugin,
1852    t_plugin_cmd_handler *cmd_handler)}@*
1853    @*
1854    Remove a command handler.@*
1855    
1856    @emph{Arguments:}
1857    @itemize @minus
1858    @item @option{plugin}: pointer to plugin structure
1859    @item @option{cmd_handler}: command handler to remove
1860    @end itemize
1861    @*
1862    @emph{Return value:}@*
1863    @*
1864    None.@*
1865    @*
1866    @emph{Example:}@*
1867    @*
1868    @code{plugin->cmd_handler_remove (plugin, my_cmd_handler);}@*
1869    @*
1870    
1871    @item
1872    @command{void cmd_handler_remove_all (t_weechat_plugin *plugin)}@*
1873    @*
1874    Remove all command handlers for a plugin.@*
1875    
1876    @emph{Arguments:}
1877    @itemize @minus
1878    @item @option{plugin}: pointer to plugin structure
1879    @end itemize
1880    @*
1881    @emph{Return value:}@*
1882    @*
1883    None.@*
1884    @*
1885    @emph{Example :}@*
1886    @*
1887    @code{plugin->cmd_handler_remove_all (plugin);}@*
1888    @*
1889    
1890    @item
1891    @command{void exec_command (t_weechat_plugin
1892    *plugin, char *server, char *channel, char *command)}@*
1893    @*
1894    Execute a WeeChat command (or send a message to a channel).@*
1895    
1896    @emph{Arguments:}
1897    @itemize @minus
1898    @item @option{plugin}: pointer to plugin structure
1899    @item @option{server}: name of server for executing command (may be
1900    NULL)
1901    @item @option{channel}: name of channel for executing command (may be
1902    NULL)
1903    @item @option{command}: command
1904    @end itemize
1905    @*
1906    @emph{Return value:}@*
1907    @*
1908    None.@*
1909    @*
1910    @emph{Examples:}@*
1911    @*
1912    @code{plugin->exec_command (plugin, NULL, NULL, "/help nick");}@*
1913    @code{plugin->exec_command (plugin, "freenode", "#weechat", "hello");}@*
1914    @*
1915    
1916    @item
1917    @command{char *get_info (t_weechat_plugin
1918    *plugin, char *info, char *server, char *channel)}@*
1919    @*
1920    Return an info about WeeChat or a channel.@*
1921    
1922    @emph{Param@`etres :}
1923    @itemize @minus
1924    @item @option{plugin}: pointer to plugin structure
1925    @item @option{info}: name of info to read:
1926    @itemize @minus
1927    @item @option{version}: get WeeChat's version
1928    @item @option{nick}: get nick
1929    @item @option{channel}: get channel name
1930    @item @option{server}: get server name
1931    @item @option{away}: get ``away'' flag
1932    @item @option{weechat_dir}: get WeeChat home dir
1933    @item @option{weechat_libdir}: get WeeChat system lib dir
1934    @item @option{weechat_sharedir}: get WeeChat system share dir
1935    @end itemize
1936    @item @option{server}: name of server for reading info (if needed)
1937    @item @option{channel}: name of channel for reading info (if needed)
1938    @end itemize
1939    @*
1940    @emph{Return value:}@*
1941    @*
1942    Information asked, NULL if not found.@*
1943    Note: result has to be free by a call to ``free'' function after
1944    use.@*
1945    @*
1946    @emph{Examples:}@*
1947    @*
1948    @code{char *version = plugin->get_info (plugin, "version", NULL, NULL);}@*
1949    @code{char *nick = plugin->get_info (plugin, "nick", "freenode", NULL);}@*
1950    @*
1951    
1952    @item
1953    @command{t_plugin_info_dcc *get_dcc_info (t_weechat_plugin *plugin)}@*
1954    @*
1955    Returns list of DCC currently active or finished.@*
1956    
1957    @emph{Arguments:}
1958    @itemize @minus
1959    @item @option{plugin}: pointer to plugin structure
1960    @end itemize
1961    @*
1962    @emph{Return value:}@*
1963    @*
1964    Chained list of DCC.@*
1965    Note: result has to be free by a call to ``free_dcc_info'' function
1966    after use.@*
1967    @*
1968    @emph{Example:}@*
1969    @*
1970    @code{t_plugin_dcc_info *dcc_info = plugin->get_dcc_info (plugin);}@*
1971    @code{for (ptr_dcc = dcc_info; ptr_dcc; ptr_dcc =
1972    ptr_dcc->next_dcc)}@*
1973    @code{@{}@*
1974    @code{@ @ @ @ plugin->printf_server (plugin, "DCC type=%d, with: %s",
1975    ptr_dcc->type, ptr_dcc->nick);}@*
1976    @code{@}}@*
1977    @*
1978    
1979    @item
1980    @command{void free_dcc_info (t_weechat_plugin *plugin,
1981    t_plugin_dcc_info *dcc_info)}@*
1982    @*
1983    Free memory used by a DCC list.@*
1984    
1985    @emph{Param@`etres :}
1986    @itemize @minus
1987    @item @option{plugin}: pointer to plugin structure
1988    @item @option{dcc_info}: pointer to DCC list returned by
1989    ``get_dcc_info'' function
1990    @end itemize
1991    @*
1992    @emph{Return value:}@*
1993    @*
1994    None.@*
1995    @*
1996    @emph{Example:}@*
1997    @*
1998    @code{plugin->free_dcc_info (plugin, dcc_info);}@*
1999    @*
2000    
2001    @item
2002    @command{char *get_config (t_weechat_plugin
2003    *plugin, char *option)}@*
2004    @*
2005    Return value of a WeeChat config option.@*
2006    
2007    @emph{Arguments:}
2008    @itemize @minus
2009    @item @option{plugin}: pointer to plugin structure
2010    @item @option{option}: name of option to read
2011    @end itemize
2012    @*
2013    @emph{Return value:}@*
2014    @*
2015    Value of option, NULL if not found.@*
2016    Note: result has to be free by a call to ``free'' function after
2017    use.@*
2018    @*
2019    @emph{Examples:}@*
2020    @*
2021    @code{char *value1 = plugin->get_config (plugin, "look_set_title");}@*
2022    @code{char *value2 = plugin->get_config (plugin, "freenode.server_autojoin");}@*
2023    @*
2024    
2025    @end itemize
2026    
2027    @subsection Compile plugin
2028    
2029    Compile does not need WeeChat sources, only file
2030    ``weechat-plugin.h''.@*
2031    
2032    To compile a plugin which has one file ``toto.c'' (sous GNU/Linux):@*
2033    @*
2034    gcc -fPIC -Wall -c toto.c@*
2035    gcc -shared -fPIC -o libtoto.so toto.o
2036    
2037    @subsection Load plugin under WeeChat
2038    
2039    Copy ``libtoto.so'' file into general plugins dir (for example
2040    /usr/local/lib/weechat/plugins) or into user's plugins dir (for
2041    example /home/xxxxx/.weechat/plugins).@*
2042    @*
2043    Under WeeChat:@*
2044    @command{/plugin load toto}
2045    
2046    @node Plugin example, Scripts plugins, Write a plugin, Plugins
2047    @section Plugin example
2048    
2049    Full example of plugin, which adds a /double command, which displays
2050    two times arguments on current channel (ok that's not very useful, but
2051    that's just an example!):
2052    
2053    @verbatim
2054    #include <stdlib.h>
2055    
2056    #include "weechat-plugin.h"
2057    
2058    char plugin_name[]        = "Toto";
2059    char plugin_version[]     = "0.1";
2060    char plugin_description[] = "Test plugin for WeeChat";
2061    
2062    /* gestionnaire de commande "/hello" */
2063    
2064    int toto_cmd_double (t_weechat_plugin *plugin, char *server,
2065                        char *command, char *arguments,
2066                        char *handler_args, void *handler_pointer)
2067    {
2068        if (arguments && arguments[0] && (arguments[0] != '/'))
2069        {
2070            plugin->exec_command (plugin, NULL, NULL, arguments);
2071            plugin->exec_command (plugin, NULL, NULL, arguments);
2072        }
2073        return 1;
2074    }
2075    
2076    int weechat_plugin_init (t_weechat_plugin *plugin)
2077    {
2078        plugin->cmd_handler_add (plugin, "double",
2079                                 "Display two times a message",
2080                                 "msg",
2081                                 "msg: message",
2082                                 &toto_cmd_double,
2083                                 NULL, NULL);
2084        return 1;
2085    }
2086    
2087    int weechat_plugin_end (t_weechat_plugin *plugin)
2088    {
2089        /* on ne fait rien ici */
2090        return 1;
2091    }
2092    @end verbatim
2093    
2094    @node Scripts plugins, , Plugin example, Plugins
2095    @section Scripts plugins
2096    
2097    Three plugins are provided with WeeChat to use script languages: Perl,
2098    Python and Ruby.
2099    
2100    @subsection Perl scripts
2101    
2102    @subsubsection Load/unload Perl scripts
2103    
2104  Perl scripts are loaded and unloaded with @command{/perl} command.  Perl scripts are loaded and unloaded with @command{/perl} command.
2105  (type @kbd{/help perl} within WeeChat to get help about command).@*  (type @kbd{/help perl} within WeeChat to get help about command).@*
# Line 1528  Unload all Perl scripts: @kbd{/perl unlo Line 2114  Unload all Perl scripts: @kbd{/perl unlo
2114  List all Perl scripts: @kbd{/perl}@*  List all Perl scripts: @kbd{/perl}@*
2115  @end itemize  @end itemize
2116    
2117  @subsection WeeChat / Perl API  @subsubsection WeeChat / Perl API
2118    
2119  @itemize @bullet  @itemize @bullet
2120  @item  @item
# Line 1548  unloaded (optional parameter, empty stri Line 2134  unloaded (optional parameter, empty stri
2134  @end itemize  @end itemize
2135  @*  @*
2136  @emph{Example:}@*  @emph{Example:}@*
2137    @*
2138  @code{weechat::register ("sample", "1.0", "sample_end", "Sample script!");}@*  @code{weechat::register ("sample", "1.0", "sample_end", "Sample script!");}@*
2139  @*  @*
2140    
# Line 1564  Print message in a channel.@* Line 2151  Print message in a channel.@*
2151  @end itemize  @end itemize
2152  @*  @*
2153  @emph{Examples:}@*  @emph{Examples:}@*
2154    @*
2155  @code{weechat::print ("message");}@*  @code{weechat::print ("message");}@*
2156  @code{weechat::print ("message", "#weechat");}@*  @code{weechat::print ("message", "#weechat");}@*
2157  @code{weechat::print ("message", "#weechat", "freenode");}@*  @code{weechat::print ("message", "#weechat", "freenode");}@*
# Line 1582  Print message in infobar.@* Line 2170  Print message in infobar.@*
2170  @end itemize  @end itemize
2171  @*  @*
2172  @emph{Example:}@*  @emph{Example:}@*
2173    @*
2174  @code{weechat::print_infobar (5, "message");}@*  @code{weechat::print_infobar (5, "message");}@*
2175  @*  @*
2176    
# Line 1601  RFC 2812: @uref{ftp://ftp.rfc-editor.org Line 2190  RFC 2812: @uref{ftp://ftp.rfc-editor.org
2190  @end itemize  @end itemize
2191  @*  @*
2192  @emph{Example:}@*  @emph{Example:}@*
2193    @*
2194  @code{weechat::add_message_handler ("privmsg", my_function);}@*  @code{weechat::add_message_handler ("privmsg", my_function);}@*
2195  @code{sub my_function}@*  @code{sub my_function}@*
2196  @code{@{ }@*  @code{@{ }@*
# Line 1624  This name may be existing command, so th Line 2214  This name may be existing command, so th
2214  Perl function. Be careful when overriding WeeChat commands, they'll not be  Perl function. Be careful when overriding WeeChat commands, they'll not be
2215  available until your Perl script will be unloaded.  available until your Perl script will be unloaded.
2216  @item @option{function}: Perl function linked with command  @item @option{function}: Perl function linked with command
2217    @item @option{description}: command description (displayed by /help
2218    command)
2219    @item @option{arguments}: short description of command arguments
2220    (displayed by /help command)
2221    @item @option{arguments_description}: long description of command
2222    arguments (displayed by /help command)
2223  @end itemize  @end itemize
2224  @*  @*
2225  @emph{Example:}@*  @emph{Example:}@*
2226    @*
2227  @code{weechat::add_command_handler ("command", my_command);}@*  @code{weechat::add_command_handler ("command", my_command);}@*
2228  @code{sub my_command}@*  @code{sub my_command}@*
2229  @code{@{ }@*  @code{@{ }@*
# Line 1648  Execute a command or send a message to a Line 2245  Execute a command or send a message to a
2245  @end itemize  @end itemize
2246  @*  @*
2247  @emph{Examples:}@*  @emph{Examples:}@*
2248    @*
2249  @code{weechat::command ("hello world!");}@*  @code{weechat::command ("hello world!");}@*
2250  @code{weechat::command ("/kick toto please leave this chan", "#weechat");}@*  @code{weechat::command ("/kick toto please leave this chan", "#weechat");}@*
2251  @code{weechat::command ("/nick newnick", "", "freenode");}@*  @code{weechat::command ("/nick newnick", "", "freenode");}@*
# Line 1661  Get various info about WeeChat, server o Line 2259  Get various info about WeeChat, server o
2259  @emph{Arguments:}  @emph{Arguments:}
2260  @itemize @minus  @itemize @minus
2261  @item @option{name}: name of info to retrieve:  @item @option{name}: name of info to retrieve:
2262    @itemize @minus
2263    @item @option{version}: get WeeChat version
2264    @item @option{nick}: get nickname
2265    @item @option{channel}: get channel name
2266    @item @option{server}: get server name
2267    @item @option{away}: get ``away'' flag
2268    @item @option{weechat_dir}: get WeeChat home dir
2269    @item @option{weechat_libdir}: get WeeChat system lib dir
2270    @item @option{weechat_sharedir}: get WeeChat system share dir
2271    
2272    @end itemize
2273  @item @option{server}: internal name of server  @item @option{server}: internal name of server
2274    @end itemize
2275    @*
2276    @emph{Examples:}@*
2277    @*
2278    @code{$version = weechat::get_info("version");}@*
2279    @code{$nick = weechat::get_info("nick", "freenode");}@*
2280    @*
2281    
2282    @item
2283    @command{weechat::get_dcc_info ( );}@*
2284    @*
2285    Get DCC list.@*
2286    
2287    Returned array has following fields:
2288  @itemize @minus  @itemize @minus
2289  @item @option{0 or version}: get WeeChat version  @item server: IRC server
2290  @item @option{1 or nick}: get nickname  @item channel: IRC channel
2291  @item @option{2 or channel}: get channel name  @item type: DCC type:
2292  @item @option{3 or server}: get server name  @itemize @minus
2293  @item @option{4 or weechatdir}: get WeeChat home directory  @item 0: chat (received)
2294  @item @option{5 or away}: get away flag for server  @item 1: chat (sent)
2295    @item 2: file (receiving)
2296    @item 3: file (sending)
2297  @end itemize  @end itemize
2298    @item status: DCC status:
2299    @itemize @minus
2300    @item 0: waiting
2301    @item 1: connecting
2302    @item 2: active
2303    @item 3: done
2304    @item 4: failed
2305    @item 5: aborted
2306    @end itemize
2307    @item start_time: date/time of DCC creation
2308    @item start_transfer: date/time of transfer start
2309    @item addr: remote address
2310    @item port: port used for DCC
2311    @item nick: remote nick
2312    @item filename: filename
2313    @item local_filename: local filename
2314    @item size: file size
2315    @item pos: current position in file
2316    @item start_resume: restart position after interruption
2317    @item bytes_per_sec: bytes sent/received per second
2318    @end itemize
2319    @*
2320    
2321    @item
2322    @command{weechat::get_config ( name );}@*
2323    @*
2324    Get WeeChat config option value.@*
2325    
2326    @emph{Arguments:}
2327    @itemize @minus
2328    @item @option{name}: name of option
2329  @end itemize  @end itemize
2330  @*  @*
2331  @emph{Examples:}@*  @emph{Examples:}@*
2332  @code{$version = get_info("version");}@*  @*
2333  @code{$nick = get_info("nick", "freenode");}@*  @code{$value1 = weechat::get_config ("look_set_title");}@*
2334    @code{$value2 = weechat::get_config ("freenode.server_autojoin");}@*
2335  @*  @*
2336    
2337  @end itemize  @end itemize
2338    
2339  @node Python scripts, Ruby scripts, Perl scripts, Extensions  @subsection Python scripts
 @section Python scripts  
2340    
2341  @subsection Load/unload Python scripts  @subsubsection Load/unload Python scripts
2342    
2343  Python scripts are loaded and unloaded with @command{/python} command.  Python scripts are loaded and unloaded with @command{/python} command.
2344  (type @kbd{/help python} within WeeChat to get help about command).@*  (type @kbd{/help python} within WeeChat to get help about command).@*
# Line 1697  Unload all Python scripts: @kbd{/python Line 2353  Unload all Python scripts: @kbd{/python
2353  List all Python scripts: @kbd{/python}@*  List all Python scripts: @kbd{/python}@*
2354  @end itemize  @end itemize
2355    
2356  @subsection WeeChat / Python API  @subsubsection WeeChat / Python API
2357    
2358  @itemize @bullet  @itemize @bullet
2359  @item  @item
# Line 1717  unloaded (optional parameter, empty stri Line 2373  unloaded (optional parameter, empty stri
2373  @end itemize  @end itemize
2374  @*  @*
2375  @emph{Example:}@*  @emph{Example:}@*
2376    @*
2377  @code{weechat.register ("sample", "1.0", "sample_end", "Sample script!")}@*  @code{weechat.register ("sample", "1.0", "sample_end", "Sample script!")}@*
2378  @*  @*
2379    
# Line 1733  Print message in a channel.@* Line 2390  Print message in a channel.@*
2390  @end itemize  @end itemize
2391  @*  @*
2392  @emph{Examples:}@*  @emph{Examples:}@*
2393    @*
2394  @code{weechat.prnt ("message")}@*  @code{weechat.prnt ("message")}@*
2395  @code{weechat.prnt ("message", "#weechat")}@*  @code{weechat.prnt ("message", "#weechat")}@*
2396  @code{weechat.prnt ("message", "#weechat", "freenode")}@*  @code{weechat.prnt ("message", "#weechat", "freenode")}@*
# Line 1751  Print message in infobar.@* Line 2409  Print message in infobar.@*
2409  @end itemize  @end itemize
2410  @*  @*
2411  @emph{Example:}@*  @emph{Example:}@*
2412    @*
2413  @code{weechat.print_infobar (5, "message")}@*  @code{weechat.print_infobar (5, "message")}@*
2414  @*  @*
2415    
# Line 1770  RFC 2812: @uref{ftp://ftp.rfc-editor.org Line 2429  RFC 2812: @uref{ftp://ftp.rfc-editor.org
2429  @end itemize  @end itemize
2430  @*  @*
2431  @emph{Example:}@*  @emph{Example:}@*
2432    @*
2433  @code{weechat.add_message_handler ("privmsg", my_function)}@*  @code{weechat.add_message_handler ("privmsg", my_function)}@*
2434  @code{def my_function(server, args):}@*  @code{def my_function(server, args):}@*
2435  @code{@ @ @ @ weechat.prnt("server="+server)}@*  @code{@ @ @ @ weechat.prnt("server="+server)}@*
# Line 1791  This name may be existing command, so th Line 2451  This name may be existing command, so th
2451  Python function. Be careful when overriding WeeChat commands, they'll not be  Python function. Be careful when overriding WeeChat commands, they'll not be
2452  available until your Python script will be unloaded.  available until your Python script will be unloaded.
2453  @item @option{function}: Python function linked with command  @item @option{function}: Python function linked with command
2454    @item @option{description}: command description (displayed by /help
2455    command)
2456    @item @option{arguments}: short description of command arguments
2457    (displayed by /help command)
2458    @item @option{arguments_description}: long description of command
2459    arguments (displayed by /help command)
2460  @end itemize  @end itemize
2461  @*  @*
2462  @emph{Example:}@*  @emph{Example:}@*
2463    @*
2464  @code{weechat.add_command_handler ("command", my_command)}@*  @code{weechat.add_command_handler ("command", my_command)}@*
2465  @code{def my_command(server, args):}@*  @code{def my_command(server, args):}@*
2466  @code{@ @ @ @ weechat.prnt("server:"+server+" arguments:"+args)}@*  @code{@ @ @ @ weechat.prnt("server:"+server+" arguments:"+args)}@*
# Line 1812  Execute a command or send a message to a Line 2479  Execute a command or send a message to a
2479  @end itemize  @end itemize
2480  @*  @*
2481  @emph{Examples:}@*  @emph{Examples:}@*
2482    @*
2483  @code{weechat.command ("hello world!")}@*  @code{weechat.command ("hello world!")}@*
2484  @code{weechat.command ("/kick toto please leave this chan", "#weechat")}@*  @code{weechat.command ("/kick toto please leave this chan", "#weechat")}@*
2485  @code{weechat.command ("/nick newnick", "", "freenode")}@*  @code{weechat.command ("/nick newnick", "", "freenode")}@*
# Line 1826  Get various info about WeeChat, server o Line 2494  Get various info about WeeChat, server o
2494  @emph{Arguments:}  @emph{Arguments:}
2495  @itemize @minus  @itemize @minus
2496  @item @option{name}: name of info to retrieve:  @item @option{name}: name of info to retrieve:
 @item @option{server}: internal name of server  
2497  @itemize @minus  @itemize @minus
2498  @item @option{0 or version}: get WeeChat version  @item @option{version}: get WeeChat version
2499  @item @option{1 or nick}: get nickname  @item @option{nick}: get nickname
2500  @item @option{2 or channel}: get channel name  @item @option{channel}: get channel name
2501  @item @option{3 or server}: get server name  @item @option{server}: get server name
2502  @item @option{4 or weechatdir}: get WeeChat home directory  @item @option{away}: get ``away'' flag
2503  @item @option{5 or away}: get away flag for server  @item @option{weechat_dir}: get WeeChat home dir
2504    @item @option{weechat_libdir}: get WeeChat system lib dir
2505    @item @option{weechat_sharedir}: get WeeChat system share dir
2506  @end itemize  @end itemize
2507    @item @option{server}: internal name of server
2508  @end itemize  @end itemize
2509  @*  @*
2510  @emph{Examples:}@*  @emph{Examples:}@*
2511    @*
2512  @code{$version = weechat.get_info("version")}@*  @code{$version = weechat.get_info("version")}@*
2513  @code{$nick = weechat.get_info("nick", "freenode")}@*  @code{$nick = weechat.get_info("nick", "freenode")}@*
2514  @*  @*
2515    
2516    @item
2517    @command{weechat.get_dcc_info ( );}@*
2518    @*
2519    Get DCC list.@*
2520    
2521    Returned array has following fields:
2522    @itemize @minus
2523    @item server: IRC server
2524    @item channel: IRC channel
2525    @item type: DCC type:
2526    @itemize @minus
2527    @item 0: chat (received)
2528    @item 1: chat (sent)
2529    @item 2: file (receiving)
2530    @item 3: file (sending)
2531    @end itemize
2532    @item status: DCC status:
2533    @itemize @minus
2534    @item 0: waiting
2535    @item 1: connecting
2536    @item 2: active
2537    @item 3: done
2538    @item 4: failed
2539    @item 5: aborted
2540    @end itemize
2541    @item start_time: date/time of DCC creation
2542    @item start_transfer: date/time of transfer start
2543    @item addr: remote address
2544    @item port: port used for DCC
2545    @item nick: remote nick
2546    @item filename: filename
2547    @item local_filename: local filename
2548    @item size: file size
2549    @item pos: current position in file
2550    @item start_resume: restart position after interruption
2551    @item bytes_per_sec: bytes sent/received per second
2552    @end itemize
2553    @*
2554    
2555    @item
2556    @command{weechat.get_config ( name );}@*
2557    @*
2558    Get WeeChat config option value.@*
2559    
2560    @emph{Arguments:}
2561    @itemize @minus
2562    @item @option{name}: name of option
2563    @end itemize
2564    @*
2565    @emph{Examples:}@*
2566    @*
2567    @code{$value1 = weechat.get_config ("look_set_title");}@*
2568    @code{$value2 = weechat.get_config ("freenode.server_autojoin");}@*
2569    @*
2570    
2571  @end itemize  @end itemize
2572    
2573  @node Ruby scripts, , Python scripts, Extensions  @subsection Ruby scripts
 @section Ruby scripts  
2574    
2575  Not developed!  Not developed!
2576    
2577    
2578  @c **************************** Authors / Support *****************************  @c **************************** Authors / Support *****************************
2579    
2580  @node Authors / Support, , Extensions, Top  @node Authors / Support, , Plugins, Top
2581  @chapter Authors / Support  @chapter Authors / Support
2582    
2583  @ifhtml  @ifhtml

Legend:
Removed from v.1.42  
changed lines
  Added in v.1.43

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26