view release on metacpan or  search on metacpan

lib/Astro/App/Satpass2/Utils.pm  view on Meta::CPAN

__END__

=head1 NAME

Astro::App::Satpass2::Utils - Utilities for Astro::App::Satpass2

=head1 SYNOPSIS

 use Astro::App::Satpass2::Utils qw{ instance };
 instance( $foo, 'Bar' )
    or die '$foo is not an instance of Bar';

=head1 DESCRIPTION

This module is a grab-bag of utilities needed by
L<Astro::App::Satpass2|Astro::App::Satpass2>.

This module is B<private> to the
L<Astro::App::Satpass2|Astro::App::Satpass2> package. Any and all
functions in it can be modified or revoked without prior notice. The
documentation is for the convenience of the author.

All documented subroutines can be exported, but none are exported by
default.

=head1 SUBROUTINES

This module supports the following exportable subroutines:

=head2 back_end

 my ( $class, @args ) = $self->back_end();
 my $back_end = $self->back_end();
 $self->back_end( 'Christian,reform_date=uk' );
 $self->back_end( 'Christian', reform_date => 'uk' );
 $self->back_end( undef );

This mixin is both accessor and mutator for the C<back_end> attribute,
which defines the class name for a L<DateTime|DateTime> back end module,
and any class-specific arguments to be passed to its C<new()> method.

If called without arguments it is an accessor. If called in list context
it returns the class name as specified when it was set, followed by any
arguments to C<new()> that were specified when it was set. If called in
scalar context it returns the class name, with the arguments to C<new()>
appended as C<"name=value"> strings, comma-delimited.

If called with arguments it is a mutator. The first argument is the
class name, possibly with leading C<'DateTime::Calendar::'> omitted)
followed optionally by comma-delimited C<"name=value"> arguments to
C<new()>. Subsequent arguments are name/value pairs of arguments to
C<new()>.

If called with a single undefined argument, it specifies the default.

=head2 __back_end_class_name_of_record

 sub class_name_of_record {
     my ( $self ) = @_;
     return $self->__back_end_class_name_of_record(
         $self->SUPER::class_name_of_record() );
 }

This mixin appends the C<back_end> information, if any, to the class
name of record. It is called this way because C<SUPER::> is resolved
with regard to the package it occurs in, not the package of the
invocant.

=head2 expand_tilde

 $expansion = $self->expand_tilde( $file_name );

This mixin (so-called) performs tilde expansion on the argument,
returning the result. Arguments that do not begin with a tilde are
returned unmodified. In addition to the usual F<~/> and F<~user/>, we
support F<~+/> (equivalent to F<./>) and F<~~/> (the user's
configuration directory). The expansion of F<~~/> will result in an
exception if the configuration directory does not exist.

All that is required of the invocant is that it support the package's
suite of error-reporting methods C<whinge()>, C<wail()>, and C<weep()>.

=head2 find_package_pod

 my $path = find_package_pod( $package_name );

This subroutine finds the given package in C<@INC> and returns the path
to its POD file. C<@INC> entries which are references are ignored.

The code for this subroutine borrows heavily from Neil Bowers'
L<Module::Path|Module::Path>. In fact, I would probably have used that
module except for the need to find the F<.pod> file if it was separate
from the F<.pm> file.

=head2 has_method

 has_method( $object, $method );

This exportable subroutine returns a code reference to the named method
if the given object has the method, or a false value otherwise. What you
actually get is the result of C<< $invocant->can( $method ) >> if the
invocant is a blessed reference, or a return otherwise.

=head2 instance

 instance( $object, $class )

This exportable subroutine returns a true value if C<$object> is an
instance of C<$class>, and false otherwise. The C<$object> argument need
not be a reference, nor need it be blessed, though in these cases the
return is false.

=head2 __legal_options

 my $lgl = $self->__legal_options( $code, $opt );

This method takes as its arguments a code reference and an optional hash
reference. It returns a reference to an array of
L<Getopt::Long|Getopt::Long> option specifications derived from the
code's C<Verb()> attribute. If the attributes are computed and the
C<$opt> hash reference is supplied, it may be modified by the
computation.

=head2 load_package