Config-Crontab
view release on metacpan or search on metacpan
if( $owner ) {
unless( defined( getpwnam($owner) ) ) {
$self->error("Unknown user: $owner");
if( $self->strict ) {
croak $self->error;
}
return;
}
if( $owner =~ $self->owner_re ) {
$self->error("Illegal username: $owner");
if( $self->strict ) {
croak $self->error;
}
return;
}
}
$self->{_owner} = $owner;
}
return ( defined $self->{_owner} ? $self->{_owner} : '' );
}
sub owner_re {
my $self = shift;
if( @_ ) {
my $re = shift;
$self->{_owner_re} = qr($re);
}
return ( defined $self->{_owner_re} ? $self->{_owner_re} : qr() );
}
############################################################
############################################################
=head1 NAME
Config::Crontab - Read/Write Vixie compatible crontab(5) files
=head1 SYNOPSIS
use Config::Crontab;
####################################
## making a new crontab from scratch
####################################
my $ct = new Config::Crontab;
## make a new Block object
my $block = new Config::Crontab::Block( -data => <<_BLOCK_ );
## mail something to joe at 5 after midnight on Fridays
MAILTO=joe
5 0 * * Fri /bin/someprogram 2>&1
_BLOCK_
## add this block to the crontab object
$ct->last($block);
## make another block using Block methods
$block = new Config::Crontab::Block;
$block->last( new Config::Crontab::Comment( -data => '## do backups' ) );
$block->last( new Config::Crontab::Env( -name => 'MAILTO', -value => 'bob' ) );
$block->last( new Config::Crontab::Event( -minute => 40,
-hour => 3,
-command => '/sbin/backup --partition=all' ) );
## add this block to crontab file
$ct->last($block);
## write out crontab file
$ct->write;
###############################
## changing an existing crontab
###############################
my $ct = new Config::Crontab; $ct->read;
## comment out the command that runs our backup
$_->active(0) for $ct->select(-command_re => '/sbin/backup');
## save our crontab again
$ct->write;
###############################
## read joe's crontab (must have root permissions)
###############################
## same as "crontab -u joe -l"
my $ct = new Config::Crontab( -owner => 'joe' );
$ct->read;
=head1 DESCRIPTION
B<Config::Crontab> provides an object-oriented interface to
Vixie-style crontab(5) files for Perl.
A B<Config::Crontab> object allows you to manipulate an ordered set
of B<Event>, B<Env>, or B<Comment> objects (also included with this
package). Descriptions of these packages may be found below.
In short, B<Config::Crontab> reads and writes crontab(5) files (and
does a little pretty-printing too) using objects. The general idea is
that you create a B<Config::Crontab> object and associate it with a
file (if unassociated, it will work over a pipe to C<crontab -l>). From
there, you can add lines to your crontab object, change existing line
attributes, and write everything back to file.
=over 4
=item
NOTE: B<Config::Crontab> does I<not> (currently) do validity checks
on your data (i.e., dates out of range, etc.). However, if the call
to B<crontab> fails when you invoke B<write>, B<write> will return
I<undef> and set B<error> with the error message returned from the
B<crontab> command. Future development may tend toward more validity
checks.
=back
Now, to successfully navigate the module's ins and outs, we'll need a
little terminology lesson.
=head2 Terminology
B<Config::Crontab> (hereafter simply B<Crontab>) sees a C<crontab>
file in terms of I<blocks>. A block is simply an ordered set of one
or more lines. Blocks are separated by two or more newlines. For
example, here is a crontab file with two blocks:
## a comment
30 4 * * * /bin/some_command
## another comment
ENV=some_value
50 9 * * 1-5 /bin/reminder --meeting=friday
The first block contains two B<Config::Crontab::*> objects: a
B<Comment> object and an B<Event> object. The second block contains
Only B<Block> objects can be added to B<Crontab> objects (see
L</CAVEATS>). B<Block> objects may be added via the B<last> method
(and several other methods, including B<first>, B<up>, B<down>,
B<before>, and B<after>).
=item *
B<Block> objects can be populated in a variety of ways, including the
B<-data> attribute (a string which may--and frequently does--span
multiple lines via a 'here' document), the B<-lines> attribute (which
takes a list reference), and the B<last> method. In addition to the
B<last> method, B<Block> objects use the same methods for adding and
moving objects that the B<Crontab> object does: B<first>, B<last>,
B<up>, B<down>, B<before>, and B<after>.
=back
After the B<Module Utility> section, the remainder of this document
is a reference manual and describes the methods available (and how to
use them) in each of the 5 classes: B<Config::Crontab>,
B<Config::Crontab::Block>, B<Config::Crontab::Event>,
B<Config::Crontab::Env>, and B<Config::Crontab::Comment>. The reader
is also encouraged to look at the example CGI script in the F<eg>
directory and the (somewhat contrived) examples in the F<t> (testing)
directory with this distribution.
=head2 Module Utility
B<Config::Crontab> is a useful module by virtue of the "one-liner"
test. A useful module must do useful work (editing crontabs is useful
work) economically (i.e., useful work must be able to be done on a
single command-line that doesn't wrap more than twice and can be
understood by an adept Perl programmer).
Graham Barr's B<Net::POP3> module (actually, most of Graham's work
falls in this category) is a good example of a useful module.
So, with no more ado, here are some useful one-liners with
B<Config::Crontab>:
=over 4
=item *
uncomment all crontab events whose command contains the string 'fetchmail'
perl -MConfig::Crontab -e '$c=new Config::Crontab; $c->read; \
$_->active(1) for $c->select(-command_re => "fetchmail"); $c->write'
=item *
remove the first crontab block that has '/bin/unwanted' as a command
perl -MConfig::Crontab -e '$c=new Config::Crontab; $c->read; \
$c->remove($c->block($c->select(-command_re => "/bin/unwanted"))); \
$c->write'
=item *
reschedule the backups to run just Monday thru Friday:
perl -MConfig::Crontab -e '$c=new Config::Crontab; $c->read; \
$_->dow("1-5") for $c->select(-command_re => "/sbin/backup"); $c->write'
=item *
reschedule the backups to run weekends too:
perl -MConfig::Crontab -e '$c=new Config::Crontab; $c->read; \
$_->dow("*") for $c->select(-command_re => "/sbin/backup"); $c->write'
=item *
change all 'MAILTO' environment settings in this crontab to 'joe@schmoe.org':
perl -MConfig::Crontab -e '$c=new Config::Crontab; $c->read; \
$_->value(q!joe@schmoe.org!) for $c->select(-name => "MAILTO"); $c->write'
=item *
strip all comments from a crontab:
perl -MConfig::Crontab -e '$c=new Config::Crontab; $c->read; \
$c->remove($c->select(-type => "comment")); $c->write'
=item *
disable an entire block of commands (the block that has the word
'Friday' in it):
perl -MConfig::Crontab -e '$c=new Config::Crontab; $c->read; \
$c->block($c->select(-data_re => "Friday"))->active(0); $c->write'
=item *
copy one user's crontab to another user:
perl -MConfig::Crontab -e '$c = new Config::Crontab(-owner => "joe"); \
$c->read; $c->owner("mike"); $c->write'
=back
=head1 PACKAGE Config::Crontab
This section describes B<Config::Crontab> objects (hereafter simply
B<Crontab> objects). A B<Crontab> object is an abstracted way of
dealing with an entire B<crontab(5)> file. The B<Crontab> class has
methods to allow you to select, add, or remove B<Block> objects as
well as read and parse crontab files and write crontab files.
=head2 init([%args])
This method is called implicitly when you instantiate an object via
B<new>. B<init> takes the same arguments as B<new> and B<read>. If
the B<-file> argument is specified (and is non-false), B<init> will
invoke B<read> automatically with the B<-file> value. Use B<init> to
re-initialize an object.
Example:
## auto-parses foo.txt in implicit call to init
$ct = new Config::Crontab( -file => 'foo.txt' );
## re-initialize the object with default values and a new file
$ct->init( -file => 'bar.txt' );
=head2 strict([boolean])
B<strict> enforces the following constraints:
Or another way:
$c = new Config::Crontab;
$c->owner('joe');
$c->read; ## reading joe's crontab
You can use this to copy a crontab from one user to another:
$c->owner('joe');
$c->read;
$c->owner('bob');
$c->write;
=head2 owner_re([regex])
B<Config::Crontab> is strict in what it will allow for a username,
since this information internally is passed to a shell. If the
username specified is not a user on the system, B<Config::Crontab>
will set B<error> with "Illegal username" and return I<undef>; if
B<strict> mode is enabled, B<Config::Crontab> will croak with the same
error.
Further, once the username is determined valid, the username is then
checked against a regular expression to thwart null string attacks and
other maliciousness. The default regular expression used to check for
a safe username is:
/[^a-zA-Z0-9\._-]/
If the pattern matches (i.e., if any characters other than the ones
above are found in the supplied username), B<Config::Crontab> will
set B<error> with "Illegal username" and return I<undef>. If B<strict>
mode is enabled, B<Config::Crontab> will croak with the same error.
$c->owner_re('[^a-zA-Z0-9_\.-#]'); ## allow # in usernames
=head2 read([%args])
Parses the crontab file specified by B<file>. If B<file> is not set
(or is false in some way), the crontab will be read from a pipe to
C<crontab -l>. B<read> optionally takes the same arguments as B<new>
and B<init> in C<key =E<gt> value> style lists.
Until you B<read> the crontab, the B<Crontab> object will be
uninitialized and will contain no data. You may re-read existing
objects to get new crontab data, but the object will retain whatever
other attributes (e.g., strict, etc.) it may have from when it was
initialized (or later attributes were changed) but will reset
B<error>. Use B<init> to completely refresh an object.
If B<read> fails, B<error> will be set.
Examples:
## reads the crontab for this UID (via crontab -l)
$ct = new Config::Crontab;
$ct->read;
## reads the crontab from a file
$ct = new Config::Crontab;
$ct->read( -file => '/var/cronbackups/cron1' );
## same thing as above
$ct = new Config::Crontab( -file => '/var/cronbackups/cron1' );
$ct->read; ## '-file' attribute already set
## ditto using 'file' method
$ct = new Config::Crontab;
$ct->file('/var/cronbackups/cron1');
$ct->read;
## ditto, using a pipe
$ct = new Config::Crontab;
$ct->file('cat /var/cronbackups/cron1|');
$ct->read;
## ditto, using 'read' method
$ct = new Config::Crontab;
$ct->read( -file => 'cat /var/cronbackups/cron1|');
## now fortified with error-checking
$ct->read
or do {
warn $ct->error;
return;
};
=cut
## FIXME: need to say something about squeeze here, but squeeze(0)
## doesn't seem to work correctly (i.e., it still squeezes the file)
=head2 mode([mode])
Returns the current parsing mode for this object instance. If a mode
is passed as an argument, next time this instance parses a crontab
file, it will use this new mode. Valid modes are I<line>, I<block>
(the default), or I<file>.
Example:
## re-read this crontab in 'file' mode
$ct->mode('file');
$ct->read;
=head2 blocks([\@blocks])
Returns a list of B<Block> objects in this crontab. The B<blocks>
method also takes an optional list reference as an argument to set
this crontab's block list.
Example:
## get blocks, remove comments and dump
for my $block ( $ct->blocks ) {
$block->remove($block->select( -type => 'comment' ) );
$block->remove($block->select( -type => 'event',
-active => 0 );
print $block->dump;
}
## one way to remove unwanted blocks from a crontab
my @keepers = $ct->select( -type => 'comment',
-data_re => 'keep this block' );
$ct->blocks(\@keepers);
## another way to do it (notice 'nre' instead of 're')
$ct->remove($ct->select( -type => 'comment',
-data_nre => 'keep this block' ));
=head2 select([%criteria])
Returns a list of crontab lines that match the specified criteria.
Multiple criteria may be specified. If no criteria are specified,
B<select> returns a list of all lines in the B<Crontab> object.
Field names should be preceded by a hyphen (though without a hyphen
is acceptable too).
=item * -type
One of 'event', 'env', or 'comment'
=item * -E<lt>fieldE<gt>
The object in the block will be matched using 'eq' (string comparison)
against this criterion.
=item * -E<lt>fieldE<gt>_re
The value of the object method specified will be matched using Perl
regular expressions (see L<perlre>) instead of string comparisons
(uses the C<=~> operator internally).
=item * -E<lt>fieldE<gt>_nre
The value of the object method specified will be negatively matched
using Perl regular expressions (see L<perlre>) instead of string
comparisons (uses the C<!~> operator internally).
=back
Examples:
## returns a list of comments in the crontab that matches the
## exact phrase '## I like bread'
@comments = $ct->select( -type => 'comment',
-data => '## I like bread' );
## returns a list of comments in the crontab that match the
## regular expression 'I like bread'
@comments = $ct->select( -type => 'comment',
-data_re => 'I like bread' );
## select all cron jobs likely to repeat during daylight saving
@events = $ct->select( -type => 'event',
-hour => '2' );
## select cron jobs that happen from 10:20 to 10:40 on Fridays
@events = $ct->select( -type => 'event',
-hour => '10',
-minute_re => '^(?:[2-3][0-9]|40)$',
-dow_re => '(?:5|Fri)' );
## select all cron jobs that execute during business hours
@events = $ct->select( -type => 'event',
-hour_re => '^(?:[8-9]|1[0-6])$' );
## select all cron jobs that don't execute during business hours
@events = $ct->select( -type => 'event',
-hour_nre => '^(?:[8-9]|1[0-6])$' );
## get all event lines in the crontab
@events = $ct->select( -type => 'event' );
## get all lines in the crontab
@lines => $ct->select;
## get a line: note list context, also, no 'type' specified
($line) = $ct->select( -data_re => 'start backups' );
=head2 select_blocks([%criteria])
Returns a list of crontab Block objects that match the specified
criteria. If no criteria are specified, B<select_blocks> behaves just
like the B<blocks> method, returning all blocks in the crontab object.
The following criteria keys are available:
=over 4
=item * -index
An integer or list reference of integers. Returns a list of blocks
indexed by the given integer(s).
Example:
## select the first block in the file
@blocks = $ct->select_blocks( -index => 1 );
## select blocks 1, 5, 6, and 7
@blocks = $ct->select_blocks( -index => [1, 5, 6, 7] );
=back
B<select_blocks> returns B<Block> objects, which means that if you
need to access data elements inside the blocks, you'll need to
retrieve them using B<lines> or B<select> method first:
## the first block in the crontab file is an environment variable
## declaration: NAME=value
@blocks = $ct->select_blocks( -index => 1 );
print "This environment variable value is " . ($block[0]->lines)[0]->value . "\n";
=head2 block($line)
Returns the block that this line belongs to. If the line is not found
in any blocks, I<undef> is returned. I<$line> must be a
B<Config::Crontab::Event>, B<Config::Crontab::Env>, or
B<Config::Crontab::Comment> object.
Examples:
## will always return undef for new objects; you'd never really do this
$block = $ct->block( new Config::Crontab::Comment(-data => '## foo') );
## returns a Block object
$block = $ct->block($existing_crontab_line);
$block->dump;
## find and remove the block in which '/bin/baz' is executed
my $event = $ct->select( -type => 'event',
-command_re => '/bin/baz');
$block = $ct->block($event);
$ct->remove($block);
=head2 remove($block)
Removes a block from the crontab file (if a block is specified) or a
$ct->up($block); ## move this block up one position
=head2 first(@block), last(@block)
These methods move the B<Config::Crontab::Block> object(s) to the
first or last positions in the B<Crontab> object's internal array. If
the block is not already a member of the array, it will be added in
the first or last position respectively.
Example:
$ct->last(new Config::Crontab::Block( -data => <<_BLOCK_ ));
## eat ice cream
5 * * * 1-5 /bin/eat --cream=ice
_BLOCK_
=head2 before($look_for, @blocks), after($look_for, @blocks)
These methods move the B<Config::Crontab::Block> object(s) to the
position immediately before or after the I<$look_for> (or reference)
block in the B<Crontab> object's internal array.
If the objects are not members of the array, they will be added before
or after the reference block respectively. If the reference object
does not exist in the array, the blocks will be moved (or added) to
the beginning or end of the array respectively (like B<first> and
B<last>).
Example:
## search for a block containing a particular event (line)
$block = $ct->block($ct->select(-command_re => '/bin/foo'));
## add the new blocks immediately after this block
$ct->after($block, @new_blocks);
=head2 write([$filename])
Writes the crontab to the file specified by the B<file> method. If
B<file> is not set (or is false), B<write> will attempt to write to
a temporary file and load it via the C<crontab> program (e.g.,
C<crontab filename>).
You may specify an optional filename as an argument to set B<file>,
which will then be used as the filename.
If B<write> fails, B<error> will be set.
Example:
## write out crontab
$ct->write
or do {
warn "Error: " . $ct->error . "\n";
return;
};
## set 'file' and write simultaneously (future calls to read and
## write will use this filename)
$ct->write('/var/mycronbackups/cron1.txt');
## same thing
$ct->file('/var/mycronbackups/cron1.txt');
$ct->write;
=head2 remove_tab([file])
Removes a crontab. If B<file> is set, that file will be unlinked. If
B<file> is not set (or is false), B<remove_tab> will attempt to remove
the selected user's crontab via F<crontab -u username -r> or F<crontab
-r> for the current user id.
If B<remove_tab> fails, B<error> will be set.
Example:
$ct->remove_tab(''); ## unset file() and remove the current user's crontab
=head2 error([string])
Returns the last error encountered (usually during a file I/O
operation). Pass an empty string to reset (calling B<init> will also
reset it).
Example:
print "The last error was: " . $ct->error . "\n";
$ct->error('');
=head2 dump
Returns a string containing the crontab file.
Example:
## show crontab
print $ct->dump;
## same as 'crontab -l' except pretty-printed
$ct = new Config::Crontab; $ct->read; print $ct->dump;
=cut
############################################################
############################################################
package Config::Crontab::Block;
use strict;
use warnings;
use Carp;
our @ISA = qw(Config::Crontab::Base Config::Crontab::Container);
sub init {
my $self = shift;
my %args = @_;
$self->lines([]); ## initialize
$self->strict(0);
$self->system(0);
$self->lines($args{'-lines'}) if defined $args{'-lines'};
$self->strict($args{'-strict'}) if defined $args{'-strict'};
return 1 unless @_;
my $active = shift;
local $_;
$_->active($active) for $self->select(-type => 'env');
$_->active($active) for $self->select(-type => 'event');
return $active;
}
sub nolog {
my $self = shift;
return 1 unless @_;
my $nolog = shift;
local $_;
$_->nolog($nolog) for $self->select(-type => 'event');
return $nolog;
}
############################################################
############################################################
=head1 PACKAGE Config::Crontab::Block
This section describes B<Config::Crontab::Block> objects (hereafter
referred to as B<Block> objects). A B<Block> object is an abstracted
way of dealing with groups of crontab(5) lines. Depending on how
B<Config::Crontab> parsed the file (see the B<read> and B<mode>
methods in B<Config::Crontab> above), a block may consist of:
=over 4
=item a single line (e.g., a crontab event, environment setting, or comment)
=item a "paragraph" of lines (a group of lines, each group separated
by at least two newlines). This is the default parsing mode.
=item the entire crontab file
=back
The default for B<Config::Crontab> is to read in I<block> (paragraph)
mode. This allows you to group lines that have a similar purpose as
well as order lines within a block (e.g., often you want an
environment setting to take effect before certain cron commands
execute).
An illustration may be helpful:
=over 4
=item B<a crontab file read in block (paragraph) mode:>
Line Block Block Line Entry
1 1 1 ## grind disks
2 1 2 5 5 * * * /bin/grind
3 1 3
4 2 1 ## backup reminder to joe
5 2 2 MAILTO=joe
6 2 3 5 0 * * Fri /bin/backup
7 2 4
8 3 1 ## meeting reminder to bob
9 3 2 MAILTO=bob
10 3 3 30 9 * * Wed /bin/meeting
Notice that each block has its own internal line numbering. Vertical
space has been inserted between blocks to clarify block structures.
Block mode parsing is the default.
=item B<a crontab file read in line mode:>
Line Block Block Line Entry
1 1 1 ## grind disks
2 2 1 5 5 * * * /bin/grind
3 3 1
4 4 1 ## backup reminder to joe
5 5 1 MAILTO=joe
6 6 1 5 0 * * Fri /bin/backup
7 7 1
8 8 1 ## meeting reminder to bob
9 9 1 MAILTO=bob
10 10 1 30 9 * * Wed /bin/meeting
Notice that each line is also a block. You normally don't want to
read in line mode unless you don't have paragraph breaks in your
crontab file (the dumper prints a newline between each block; with
each line being a block you get an extra newline between each line).
=item B<a crontab file read in file mode:>
Line Block Block Line Entry
1 1 1 ## grind disks
2 1 2 5 5 * * * /bin/grind
3 1 3
4 1 4 ## backup reminder to joe
5 1 5 MAILTO=joe
6 1 6 5 0 * * Fri /bin/backup
7 1 7
8 1 8 ## meeting reminder to bob
9 1 9 MAILTO=bob
10 1 10 30 9 * * Wed /bin/meeting
Notice that there is only one block in file mode, and each line is a
block line (but not a separate block).
=back
=head1 METHODS
This section describes methods accessible from B<Block> objects.
=head2 new([%args])
Creates a new B<Block> object. You may create B<Block> objects in any
of the following ways:
=over 4
=item Empty
$event = new Config::Crontab::Block;
=item Fully Populated
$event = new Config::Crontab::Block( -data => <<_BLOCK_ );
## a comment
5 19 * * Mon /bin/fhe --turn=dad
_BLOCK_
=back
Constructor attributes available in the B<new> method take the same
arguments as their method counterparts (described below), except that
the names of the attributes must have a hyphen ('-') prepended to the
attribute name (e.g., 'lines' becomes '-lines'). The following is a
list of attributes available to the B<new> method:
=over 4
=item B<data>
=item B<lines>
=back
If the B<-data> attribute is present in the constructor when other
attributes are also present, the B<-data> attribute will override all
other attributes.
Each of these attributes corresponds directly to its similarly-named
method.
Examples:
## create an empty block object & populate it with the data method
$block = new Config::Crontab::Block;
$block->data( <<_BLOCK_ ); ## via a 'here' document
## 2:05a Friday backup
MAILTO=sysadmin@mydomain.ext
5 2 * * Fri /sbin/backup /dev/da0s1f
_BLOCK_
## create a block in the constructor (also via 'here' document)
$block = new Config::Crontab::Block( -data => <<_BLOCK_ );
## 2:05a Friday backup
MAILTO=sysadmin@mydomain.ext
5 2 * * Fri /sbin/backup /dev/da0s1f
_BLOCK_
## create an array of crontab objects
my @lines = ( new Config::Crontab::Comment(-data => '## run bar'),
new Config::Crontab::Event(-data => '5 8 * * * /foo/bar') );
## create a block object via lines attribute
$block = new Config::Crontab::Block( -lines => \@lines );
## ...or with lines method
$block->lines(\@lines); ## @lines is an array of crontab objects
If bogus data is passed to the constructor, it will return I<undef>
instead of an object reference. If there is a possiblility of poorly
formatted data going into the constructor, you should check the object
variable for definedness before using it.
If the B<-data> attribute is present in the constructor when other
attributes are also present, the B<-data> attribute will override all
other attributes.
=head2 data([string])
Get or set a raw block. Internally, B<Block> passes its arguments to
other objects for parsing when a parameter is present.
Example:
## re-initialize this block
$block->data("## comment\n5 * * * * /bin/checkup");
print $block->data;
Block data is terminated with a final newline.
=head2 lines([\@objects])
Get block data as a list of B<Config::Crontab::*> objects. Set block
data using a list reference.
Example:
$block->lines( [ new Config::Crontab::Comment( -data => "## run backup" ),
new Config::Crontab::Event( -data => "5 4 * * 1-5 /sbin/backup" ) ] );
## sorta like $block->dump
for my $obj ( $block->lines ) {
print $obj->dump . "\n";
}
## a clumsy way to "unshift" a new event
$block->lines( [new Config::Crontab::Comment(-data => '## hi mom!'),
$block->lines] );
## the right way to add a new event
$block->first( new Config::Crontab::Comment(-data => '## hi mom!') );
print $_->dump for $block->lines;
=head2 select([%criteria])
Returns a list of B<Event>, B<Env>, or B<Comment> objects from a block
that match the specified criteria. Multiple criteria may be specified.
Field names should be preceded by a hyphen (though without a hyphen
is acceptable too; we use hyphens to avoid the need for quoting keys
and avoid potential bareword collisions).
If not criteria are specified, B<select> returns a list of all lines
in the block (like B<lines>).
Example:
## select all events
for my $event ( $block->select( -type => 'event') ) {
print $event->dump . "\n";
}
## select events that have the word 'foo' in the command
for my $event ( $block->select( -type => 'event', -command_re => 'foo') ) {
print $event->dump . "\n";
}
=head2 remove(@objects)
Remove B<Config::Crontab::*> objects from this block.
Example:
## simple case: you need to get a handle on these objects first
$block->remove( $obj1, $obj2, $obj3 );
## more complex: remove an event from a block by searching
for my $event ( $block->select( -type => 'event') ) {
next unless $event->command =~ /\bbackup\b/; ## look for backup command
$block->remove($event); last; ## and remove it
}
=head2 replace($oldobj, $newobj)
Replaces I<$oldobj> with I<$newobj> within a block. Returns I<$oldobj>
if successful, I<undef> otherwise.
Example:
## replace $event1 with $event2 in this block.
## '=>' is the same as a comma (,)
($event1) = $block->select(-type => 'event', -command => '/bin/foo');
$event2 = new Config::Crontab::Event( -data => '5 2 * * * /bin/bar' );
ok( $block->replace($event1 => $event2) );
=head2 up($target_obj), down($target_obj)
These methods move the B<Config::Crontab::*> object up or down within
the block.
If the object is not a member of the block, it will be added to the
block in the first position for B<up> and it will be added to the
block in the last position for B<down>.
Examples:
$block->up($event); ## move event up one position in the block
## add a new event at the end of the block
$block->down(new Config::Crontab::Event(-data => '5 2 * * Mon /bin/monday'));
=head2 first(@target_obj), last(@target_obj)
These methods move the B<Config::Crontab::*> object(s) to the first
or last positions in the block.
If the object or objects are not members of the block, they will be
added to the first or last part of the block respectively.
Examples:
$block->first($comment); ## move $comment to the first line in this block
## add these new events to the end of the block
$block->last( new Config::Crontab::Comment(-data => '## hi mom!'),
new Config::Crontab::Comment(-data => '## hi dad!'), );
=head2 before($look_for, @obj), after($look_for, @obj)
These methods move the B<Config::Crontab::*> object(s) to the position
immediately before or after the I<$look_for> (or reference) object
in the block.
If the objects are not members of the block, they will be added
to the block before or after the reference object. If the reference
object does not exist in the block, the objects will be moved (or
added) to the beginning or end of the block respectively (much the
same as B<first> and B<last>).
( run in 3.969 seconds using v1.01-cache-2.11-cpan-2398b32b56e )