[830] in BarnOwl Developers
[D-O-H] r824 - trunk/owl
daemon@ATHENA.MIT.EDU (nelhage@MIT.EDU)
Thu Oct 29 18:10:10 2009
Resent-From: nelhage@mit.edu
Resent-To: barnowl-dev-mtg@charon.mit.edu
To: dirty-owl-hackers@mit.edu
From: nelhage@MIT.EDU
Reply-to: dirty-owl-hackers@MIT.EDU
Date: Thu, 10 Jan 2008 15:48:00 -0500 (EST)
Author: nelhage
Date: 2008-01-10 15:48:00 -0500 (Thu, 10 Jan 2008)
New Revision: 824
Modified:
trunk/owl/perlglue.xs
trunk/owl/perlwrap.pm
Log:
Document (nearly) every public function in the BarnOwl:: namespace
Modified: trunk/owl/perlglue.xs
===================================================================
--- trunk/owl/perlglue.xs 2008-01-10 20:47:00 UTC (rev 823)
+++ trunk/owl/perlglue.xs 2008-01-10 20:48:00 UTC (rev 824)
@@ -12,8 +12,25 @@
#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 *
command(cmd)
char *cmd
Modified: trunk/owl/perlwrap.pm
===================================================================
--- trunk/owl/perlwrap.pm 2008-01-10 20:47:00 UTC (rev 823)
+++ trunk/owl/perlwrap.pm 2008-01-10 20:48:00 UTC (rev 824)
@@ -14,6 +14,117 @@
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 {
# bootstrap in C bindings and glue
*owl:: = \*BarnOwl::;
@@ -46,6 +157,26 @@
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");
sub AUTOLOAD {
our $AUTOLOAD;
@@ -62,8 +193,25 @@
first argument.
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
sub new_command {
