From 1894fc5ed2ed791594afd0e0a1f8d10ecdb6647b Mon Sep 17 00:00:00 2001 From: Dave Morriss Date: Thu, 18 Dec 2025 14:23:08 +0000 Subject: [PATCH] Updates to 'reserve_cnews' Community_News/reserve_cnews: brought this script out of the archive where it had been placed in the expectation that Community News slots would be reserved algorithmically on the hub. This script uses the older strategy of placing dummy shows in the slots for the first Monday of each month. The script has been updated and its internal documentation improved. This version can find the next free Community News slot and then create the requested number of reservations thereafter. --- Community_News/reserve_cnews | 153 +++++++++++++++++++++++++---------- 1 file changed, 110 insertions(+), 43 deletions(-) diff --git a/Community_News/reserve_cnews b/Community_News/reserve_cnews index 5a38865..c0158bd 100755 --- a/Community_News/reserve_cnews +++ b/Community_News/reserve_cnews @@ -4,7 +4,8 @@ # FILE: reserve_cnews # # USAGE: ./reserve_cnews [-from[=DATE]] [-count=COUNT] [-[no]dry-run] -# [-[no]silent] [-config=FILE] [-help] [-debug=N] +# [-[no]silent] [-config=FILE] [-help] +# [-documentation|man] [-debug=N] # # DESCRIPTION: Reserve a series of slots from a given date for the Community # News shows by computing the dates for the reservations and @@ -13,11 +14,20 @@ # OPTIONS: --- # REQUIREMENTS: --- # BUGS: --- -# NOTES: --- +# NOTES: To view the entire documentation use: +# +# ./reserve_cnews -documentation +# +# To create a PDF version of the documentation: +# +# pod2pdf reserve_cnews --out=reserve_cnews.pdf +# +# Where pod2pdf comes from App::pod2pdf +# # AUTHOR: Dave Morriss (djm), Dave.Morriss@gmail.com -# VERSION: 0.0.14 +# VERSION: 0.0.15 # CREATED: 2014-04-29 22:16:00 -# REVISION: 2023-04-10 16:05:36 +# REVISION: 2025-12-18 14:06:54 # #=============================================================================== @@ -26,6 +36,8 @@ use strict; use warnings; use utf8; +use Cwd qw( abs_path ); # Detecting where the script lives + use Getopt::Long; use Pod::Usage; @@ -41,7 +53,7 @@ use Data::Dumper; # # Version number (manually incremented) # -our $VERSION = '0.0.14'; +our $VERSION = '0.0.15'; # # Script name @@ -56,7 +68,12 @@ $DIR = '.' unless $DIR; # # Constants and other declarations # -my $basedir = "$ENV{HOME}/HPR/Community_News"; +# +# We make variable to hold the working directory where the script is located +# +( my $basedir = abs_path($0) ) =~ s|/?[^/]*$||mx; + +#my $basedir = "$ENV{HOME}/HPR/Community_News"; my $configfile = "$basedir/.hpr_db.cfg"; my $hostname = 'HPR Volunteers'; @@ -93,9 +110,19 @@ Options( \%options ); # # Default help # -pod2usage( -msg => "$PROG version $VERSION\n", -exitval => 1 ) +pod2usage( -msg => "$PROG version $VERSION\n", -verbose => 0, -exitval => 1 ) if ( $options{'help'} ); +# +# Full documentation if requested with -doc +# +pod2usage( + -msg => "$PROG version $VERSION\n", + -verbose => 2, + -exitval => 1, + -noperldoc => 0, +) if ( $options{'documentation'} ); + # # Collect options # @@ -104,8 +131,8 @@ my $cfgfile = ( defined( $options{config} ) ? $options{config} : $configfile ); my $dry_run = ( defined( $options{'dry-run'} ) ? $options{'dry-run'} : 0 ); my $silent = ( defined( $options{silent} ) ? $options{silent} : 0 ); -my $count = ( defined( $options{count} ) ? $options{count} : $DEF_COUNT ); -my $from = $options{from}; +my $count = ( defined( $options{count} ) ? $options{count} : $DEF_COUNT ); +my $from = $options{from}; _debug( $DEBUG >= 1, 'Host name: ' . $hostname ); _debug( $DEBUG >= 1, 'Series name: ' . $seriesname ); @@ -142,9 +169,6 @@ $dbh->{mysql_enable_utf8} = 1; # Find the latest show for reference purposes #------------------------------------------------------------------------------- $sth1 = $dbh->prepare( -# q{SELECT id, date FROM eps -# WHERE DATEDIFF(date,CURDATE()) <= 0 AND DATEDIFF(date,CURDATE()) >= -2 -# ORDER BY date DESC LIMIT 1} q{SELECT id, date FROM eps WHERE DATEDIFF(date,CURDATE()) BETWEEN -2 AND 0 ORDER BY date DESC LIMIT 1} @@ -197,7 +221,8 @@ _debug( $DEBUG >= 2, 'Host id: ' . $hostid ); _debug( $DEBUG >= 2, 'Series id: ' . $series ); #------------------------------------------------------------------------------- -# The start date comes from the -from=DATE option, the database or is defaulted +# The start date comes from the -from=DATE option, the database or is +# defaulted. It will always be the first day of the appropriate month. #------------------------------------------------------------------------------- # # Use the date provided or the default @@ -211,7 +236,7 @@ if ( ! defined( $from ) ) { } elsif ( $from =~ /^$/ ) { _debug($DEBUG >= 3, "From date: Database"); - @startdate = get_next_date( $dbh, $series ); + @startdate = ( ( get_next_free_date( $dbh, $series ) )[ 0 .. 1 ], 1 ); } else { # @@ -241,13 +266,11 @@ print "Reference show: hpr$ref_show on ", ISO8601_Date(@ref_date), "\n\n" # $sth1 = $dbh->prepare(q{SELECT id FROM eps where id = ?}); $sth2 = $dbh->prepare(q{SELECT id, date FROM eps where title = ?}); -$sth3 = $dbh->prepare( - q{ +$sth3 = $dbh->prepare( q{ INSERT INTO eps (id,date,hostid,title,summary,series,tags, duration,notes,downloads) VALUES(?,?,?,?,?,?,?,0,'',0) -} -); +}); # # Compute a series of dates from the start date @@ -287,6 +310,10 @@ for my $i ( 1 .. $count ) { "Skipping; an episode already exists with title '%s' (hpr%s, %s)\n", $title, $h2->{id}, $h2->{date}; } + + # + # Add a month to the running date + # @cdate = Add_Delta_YM( @cdate, 0, 1 ); next; } @@ -302,7 +329,7 @@ for my $i ( 1 .. $count ) { # # Find a free slot # - print "Slot $show for '$title' is allocated. " unless ($silent); + print "Slot $show for '$title' is already allocated. " unless ($silent); until ( $rv == 0 && ( Day_of_Week(@rdate) < 6 ) ) { $show++ if ( Day_of_Week(@rdate) < 6 ); @rdate = Add_Delta_Days( @rdate, 1 ); @@ -399,7 +426,7 @@ sub convert_date { # unless ($force) { unless ( Delta_Days( @today[ 0, 1 ], 1, @startdate ) ge 0 ) { - warn "Invalid date $textdate (in the past)\n"; + warn "convert_date: Invalid date $textdate (in the past)\n"; die "Use -force to create a back-dated calendar\n"; } } @@ -409,13 +436,13 @@ sub convert_date { } #=== FUNCTION ================================================================ -# NAME: get_next_date -# PURPOSE: Find the next unused date from the database +# NAME: get_next_free_date +# PURPOSE: Find the next unused Community News release date from the +# database # PARAMETERS: $dbh Database handle # $series The id of the Community News series (from # a previous query) -# RETURNS: The start of the month of the next free date in Date::Calc -# format +# RETURNS: The next free Community News date in Date::Calc format # DESCRIPTION: Finds the latest reservation in the database. Uses the date # associated with this reservation, converts to Date::Calc # format, adds a month to it and ensures it's the first Monday @@ -425,7 +452,7 @@ sub convert_date { # COMMENTS: TODO: do we need the show number of the latest reservation? # SEE ALSO: N/A #=============================================================================== -sub get_next_date { +sub get_next_free_date { my ( $dbh, $series ) = @_; my ( $sth, $h ); @@ -469,17 +496,16 @@ sub get_next_date { # NAME: make_date # PURPOSE: Make the event date for recurrence # PARAMETERS: $refdate -# An arrayref to the reference date array (usually -# today's date) +# An arrayref to the reference date array # $dow Day of week for the event date (1-7, 1=Monday) # $n The nth day of the week in the given month required # for the event date ($dow=1, $n=1 means first Monday) # $offset Number of days to offset the computed date -# RETURNS: The resulting date as a list for Date::Calc -# DESCRIPTION: We want to compute a simple date with an offset, such as -# "the Saturday before the first Monday of the month". We do -# this by computing a pre-offset date (first Monday of month) -# then apply the offset (Saturday before). +# RETURNS: The resulting date as a list in Date::Calc format +# DESCRIPTION: We want to compute a simple date, optionally with an offset, +# such as "the Saturday before the first Monday of the month". +# We do this by computing a pre-offset date (first Monday of +# month) then apply the offset (Saturday before). # THROWS: No exceptions # COMMENTS: TODO Needs more testing to be considered truly universal # SEE ALSO: @@ -627,8 +653,8 @@ sub Options { my ($optref) = @_; my @options = ( - "help", "debug=i", "config=s", "from:s", - "count=i", "dry-run!", "silent!", + "help", "documentation|man", "debug=i", "config=s", + "from:s", "count=i", "dry-run!", "silent!", ); if ( !GetOptions( $optref, @options ) ) { @@ -651,16 +677,17 @@ reserve_cnews - reserve Community News shows in the HPR database =head1 VERSION -This documentation refers to B version 0.0.14 +This documentation refers to B version 0.0.15 =head1 USAGE - ./reserve_cnews [-help] [-from[=DATE]] [-count=COUNT] + ./reserve_cnews [-help] [-documentation|man] [-from[=DATE]] [-count=COUNT] [-[no]dry-run] [-[no]silent] [-config=FILE] [-debug=N] Examples: ./reserve_cnews -help + ./reserve_cnews -documentation ./reserve_cnews ./reserve_cnews -from=1-June-2014 -dry-run ./reserve_cnews -from=15-Aug-2015 -count=6 @@ -675,7 +702,11 @@ This documentation refers to B version 0.0.14 =item B<-help> -Prints a brief help message describing the usage of the program, and then exits. +Prints a help message describing the usage of the program, and then exits. + +=item B<-documentation> or B<-man> + +Prints the entire embedded documentation for the program, then exits. =item B<-from=DATE> or B<-from> @@ -762,14 +793,15 @@ The show title chosen for each reservation is displayed as well as the summary. =head1 DESCRIPTION Hacker Public Radio produces a Community News show every month. The show is -recorded on the Saturday before the first Monday of the month, and should be +usually recorded on the Friday before the first Monday of the month, and should be released as soon as possible afterwards. This program reserves future slots in the database for upcoming shows. It computes the date of the first Monday of all of the months in the requested -sequence then determines which show number matches that date. It writes rows -into the I table containing the episode number, the host -identifier ('HPR Admins') and the reason for the reservation. +sequence then determines which show number matches that date. It writes +sufficient details into the I (episodes) table containing the episode number, the host +identifier ('HPR Volunteers'), the series ('HPR Community News') and the title +and summary relevant to the date of the show. It is possible that an HPR host has already requested the slot that this program determines it should reserve. When this happens the program increments @@ -780,6 +812,40 @@ It is also possible that a reservation has previously been made in the I table. When this case occurs the program ignores this particular reservation. +The script uses a starting date for the process of finding show slots in the +database. It operates in three modes when setting this date: + +=over 4 + +=item 1 + +The B<-from> option is omitted. + +The starting date used is the first day of the current month. + +=item 2 + +The B<-from> option is used but without a B part. + +The script searches the database for the latest reservation in the 'HPR +Community News' series. It adds a month to this date and returns the start of +the resulting month, and computes the show number for this slot. This will be +the first reservation that will be made. + +In this mode the script creates new reservations, though it also looks for any +existing reservations in the database and will skip them if found. + +=item 3 + +The full B<-from=DATE> option is given. + +The date given is used to compute the start of the month, and the script then +proceeds to check each ensuing month to add reservations. It will skip any +reservations it finds with the possible result that it will do nothing because +the requested number of reservations have already been made. + +=back + =head1 DIAGNOSTICS =over 8 @@ -829,10 +895,11 @@ B<.hpr_db.cfg> and should contain the following data: =head1 DEPENDENCIES Config::General + Cwd + DBI Data::Dumper Date::Calc Date::Parse - DBI Getopt::Long Pod::Usage @@ -848,7 +915,7 @@ Dave Morriss (Dave.Morriss@gmail.com) =head1 LICENCE AND COPYRIGHT -Copyright (c) 2014 - 2023 Dave Morriss (Dave.Morriss@gmail.com). All +Copyright (c) 2014 - 2025 Dave Morriss (Dave.Morriss@gmail.com). All rights reserved. This module is free software; you can redistribute it and/or