weechat/doc/fr/dev/plugin_script_api.fr.xml

<?xml version="1.0" encoding="UTF-8"?>

<!--

WeeChat documentation (french 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="secExtensionsScripts">
  <title>Extensions pour scripts</title>
  
  <para>
    Cinq extensions sont fournies en standard avec WeeChat pour utiliser
    des langages de script : Perl, Python, Ruby, Lua et Tcl.
  </para>
  
  <section id="secChargerDechargerScripts">
    <title>Charger / décharger des scripts</title>
    
    <para>
      Les scripts sont chargés et déchargés avec les commandes
      <command>/perl</command>, <command>/python</command>,
      <command>/ruby</command>, <command>/lua</command>
      et <command>/tcl</command> (tapez <command>/help</command> dans WeeChat
      pour obtenir de l'aide sur les commandes).
    </para>
    
    <para>
      Exemples :
      <itemizedlist>
        <listitem>
          <para>
            Charger un script Perl :
            <command><userinput>/perl load /tmp/essai.pl</userinput></command>
          </para>
        </listitem>
        <listitem>
          <para>
            Lister les scripts Perl chargés :
            <command><userinput>/perl</userinput></command>
          </para>
        </listitem>
        <listitem>
          <para>
            Charger un script Python :
            <command><userinput>/python load /tmp/essai.py</userinput></command>
          </para>
        </listitem>
        <listitem>
          <para>
            Lister les scripts Python chargés :
            <command><userinput>/python</userinput></command>
          </para>
        </listitem>
        <listitem>
          <para>
            Charger un script Ruby :
            <command><userinput>/ruby load /tmp/essai.rb</userinput></command>
          </para>
        </listitem>
        <listitem>
          <para>
            Lister les scripts Ruby chargés :
            <command><userinput>/ruby</userinput></command>
          </para>
        </listitem>
        <listitem>
          <para>
            Charger un script Lua :
            <command><userinput>/lua load /tmp/essai.lua</userinput></command>
          </para>
        </listitem>
        <listitem>
          <para>
            Lister les scripts Lua chargés :
            <command><userinput>/lua</userinput></command>
          </para>
        </listitem>
        <listitem>
          <para>
            Charger un script Tcl :
            <command><userinput>/tcl load /tmp/essai.tcl</userinput></command>
          </para>
        </listitem>
        <listitem>
          <para>
            Lister les scripts Tcl chargés :
            <command><userinput>/tcl</userinput></command>
          </para>
        </listitem>
      </itemizedlist>
    </para>
    
  </section>
  
  <section id="secSyntaxeParLangage">
    <title>Syntaxe par langage</title>
    
    <section id="secScriptPerl">
      <title>Perl</title>
      
      <para>
        Dans un script Perl WeeChat, toutes les fonctions et variables
        de l'interface sont préfixées par "<literal>weechat::</literal>".
        Exemple :
<screen>
weechat::register("test", "Auteur &lt;auteur\@domaine.com&gt;", "1.0",
                  "GPL3", "Description du script", "au_revoir", "");
</screen>
      </para>
      
    </section>
    
    <section id="secScriptPython">
      <title>Python</title>
      
      <para>
        Un script Python WeeChat doit commencer par importer weechat :
        <screen>import weechat</screen>
      </para>
      
      <para>
        Toutes les fonctions et variables de l'interface sont préfixées
        par "<literal>weechat.</literal>".
        Exemple :
<screen>
weechat.register("test", "Auteur &lt;auteur@domaine.com&gt;", "1.0",
                 "GPL3", "Description du script", "au_revoir", "")
</screen>
      </para>
      
    </section>
    
    <section id="secScriptRuby">
      <title>Ruby</title>
      
      <para>
        Dans un script Ruby WeeChat, tout le code doit être dans des
        fonctions. Pour le code principal, vous devez définir une
        fonction "<literal>weechat_init</literal>", qui est appelée
        automatiquement quand le script est chargé par WeeChat.
        Exemple :
<screen>
def weechat_init
    Weechat.register("test", "Auteur &lt;auteur@domaine.com&gt;", "1.0",
                     "GPL3", "Description du script", "au_revoir", "")
    return Weechat::WEECHAT_RC_OK
end
</screen>
      </para>
      
      <para>
        Toutes les fonctions de l'interface sont préfixées par
        "<literal>Weechat.</literal>" et les variables par
        "<literal>Weechat::</literal>".
      </para>
      
    </section>
    
    <section id="secScriptLua">
      <title>Lua</title>
      
      <para>
        Dans un script Lua WeeChat, toutes les fonctions de l'interface
        sont préfixées par "<literal>weechat.</literal>".
        Les variables sont préfixées par "<literal>weechat.</literal>" et
        suffixées par "<literal>()</literal>".
        Exemple :
<screen>
weechat.register("test", "Auteur &lt;auteur@domaine.com&gt;", "1.0",
                 "GPL3", "Description du script", "au_revoir", "")
</screen>
      </para>
      
    </section>
    
    <section id="secScriptTcl">
      <title>Tcl</title>
      
      <para>
        Dans un script Tcl WeeChat, toutes les fonctions de l'interface
        sont préfixées par "<literal>weechat::</literal>".
        Les variables sont préfixées par "<literal>$weechat::</literal>".
        Exemple :
<screen>
weechat::register "test" "Auteur &lt;auteur@domaine.com&gt;" "1.0" "GPL3" "Description du script" "au_revoir" ""
</screen>
      </para>
      
    </section>
    
  </section>
  
  <section id="secInterfaceWeeChatScripts">
    <title>Interface WeeChat / scripts</title>
    
    <section id="sec_script_register">
      <title>register</title>
      
      <para>
        Prototype Perl :
        <command>
          weechat::register(nom, auteur, version, licence, description,
          fonction_de_fin, charset);
        </command>
      </para>
      <para>
        Prototype Python :
        <command>
          weechat.register(nom, auteur, version, licence, description,
          fonction_de_fin, charset)
        </command>
      </para>
      <para>
        Prototype Ruby :
        <command>
          Weechat.register(nom, auteur, version, licence, description,
          fonction_de_fin, charset)
        </command>
      </para>
      <para>
        Prototype Lua :
        <command>
          weechat.register(nom, auteur, version, licence, description,
          fonction_de_fin, charset)
        </command>
      </para>
      <para>
        Prototype Tcl :
        <command>
          weechat::register nom auteur version licence description
          fonction_de_fin charset
        </command>
      </para>
      <para>
        C'est la première fonction à appeler dans le script.
        Tout script pour WeeChat doit appeler cette fonction.
      </para>
      <para>
        Paramètres :
        <itemizedlist>
          <listitem>
            <para>
              <option>nom</option> : nom unique pour identifier le script
              (chaque script doit avoir un nom différent)
            </para>
          </listitem>
          <listitem>
            <para>
              <option>auteur</option> : chaîne avec l'auteur (peut include
              nom, pseudo, e-mail, etc...)
            </para>
          </listitem>
          <listitem>
            <para>
              <option>version</option> : version du script
            </para>
          </listitem>
          <listitem>
            <para>
              <option>description</option> : brève description du script
            </para>
          </listitem>
          <listitem>
            <para>
              <option>fonction_de_fin</option> : fonction appelée quand
              le script est déchargé (paramètre facultatif, une chaîne
              vide signifiant qu'il n'y a pas de fonction à appeler)
            </para>
          </listitem>
          <listitem>
            <para>
              <option>charset</option> : jeu de caractères du script, à
              préciser si le script n'est PAS écrit en UTF-8 (vous pouvez
              laisser blanc pour un script UTF-8, c'est le jeu de caractère
              par défaut)
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
        Valeur renvoyée : 1 si le script a été enregistré, 0 si une erreur
        s'est produite.
      </para>
      <para>
        Exemples :
<screen>
# perl
weechat::register("test", "Auteur &lt;auteur\@domaine.com&gt;", "1.0",
                  "GPL3", "Description du script", "au_revoir", "");

# python
weechat.register("test", "Auteur &lt;auteur@domaine.com&gt;", "1.0",
                 "GPL3", "Description du script", "au_revoir", "")

# ruby
Weechat.register("test", "Auteur &lt;auteur@domaine.com&gt;", "1.0",
                 "GPL3", "Description du script", "au_revoir", "")

-- lua
weechat.register("test", "Auteur &lt;auteur@domaine.com&gt;", "1.0",
                 "GPL3", "Description du script", "au_revoir", "")

# tcl
weechat::register "test" "Auteur &lt;auteur@domaine.com&gt;" "1.0" "GPL3" "Description du script" "au_revoir" ""
</screen>
      </para>
    </section>

    <section id="secOther_functions">
      <title>Autres fonctions</title>
      
      <para>
        Les fonctions suivantes sont dans l'API scripts (pour la description,
        voir <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>