GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Astro::App::Satpass2::Utils(3) User Contributed Perl Documentation Astro::App::Satpass2::Utils(3)

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

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

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

This module is private to the 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.

This module supports the following exportable subroutines:

 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 "back_end" attribute, which defines the class name for a DateTime back end module, and any class-specific arguments to be passed to its "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 "new()" that were specified when it was set. If called in scalar context it returns the class name, with the arguments to "new()" appended as "name=value" strings, comma-delimited.

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

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

 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 "back_end" information, if any, to the class name of record. It is called this way because "SUPER::" is resolved with regard to the package it occurs in, not the package of the invocant.

 $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 ~/ and ~user/, we support ~+/ (equivalent to ./) and ~~/ (the user's configuration directory). The expansion of ~~/ 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 "whinge()", "wail()", and "weep()".

 my $path = find_package_pod( $package_name );

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

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

 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 "$invocant->can( $method )" if the invocant is a blessed reference, or a return otherwise.

 instance( $object, $class )

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

 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 Getopt::Long option specifications derived from the code's "Verb()" attribute. If the attributes are computed and the $opt hash reference is supplied, it may be modified by the computation.

 load_package( $module );
 load_package( $module, 'Astro::App::Satpass2' );
 load_package( { lib => '.lib' }, $module );
 $object->load_package( { complaint => 'wail' }. $module );

This exportable subroutine loads a Perl module. The first argument is the name of the module itself. Subsequent arguments are prefixes to try, without any trailing colons.

This subroutine can also be called as a method. If this is done errors will be reported with a call to the invocant's "weep()" method if that exists. Otherwise "Carp" will be loaded and errors will be reported by "Carp::confess()".

An optional first argument is a reference to a hash of option values. The supported values are:

complaint
This specifies how to report invalid module names if "load_package()" is called as a method. Valid values are 'whinge', 'wail', and 'weep'. An invalid value is equivalent to 'weep', which is the default. If not called as a method, this option is ignored and a call to "Carp::confess()" is done.
fatal
If "load_package()" is called as a method, this argument specifies how to report a failure to load the requested module. Valid values are 'whinge', 'wail' and 'weep'. An invalid value is equivalent to 'wail', which is the default. If "load_package()" is not called as a method, any true value will cause "Carp::croak()" to be called, and the failure not to be recorded, so that the load can be retried with a different path.

Either way, a false value causes "load_package()" to simply return if the requested module can not be loaded.

lib
This specifies a directory to add to @INC before attempting the load. If it is not specified, lib/ in the configuration directory is used. If it is specified as "undef", nothing is added to @INC. No expansion is done on the directory name.

In the examples, if $module contains 'Foo', the first example will try to "require 'Foo'", and the second will try to "require 'Astro::App::Satpass2::Foo'" and "require 'Foo'", in that order. The first attempt that succeeds returns the name of the module actually loaded. If no attempt succeeds, "undef" is returned.

Arguments are cached, and subsequent attempts to load a module simply return the contents of the cache.

 my $hash_ref = merge_hashes( \%hash1, \%hash2, ... );

This subroutine returns a reference to a hash that contains keys merged from all the hash references passed as arguments. Arguments which are not hash references are removed before processing. If there are no arguments, an empty hash is returned. If there is exactly one argument, it is returned. If there is more than one argument, a new hash is constructed from all keys of all hashes, and that hash is returned. If the same key appears in more than one argument, the value from the right-most argument is the one returned.

 my $cfg_dir = my_dist_config( { 'create-directory' => 1 } );

This subroutine returns a path to the user's configuration directory. If environment variable "ASTRO_APP_SATPASS2_CONFIG_DIR" is defined, that is expanded to an absolute path and returned regardless of any arguments. Otherwise it simply wraps

 File::HomeDir->my_dist_config( 'Astro-App-Satpass2' );

You can pass an optional reference to an options hash (sic!). The only supported option is {'create-directory'}, which is passed verbatim to the "File::HomeDir" 'create' option.

If the configuration directory is found or successfully created, the path to it is returned. Otherwise "undef" is returned.

my_dist_config under macOS

Under macOS 10.15 Catalina it has proven difficult/impossible to grant a launchd job access to the Documents/ directory, which is where File::HomeDir puts the configuration data.

To give the user a way to work around this, the "darwin" implementation checks "File::HomeDir->my_dist_data( 'Astro-App-Satpass2' )" after the environment variable, but before the File::HomeDir "my_dist_config()" directory.

The "my_dist_data()" directory is ~/Library/Application Support/Perl/dist/Astro-App-Satpass2/, which is accessible from "launchd" jobs, at least as of macOS 10.15 Catalina. This directory will not be created if it does not exist, even if a true value was specified for the 'create-directory' option.

 my ( $cls, @arg ) = $self->__parse_class_and_args( $val );

This mixin parses the $val as a list of comma-delimited "name=value" pairs. The first element, though, is expected not to contain an equals sign, and in fact to be a valid class name. The invocant is only used for error messages, and must conform to the Astro::App::Satpass2::Warner interface.

 say scalar quoter( @vals );
 say quoter( @vals );

This exportable subroutine quotes and escapes its arguments as necessary for the parser. Specifically, if an argument is:

* undef, 'undef' is returned;

* a number, $string is returned unmodified;

* an empty string, '' is returned;

* a string containing white space, quotes, or dollar signs, the value is escaped and enclosed in double quotes ("").

* anything else is returned unmodified.

If called in scalar context, the results are concatenated with "join ' ', ...". Otherwise they are simply returned.

 my ( $self, $opt, @args ) = __arguments( @_ );

This subroutine is intended to be used to unpack the arguments of an "Astro::App::Satpass2" interactive method or a code macro.

Specifically, this subroutine expects to be called from a subroutine or method that has the "Verb()" attribute, and expects the contents of the parentheses in the "Verb()" attribute to be a set of white-space-delimited Getopt::Long option specifications. Further, if the subroutine has a "Configure()" attribute, it will be used to configure the Getopt::Long object.

The first argument is expected to be the invocant, and is always returned intact.

Subsequent arguments are preprocessed by calling their "dereference()" method if it exists. This is a severe wart on the code, but was needed (I thought) to get certain arguments through "Template-Toolkit". Arguments that do not have a "dereference()" method are left unmodified, as are any unblessed arguments.

If the first remaining argument after preprocessing is a hash reference, it is assumed that the options have already been processed, and we simply return the invocant and the remaining arguments as they now stand.

If the first remaining argument after preprocessing is not a hash reference, we run all the remaining arguments through Getopt::Long, and return the invocant, the options hash populated by Getopt::Long, and all remaining arguments. If Getopt::Long encounters an error an exception is thrown. This is done using the invocant's "wail()" method if it has one, otherwise "Carp" is loaded and "Carp::croak()" is called.

This module supports the following exportable constants. You can export them all using tag ':ref'.

This constant is simply "ref []".

This constant is simply "ref sub {}".

This constant is simply "ref {}".

This constant is simply "ref qr{}".

This constant is simply "ref \1".

This module exports the following globals:

This global contains all modules in this package.

Support is by the author. Please file bug reports at <https://rt.cpan.org/Public/Dist/Display.html?Name=Astro-App-Satpass2>, <https://github.com/trwyant/perl-Astro-App-Satpass2/issues>, or in electronic mail to the author.

Thomas R. Wyant, III wyant at cpan dot org

Copyright (C) 2011-2021 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

2021-11-04 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.