Changeset 74fc22a for

Jan 10, 2008, 3:48:00 PM (13 years ago)
Nelson Elhage <>
master, barnowl_perlaim, debian, release-1.4, release-1.5, release-1.6, release-1.7, release-1.8, release-1.9
Document (nearly) every public function in the BarnOwl:: namespace
1 edited



    r18fb3d4f r74fc22a  
    1515package BarnOwl;
     17=head1 NAME
     21=head1 DESCRIPTION
     23The BarnOwl module contains the core of BarnOwl's perl
     24bindings. Source in this module is also run at startup to bootstrap
     25barnowl by defining things like the default style.
     27=for NOTE
     28These following functions are defined in perlglue.xs. Keep the
     29documentation here in sync with the user-visible commands defined
     32=head2 command STRING
     34Executes a BarnOwl command in the same manner as if the user had
     35executed it at the BarnOwl command prompt. If the command returns a
     36value, return it as a string, otherwise return undef.
     38=head2 getcurmsg
     40Returns the current message as a C<BarnOwl::Message> subclass, or
     41undef if there is no message selected
     43=head2 getnumcols
     45Returns the width of the display window BarnOwl is currently using
     47=head2 getidletime
     49Returns the length of time since the user has pressed a key, in
     52=head2 zephyr_getrealm
     54Returns the zephyr realm barnowl is running in
     56=head2 zephyr_getsender
     58Returns the fully-qualified name of the zephyr sender barnowl is
     59running as, e.g. C<nelhage@ATHENA.MIT.EDU>
     61=head2 zephyr_zwrite COMMAND MESSAGE
     63Sends a zephyr programmatically. C<COMMAND> should be a C<zwrite>
     64command line, and C<MESSAGE> is the zephyr body to send.
     66=head2 ztext_stylestrip STRING
     68Strips zephyr formatting from a string and returns the result
     70=head2 queue_message MESSAGE
     72Enqueue a message in the BarnOwl message list, logging it and
     73processing it appropriately. C<MESSAGE> should be an instance of
     74BarnOwl::Message or a subclass.
     76=head2 admin_message HEADER BODY
     78Display a BarnOwl B<Admin> message, with the given header and body.
     80=head2 start_question PROMPT CALLBACK
     82Displays C<PROMPT> on the screen and lets the user enter a line of
     83text, and calls C<CALLBACK>, which must be a perl subroutine
     84reference, with the text the user entered
     86=head2 start_password PROMPT CALLBACK
     88Like C<start_question>, but echoes the user's input as C<*>s when they
     91=head2 start_editwin PROMPT CALLBACK
     93Like C<start_question>, but displays C<PROMPT> on a line of its own
     94and opens the editwin. If the user cancels the edit win, C<CALLBACK>
     95is not invoked.
     97=head2 get_data_dir
     99Returns the BarnOwl system data directory, where system libraries and
     100modules are stored
     102=head2 get_config_dir
     104Returns the BarnOwl user configuration directory, where user modules
     105and configuration are stored (by default, C<$HOME/.owl>)
     107=head2 popless_text TEXT
     109Show a popup window containing the given C<TEXT>
     111=head2 popless_ztext TEXT
     113Show a popup window containing the provided zephyr-formatted C<TEXT>
     115=head2 error STRING
     117Reports an error and log it in `show errors'. Note that in any
     118callback or hook called in perl code from BarnOwl, a C<die> will be
     119caught and passed to C<error>.
     121=head2 getnumcolors
     123Returns the number of colors this BarnOwl is capable of displaying
    17128BEGIN {
    46157    return &BarnOwl::Hooks::_receive_msg($m);
     160=head2 AUTOLOAD
     161 has a C<AUTOLOAD> method that translates unused names in
     163the BarnOwl:: namespace to a call to BarnOwl::command() with that
     164command. Underscores are also translated to C<->s, so you can do
     165e.g. C<BarnOwl::start_command()> and it will be translated into
     168So, if you're looking for functionality that you can't find in the
     169perl interface, check C<:show commands> or C<commands.c> in the
     170BarnOwl source tree -- there's a good chance it exists as a BarnOwl
     173=head3 BUGS
     175There are horrible quoting issues here. The AUTOLOAD simple joins your
     176commands with spaces and passes them unmodified to C<::command>
    49180# make BarnOwl::<command>("foo") be aliases to BarnOwl::command("<command> foo");
    64195ARGS should be a hashref containing any or all of C<summary>,
    65 C<usage>, or C<description> keys.
     196C<usage>, or C<description> keys:
     198=over 4
     200=item summary
     202A one-line summary of the purpose of the command
     204=item usage
     206A one-line usage synopsis, showing available options and syntax
     208=item description
     210A longer description of the syntax and semantics of the command,
     211explaining usage and options
Note: See TracChangeset for help on using the changeset viewer.