NAME

AmphetaDesk::Utilities - A potpourri of minor utilities for AmphetaDesk

SYNOPSIS

    # generic stuff.
    $modified = encode_to_dec($data); # encodes to decimal equivalents.
    $modified = strip_newlines_and_tabs($data); # what do you think?
    $modified = add_link_targets($data, $target); # add <a target="">'s.
    $modified = remove_utf_bom($data); # stops older expats from crashing.

    # logging routines.
    set_logfile($filepath);
    note("this is a note to our log");
    note("this is a note to our log and OS GUI", 1);
    note("this is a note to our log, our OS GUI, and the browser", 1, 1);
    error("this is a note everywhere, that then dies");

    # webpage communication
    set_response("add a message to the web page note buffer");
    my @responses = get_response; # gets/deletes all messages in buffer.

DESCRIPTION

This package contains all the minor utilities needed through out AmphetaDesk, like logging, newline and tab removal, decimal encoding, HTML removal, and so on. It's really a dumping ground of routines that didn't fit anywhere else.

METHODS

add_link_targets($data, $target): This routine will scour through the passed $data, looking for HTML links and then adding targets to them, to focus the link into a new (or existing) window. The target name to add is defined by $target. AmphetaDesk calls this routine automatically for every item in the user's subscribed feeds. It returns the modified $data.

encode_to_dec($data): This routine encodes non-alphanumerics to decimal equivalents (like %20). It returns the modified, encoded data. Requires URI::Escape (we used to homebrew this, but felt more comfortable blaming another module instead of our own code).

get_response and set_response($msg): get_response returns an array of the current batch of responses, created by the set_response routine. Responses are like log file lines, but are used only for displaying diagnostic messages in the browser window (either in normal template pages, or in a javascript popup window). get_response will remove the saved response(s) once retrieved. One possible way of handling responses is with my $response = join("<br>", get_response()).

note and error: You may use note to write a note to the GUI window, AmphetaDesk.log, or the web page (see get_reponse) - it'll always return with a 1. What happens to the GUI window is controlled by one of the various OS libraries, located under AmphetaDesk::OS. If you use error, we note and then die. Example usage demonstrating the possible output locations:; The log is only printed to if set_logfile has been configured.

remove_utf8_bom: This routine works around a fatal segfault on versions of AmphetaDesk that have been compiled with an old version of expat (before 1.95.2). See, we need expat 1.95.2 or higher to parse UTF8-BOM files, but we can't rely on that existing for old versions of AmphetaDesk or for Linux versions that don't have an updated expat RPM/install. In this case, the safest is to check for the existence of the byte order mark (0xEF 0xBB 0xBF)... if we see it, we remove it and then return the data back to our caller.

set_logfile($logfile): This routine closes any open LOG filehandles (implicitly) and opens a new one which appends to the passed $logfile. All note and error routines will use this LOG filehandle when logging, and STDERR will be redirected there. If the current $logfile exists, it will be deleted after 250k so we don't go squirrels with evil. This routine returns 1 if the log was opened successfully, and dies if it wasn't.

strip_newlines_and_tabs($data): This routine removes newlines and tabs from the passed data. It can dip into arrays, single level hashes, and normal variables. It replaces all newlines and tabs with a single space character, and then returns the data.

AUTHOR

Morbus Iff, <morbus@disobey.com>

COPYRIGHT AND LICENSE