Changeset 74fc22a

Timestamp:

Jan 10, 2008, 3:48:00 PM (16 years ago)

Author:

Nelson Elhage <nelhage@mit.edu>

Branches:

master, barnowl_perlaim, debian, release-1.10, 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

Files:

• perlglue.xs (modified) (1 diff)
• perlwrap.pm (modified) (3 diffs)

perlglue.xs

@@ -13 +13 @@
 #define SV_IS_CODEREF(sv) (SvROK((sv)) && SvTYPE(SvRV((sv))) == SVt_PVCV)
 
-MODULE = BarnOwl                PACKAGE = BarnOwl               
+MODULE = BarnOwl                PACKAGE = BarnOwl
+
+        /*************************************************************
+         * NOTE
+         *************************************************************
+         * These functions, when they are intended to be user-visible,
+         * are document in perlwrap.pm. If you add functions to this
+         * file, add the appropriate documentation there!
+         *
+         * If the function is simple enough, we simply define its
+         * entire functionality here in XS. If, however, it needs
+         * complex argument processing or something, we define a
+         * simple version here that takes arguments in as flat a
+         * manner as possible, to simplify the XS code, with a name
+         * with a trailing `_internal', and write a perl wrapper in
+         * perlwrap.pm that munges the arguments as appropriate and
+         * calls the internal version.
+         */
 
 char *

perlwrap.pm

@@ -14 +14 @@
 
 package BarnOwl;
+
+=head1 NAME
+
+BarnOwl
+
+=head1 DESCRIPTION
+
+The BarnOwl module contains the core of BarnOwl's perl
+bindings. Source in this module is also run at startup to bootstrap
+barnowl by defining things like the default style.
+
+=for NOTE
+These following functions are defined in perlglue.xs. Keep the
+documentation here in sync with the user-visible commands defined
+there!
+
+=head2 command STRING
+
+Executes a BarnOwl command in the same manner as if the user had
+executed it at the BarnOwl command prompt. If the command returns a
+value, return it as a string, otherwise return undef.
+
+=head2 getcurmsg
+
+Returns the current message as a C<BarnOwl::Message> subclass, or
+undef if there is no message selected
+
+=head2 getnumcols
+
+Returns the width of the display window BarnOwl is currently using
+
+=head2 getidletime
+
+Returns the length of time since the user has pressed a key, in
+seconds.
+
+=head2 zephyr_getrealm
+
+Returns the zephyr realm barnowl is running in
+
+=head2 zephyr_getsender
+
+Returns the fully-qualified name of the zephyr sender barnowl is
+running as, e.g. C<nelhage@ATHENA.MIT.EDU>
+
+=head2 zephyr_zwrite COMMAND MESSAGE
+
+Sends a zephyr programmatically. C<COMMAND> should be a C<zwrite>
+command line, and C<MESSAGE> is the zephyr body to send.
+
+=head2 ztext_stylestrip STRING
+
+Strips zephyr formatting from a string and returns the result
+
+=head2 queue_message MESSAGE
+
+Enqueue a message in the BarnOwl message list, logging it and
+processing it appropriately. C<MESSAGE> should be an instance of
+BarnOwl::Message or a subclass.
+
+=head2 admin_message HEADER BODY
+
+Display a BarnOwl B<Admin> message, with the given header and body.
+
+=head2 start_question PROMPT CALLBACK
+
+Displays C<PROMPT> on the screen and lets the user enter a line of
+text, and calls C<CALLBACK>, which must be a perl subroutine
+reference, with the text the user entered
+
+=head2 start_password PROMPT CALLBACK
+
+Like C<start_question>, but echoes the user's input as C<*>s when they
+input.
+
+=head2 start_editwin PROMPT CALLBACK
+
+Like C<start_question>, but displays C<PROMPT> on a line of its own
+and opens the editwin. If the user cancels the edit win, C<CALLBACK>
+is not invoked.
+
+=head2 get_data_dir
+
+Returns the BarnOwl system data directory, where system libraries and
+modules are stored
+
+=head2 get_config_dir
+
+Returns the BarnOwl user configuration directory, where user modules
+and configuration are stored (by default, C<$HOME/.owl>)
+
+=head2 popless_text TEXT
+
+Show a popup window containing the given C<TEXT>
+
+=head2 popless_ztext TEXT
+
+Show a popup window containing the provided zephyr-formatted C<TEXT>
+
+=head2 error STRING
+
+Reports an error and log it in `show errors'. Note that in any
+callback or hook called in perl code from BarnOwl, a C<die> will be
+caught and passed to C<error>.
+
+=head2 getnumcolors
+
+Returns the number of colors this BarnOwl is capable of displaying
+
+=cut
+
 
 BEGIN {
@@ -46 +157 @@
     return &BarnOwl::Hooks::_receive_msg($m);
 }
+
+=head2 AUTOLOAD
+
+BarnOwl.pm has a C<AUTOLOAD> method that translates unused names in
+the BarnOwl:: namespace to a call to BarnOwl::command() with that
+command. Underscores are also translated to C<->s, so you can do
+e.g. C<BarnOwl::start_command()> and it will be translated into
+C<start-command>.
+
+So, if you're looking for functionality that you can't find in the
+perl interface, check C<:show commands> or C<commands.c> in the
+BarnOwl source tree -- there's a good chance it exists as a BarnOwl
+command.
+
+=head3 BUGS
+
+There are horrible quoting issues here. The AUTOLOAD simple joins your
+commands with spaces and passes them unmodified to C<::command>
+
+=cut
 
 # make BarnOwl::<command>("foo") be aliases to BarnOwl::command("<command> foo");
@@ -63 +194 @@
 
 ARGS should be a hashref containing any or all of C<summary>,
-C<usage>, or C<description> keys.
+C<usage>, or C<description> keys:
+
+=over 4
+
+=item summary
+
+A one-line summary of the purpose of the command
+
+=item usage
+
+A one-line usage synopsis, showing available options and syntax
+
+=item description
+
+A longer description of the syntax and semantics of the command,
+explaining usage and options
+
+=back
 
 =cut