#!/usr/bin/env perl
# cyclemoon - Maintains two Moon-related files
# License:  Creative Commons Attribution-NonCommercial-ShareAlike 2.5
# Revision: 070808

#---------------------------------------------------------------------
#                         license information
#---------------------------------------------------------------------

# This section may not be modified except as approved by the author or
# licensor, or to make non-content changes such as adjustments to par-
# agraph formatting or white space.

# This  version of this software is  distributed  under  the following
# license:
#
#       Creative Commons Attribution-NonCommercial-ShareAlike 2.5

# You may use, modify, and redistribute this software without fees  or
# royalties, but only under the terms and conditions set forth  by the
# license.  In particular, copies and derived works cannot be used for
# commercial purposes.  Additionally, the license propagates to copies
# and derived works. Furthermore, you must provide attribution "in the
# manner  specified  by the  author or licensor".  The latter point is
# discussed below.

# The author [and licensor] hereby specifies that  attribution must be
# handled in the following manner:  a. If the software is interactive,
# any  About or Credits dialog boxes, windows, or output text provided
# by the  original version must be preserved and readily accessible to
# the end user at runtime.  b. If the software is non-interactive,  or
# if it does not  provide  About or Credits dialog boxes, windows,  or
# output text,  the  operating system and/or  desktop environment used
# must provide attribution that is  visible and/or  readily accessible
# to the end user at runtime.

# The following techniques  do not meet the  attribution requirements:
# Attribution through text  files, attribution  through  printed docu-
# mentation,  verbal  attribution, or postings on  external  web sites
# [i.e.,  web  sites  that are not an intrinsic local component of the
# operating system or  desktop environment used].  These  examples are
# provided for illustrative purposes only.

# It should be noted that trademarks are an additional issue.  If this
# software  uses any  trademarks,  trademark-related  restrictions may
# apply.

# This is not a  complete explanation of the  terms and conditions in-
# volved.  For more information, see the Creative Commons Attribution-
# NonCommercial-ShareAlike 2.5 license.

#---------------------------------------------------------------------
#                              overview
#---------------------------------------------------------------------

# "cyclemoon" creates and maintains two files:
#
#     a. /var/tmp/moonphase.png  - A picture of  the Moon  with  phase
#        shadow added.  The phase shadow is based on the current  date
#        and time.
#
#     b. /var/tmp/moonphase.txt  - A short text file that provides in-
#        formation related to the image.

# To use "cycletime", proceed as follows:
#
#     a. Arrange for  the  system to run  the program once  at startup
#        time.
#
#     b. Arrange for "cron" to run the program once or twice per hour.

# When  "cyclemoon" is executed,  it checks to see if the output files
# are missing, or if they're more than 12 hours old.  If either condi-
# tion is met [for either output file],  "cyclemoon"  regenerates both
# files.

# "cyclemoon"  requires POV-Ray. If this program is executed on a dis-
# tro that doesn't have POV-Ray, it exits silently. Note: This is  in-
# tentional,  as the local distro has variants that don't include POV-
# Ray.  In most cases, other run-time problems will produce error mes-
# sages.

# Note:  If the "povray" executable isn't located in "/usr/bin",  edit
# "cyclemoon" and  "moonphasepic".  Set $PROG_POVRAY  appropriately in
# both files.

# For more  information,  execute  "moonphasepic"  without any parame-
# ters.

#---------------------------------------------------------------------
#                            module setup
#---------------------------------------------------------------------

require 5.6.1;
use strict;
use Carp;
use warnings;
                                # Trap warnings
$SIG {__WARN__} = sub { die @_; };

#---------------------------------------------------------------------
#                           basic constants
#---------------------------------------------------------------------

use constant ZERO  => 0;        # Zero
use constant ONE   => 1;        # One

use constant FALSE => 0;        # Boolean FALSE
use constant TRUE  => 1;        # Boolean TRUE

my $SECONDS_PER_HOUR = 3600;    # Number of seconds per hour

#---------------------------------------------------------------------
#                         program parameters
#---------------------------------------------------------------------

                                # Absolute pathnames  for  PNG and TXT
                                # output files [respectively]
my $IMGFILE     = '/var/tmp/moonphase.png';
my $TXTFILE     = '/var/tmp/moonphase.txt';

my $IMGWIDTH    = 360;          # Image width [in pixels ]
                                # Maximum age [in seconds]
my $MAXAGE      = 12 * $SECONDS_PER_HOUR;

                                # Absolute pathname for  "povray" pro-
                                # gram
my $PROG_POVRAY = '/usr/bin/povray';

#---------------------------------------------------------------------
#                            main routine
#---------------------------------------------------------------------

sub Main
{
    exit ONE unless -f $PROG_POVRAY;

    my ($xtime1, $xtime2);
    my $time = time;

    $xtime1 = (stat $IMGFILE) [9];
    $xtime1 = $MAXAGE+ONE unless defined $xtime1;
    $xtime1 = $time - $xtime1;

    $xtime2 = (stat $TXTFILE) [9];
    $xtime2 = $MAXAGE+ONE unless defined $xtime2;
    $xtime2 = $time - $xtime2;

    exit ZERO if ($xtime1 <= $MAXAGE) && ($xtime2 <= $MAXAGE);

    my $cmd = << "END";
__META_PREFIX__/bin/moonphasepic
    now --info=$TXTFILE --output=$IMGFILE --width=$IMGWIDTH
END
    $cmd =~ s@\s+@ @gs;
    $cmd =~ s@\s+\z@@s;

    system $cmd;
    undef;
}

#---------------------------------------------------------------------
#                            main program
#---------------------------------------------------------------------

&Main();                        # Call the main routine
exit ZERO;                      # Normal exit