Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Astro::App::Satpass2::UsersContributed Perl DocuAstro::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

       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

       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

	$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

	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

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

	   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.

	   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()"

       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

       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
       <>, 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.

perl v5.32.1			  2021-11-04	Astro::App::Satpass2::Utils(3)


Want to link to this manual page? Use this URL:

home | help