Perlwrap
From BarnOwl
This document is autogenerated from perlwrap.pm's perldocs using pod2wiki. Please do not edit this page!
NAME
BarnOwl
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.
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.
getcurmsg
Returns the current message as a BarnOwl::Message subclass, or undef if there is no message selected
getnumcols
Returns the width of the display window BarnOwl is currently using
getidletime
Returns the length of time since the user has pressed a key, in seconds.
zephyr_getrealm
Returns the zephyr realm barnowl is running in
zephyr_getsender
Returns the fully-qualified name of the zephyr sender barnowl is running as, e.g. nelhage@ATHENA.MIT.EDU
zephyr_zwrite COMMAND MESSAGE
Sends a zephyr programmatically. COMMAND should be a zwrite command line, and MESSAGE is the zephyr body to send.
ztext_stylestrip STRING
Strips zephyr formatting from a string and returns the result
queue_message MESSAGE
Enqueue a message in the BarnOwl message list, logging it and processing it appropriately. MESSAGE should be an instance of BarnOwl::Message or a subclass.
admin_message HEADER BODY
Display a BarnOwl Admin message, with the given header and body.
start_question PROMPT CALLBACK
Displays PROMPT on the screen and lets the user enter a line of text, and calls CALLBACK, which must be a perl subroutine reference, with the text the user entered
start_password PROMPT CALLBACK
Like start_question, but echoes the user's input as *s when they input.
start_editwin PROMPT CALLBACK
Like start_question, but displays PROMPT on a line of its own and opens the editwin. If the user cancels the edit win, CALLBACK is not invoked.
get_data_dir
Returns the BarnOwl system data directory, where system libraries and modules are stored
get_config_dir
Returns the BarnOwl user configuration directory, where user modules and configuration are stored (by default, $HOME/.owl)
popless_text TEXT
Show a popup window containing the given TEXT
popless_ztext TEXT
Show a popup window containing the provided zephyr-formatted TEXT
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 die will be caught and passed to error.
getnumcolors
Returns the number of colors this BarnOwl is capable of displaying
add_dispatch FD CALLBACK
Adds a file descriptor to BarnOwl's internal select() loop. CALLBACK will be invoked whenever data is available to be read from FD.
remove_dispatch FD
Remove a file descriptor previously registered via add_dispatch
AUTOLOAD
BarnOwl.pm has a AUTOLOAD method that translates unused names in the BarnOwl:: namespace to a call to BarnOwl::command() with that command. Underscores are also translated to -s, so you can do e.g. BarnOwl::start_command() and it will be translated into start-command.
So, if you're looking for functionality that you can't find in the perl interface, check :show commands or commands.c in the BarnOwl source tree -- there's a good chance it exists as a BarnOwl command.
BUGS
There are horrible quoting issues here. The AUTOLOAD simple joins your commands with spaces and passes them unmodified to ::command
new_command NAME FUNC [{ARGS}]
Add a new owl command. When owl executes the command NAME, FUNC will be called with the arguments passed to the command, with NAME as the first argument.
ARGS should be a hashref containing any or all of summary, usage, or description keys:
- summary
- A one-line summary of the purpose of the command
- usage
- A one-line usage synopsis, showing available options and syntax
- description
- A longer description of the syntax and semantics of the command, explaining usage and options
new_variable_int NAME [{ARGS}]
new_variable_bool NAME [{ARGS}]
new_variable_string NAME [{ARGS}]
Add a new owl variable, either an int, a bool, or a string, with the specified name.
ARGS can optionally contain the following keys:
- default
- The default and initial value for the variable
- summary
- A one-line summary of the variable's purpose
- description
- A longer description of the function of the variable
BarnOwl::Hook
DESCRIPTION
A BarnOwl::Hook represents a list of functions to be triggered on some event. BarnOwl exports a default set of these (see BarnOwl::Hooks), but can also be created and used by module code.
new
Creates a new Hook object
run [ARGS]
Calls each of the functions registered with this hook with the given arguments.
add SUBREF
Registers a given subroutine with this hook
clear
Remove all functions registered with this hook.
BarnOwl::Hooks
DESCRIPTION
BarnOwl::Hooks exports a set of BarnOwl::Hook objects made available by BarnOwl internally.
USAGE
Modules wishing to respond to events in BarnOwl should register functions with these hooks.
EXPORTS
None by default. Either import the hooks you need explicitly, or refer to them with fully-qualified names. Available hooks are:
- $startup
- Called on BarnOwl startup, and whenever modules are reloaded. Functions registered with the $startup hook get a true argument if this is a reload, and false if this is a true startup
- $shutdown
- Called before BarnOwl shutdown
- $receiveMessage
- Called with a BarnOwl::Message object every time BarnOwl appends a new message to its message list
- $mainLoop
- Called on every pass through the BarnOwl main loop. This is guaranteed to be called at least once/sec and may be called more frequently.
- $getBuddyList
- Called to display buddy lists for all protocol handlers. The result from every function registered with this hook will be appended and displayed in a popup window, with zephyr formatting parsed.
