Changeset 74fc22a for perlwrap.pm


Ignore:
Timestamp:
Jan 10, 2008, 3:48:00 PM (13 years ago)
Author:
Nelson Elhage <nelhage@mit.edu>
Branches:
master, barnowl_perlaim, debian, release-1.4, release-1.5, release-1.6, release-1.7, release-1.8, release-1.9
Children:
b68342b
Parents:
635881c
Message:
Document (nearly) every public function in the BarnOwl:: namespace
File:
1 edited

Legend:

Unmodified
Added
Removed
  • perlwrap.pm

    r18fb3d4f r74fc22a  
    1414
    1515package BarnOwl;
     16
     17=head1 NAME
     18
     19BarnOwl
     20
     21=head1 DESCRIPTION
     22
     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.
     26
     27=for NOTE
     28These following functions are defined in perlglue.xs. Keep the
     29documentation here in sync with the user-visible commands defined
     30there!
     31
     32=head2 command STRING
     33
     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.
     37
     38=head2 getcurmsg
     39
     40Returns the current message as a C<BarnOwl::Message> subclass, or
     41undef if there is no message selected
     42
     43=head2 getnumcols
     44
     45Returns the width of the display window BarnOwl is currently using
     46
     47=head2 getidletime
     48
     49Returns the length of time since the user has pressed a key, in
     50seconds.
     51
     52=head2 zephyr_getrealm
     53
     54Returns the zephyr realm barnowl is running in
     55
     56=head2 zephyr_getsender
     57
     58Returns the fully-qualified name of the zephyr sender barnowl is
     59running as, e.g. C<nelhage@ATHENA.MIT.EDU>
     60
     61=head2 zephyr_zwrite COMMAND MESSAGE
     62
     63Sends a zephyr programmatically. C<COMMAND> should be a C<zwrite>
     64command line, and C<MESSAGE> is the zephyr body to send.
     65
     66=head2 ztext_stylestrip STRING
     67
     68Strips zephyr formatting from a string and returns the result
     69
     70=head2 queue_message MESSAGE
     71
     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.
     75
     76=head2 admin_message HEADER BODY
     77
     78Display a BarnOwl B<Admin> message, with the given header and body.
     79
     80=head2 start_question PROMPT CALLBACK
     81
     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
     85
     86=head2 start_password PROMPT CALLBACK
     87
     88Like C<start_question>, but echoes the user's input as C<*>s when they
     89input.
     90
     91=head2 start_editwin PROMPT CALLBACK
     92
     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.
     96
     97=head2 get_data_dir
     98
     99Returns the BarnOwl system data directory, where system libraries and
     100modules are stored
     101
     102=head2 get_config_dir
     103
     104Returns the BarnOwl user configuration directory, where user modules
     105and configuration are stored (by default, C<$HOME/.owl>)
     106
     107=head2 popless_text TEXT
     108
     109Show a popup window containing the given C<TEXT>
     110
     111=head2 popless_ztext TEXT
     112
     113Show a popup window containing the provided zephyr-formatted C<TEXT>
     114
     115=head2 error STRING
     116
     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>.
     120
     121=head2 getnumcolors
     122
     123Returns the number of colors this BarnOwl is capable of displaying
     124
     125=cut
     126
    16127
    17128BEGIN {
     
    46157    return &BarnOwl::Hooks::_receive_msg($m);
    47158}
     159
     160=head2 AUTOLOAD
     161
     162BarnOwl.pm 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
     166C<start-command>.
     167
     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
     171command.
     172
     173=head3 BUGS
     174
     175There are horrible quoting issues here. The AUTOLOAD simple joins your
     176commands with spaces and passes them unmodified to C<::command>
     177
     178=cut
    48179
    49180# make BarnOwl::<command>("foo") be aliases to BarnOwl::command("<command> foo");
     
    63194
    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:
     197
     198=over 4
     199
     200=item summary
     201
     202A one-line summary of the purpose of the command
     203
     204=item usage
     205
     206A one-line usage synopsis, showing available options and syntax
     207
     208=item description
     209
     210A longer description of the syntax and semantics of the command,
     211explaining usage and options
     212
     213=back
    66214
    67215=cut
Note: See TracChangeset for help on using the changeset viewer.