Mac::Apps::Seasonality::CommandLineUtilities - Utility routines for command-line tools related to Seasonality.

This document describes Mac::Apps::Seasonality::CommandLineUtilities version 0.0.6.

    use Mac::Growl qw{ RegisterNotifications PostNotification };

    use Mac::Apps::Seasonality::Constants qw{ :application };
    use Mac::Apps::Seasonality::CommandLineUtilities qw{ :growl };

    RegisterNotifications(
        'Command-line Tool Name',
        $GROWL_NOTIFICATIONS_REF,
        $GROWL_NOTIFICATIONS_REF,
        $GROWL_APPLICATION_ICON
    );

    PostNotification(
        'Command-line Tool Name',
        $GROWL_NOTIFICATION_PROGRESS,
        'Notification Title',
        'Notification Text',
    );
    PostNotification(
        'Command-line Tool Name',
        $GROWL_NOTIFICATION_SEASONALITY_APPLICATION_STATUS
        'Notification Title',
        "$SEASONALITY_NAME is currently causing a rainstorm in Death Valley",
    );
    PostNotification(
        'Command-line Tool Name',
        $GROWL_NOTIFICATION_ERROR
        'Notification Title',
        q{Could not go to the gym today. It's too hot outside.},
        'sticky'
    );







    use DBI;
    use Mac::Apps::Seasonality::CommandLineUtilities    qw{ :all };

    initialize_program_utilities(
        'Command-line Tool Name',
        quiet => 0,
        use_growl => 1,
    );

    state_progress($GROWL_NOTIFICATION_PROGRESS, q{Hey! I'm doing something!};

    shutdown_seasonality_if_necessary(
        no_shutdown   => 0,
        no_restart    => 0,
        force_start   => 0,
        shutdown_wait => 5,
    );

    my $database_connection = create_database_connection('weather.db', backup => 1);

    # do something with the database.

    close_database_connection();

    restart_seasonality_if_necessary();

This is a set of utilities for building applications which deal with Seasonality. All functions expect that initialize_program_utilities() has been called first. Most functions will emit messages about what they're doing via state_progress(). This behavior can be disabled by passing a true value for the second parameter to initialize_program_utilities(). The state_progress() function emits messages to STDOUT and via Growl notifications if Mac::Growl is installed and the third parameter to initialize_program_utilities() is a true value.

$GROWL_NOTIFICATION_PROGRESS

The progress notification for Growl, to be used as the second parameter to "PostNotification" in Mac::Growl in order to announce actions being taken by the program.

$GROWL_NOTIFICATION_SEASONALITY_APPLICATION_STATUS

The state of Seasonality notification for Growl, to be used as the second parameter to "PostNotification" in Mac::Growl in order to announce whether the program thinks Seasonality is running or not.

$GROWL_NOTIFICATION_ERROR

The error notification for Growl, to be used as the second parameter to "PostNotification" in Mac::Growl in order to announce problems found by the program.

$GROWL_NOTIFICATIONS_REF

A reference to an array containing $GROWL_NOTIFICATION_PROGRESS, $GROWL_NOTIFICATION_SEASONALITY_APPLICATION_STATUS, and $GROWL_NOTIFICATION_ERROR. This is useful for the second and third parameters to "RegisterNotifications" in Mac::Growl.

$GROWL_APPLICATION_ICON

The name of the icon to use for notifications.

initialize_program_utilities( $application_name, [ quiet => $boolean, ] [ use_growl => $boolean, ] )

Saves the name of the application, tells state_progress() whether to actually emit anything and whether it should use Growl if it is available. Also it initializes Growl if it is to be used.

No useful value is returned.

state_progress( $notification, $message )

Emits messages to STDOUT and to Growl, if it is enabled.

The $notification parameter should be one of $GROWL_NOTIFICATION_PROGRESS, $GROWL_NOTIFICATION_SEASONALITY_APPLICATION_STATUS, or $GROWL_NOTIFICATION_ERROR if Growl is being used. In particular, if this parameter is $GROWL_NOTIFICATION_ERROR, the message will be emitted even if the call to initialize_program_utilities() stated that the application should be quiet; also, if Growl is enabled, the notification will be sticky.

No useful value is returned.

shutdown_seasonality_if_necessary( [ no_shutdown => $boolean, ] [ no_restart => $boolean, ] [ force_start => $boolean, ] [ shutdown_wait => $seconds, ] )

Shuts down Seasonality, if it is running, and gathers the information that restart_seasonality_if_necessary() needs.

If no_shutdown is true, Seasonality will not be shut down, even if is running.

If no_restart is true, Seasonality will not be restarted by restart_seasonality_if_necessary(), even if it was running when this function was called.

If force_start is true, Seasonality will be started by restart_seasonality_if_necessary(), even if it wasn't running when this function was called. A true value for this parameter overrides the value of no_restart.

The value of shutdown_wait is the number of seconds to wait for Seasonality to stop, if it is going to be brought down.

No useful value is returned.

create_database_connection( $database_file_name, [ backup => $boolean, ] )

TODO

close_database_connection()

TODO

restart_seasonality_if_necessary()

TODO

None of the above constants or functions are exported by default. They have to be individually imported, or you can use the following tags.

:all

Import everything.

:growl

Import the $GROWL_* constants.

:functions

Import the functions.

No application name was given to initialize_program_utilities().

No arguments were given to initialize_program_utilities() or the application name was empty.

Mac::Apps::Seasonality::CommandLineUtilities has not been initialized. Call initialize_program_utilities() first.

A function in this package was invoked before initialize_program_utilities() was called.

Could not shut down Seasonality: $EXTENDED_OS_ERROR

An attempt to stop a current Seasonality process failed for the specified reason.

"%s" does not exist as a writable file. Will not create it.

A call was made to create_database_connection() with the path to the database not existing or not being writable. All database files should be created by Seasonality in order to ensure that it doesn't run into any problems with them.

Could not copy "%s" to "%s": $OS_ERROR

An attempt to back up the database failed.

Could not open %s: $DBI::errstr

An attempt to open the database failed due to a problem discovered by the database driver.

Mac::Apps::Seasonality::CommandLineUtilities requires no configuration files or environment variables.

DBD::SQLite2 Mac::Apps::Launch Mac::Apps::Seasonality::Constants Mac::Processes Readonly

None reported.

No bugs have been reported.

Please report any bugs or feature requests to bug-mac-apps-seasonality-loadicaohistory@rt.cpan.org, or through the web interface at http://rt.cpan.org.

Elliot Shank perl@galumph.com

Copyright ©2006-2007, Elliot Shank <perl@galumph.com>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.