The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Astro-App-Satpass2-0.020
River stage zero No dependents
++
/ Astro::App::Satpass2::Macro

NAME

Astro::App::Satpass2::Macro - Implement a macro

SYNOPSIS

No user-serviceable parts inside.

DESCRIPTION

This is an abstract class to implement macros.

METHODS

This class supports the following public methods:

new

 my $macro = Astro::App::Satpass2::Macro->new( name => 'Foo' );

This static method returns a new macro object. The arguments are pairs of attribute names and values. An exception will be thrown if the object can not be constructed.

execute

 print $macro->execute( $name, @args );

This method executes the named macro, passing it the given arguments. The results of the execution are returned.

This method must be overridden by the subclass.

generator

 print $macro->generator( 'foo' );
 print $macro->generator();

If the generate attribute (q.v.) was not provided when the object was instantiated , this method fails.

If the generate attribute was provided when the object was instantiated and arguments were provided, this method validates that the arguments are all names of macros implemented by this object, failing if they are not. If the arguments are valid, it calls the code provided in the generate attribute with the invocant and the arguments.

If the generate attribute was provided when the object was instantiated and no arguments were provided, the code provided in the generate attribute is called with the invocant and the list of all macros implemented by the invocant in ASCIIbetical order.

implements

 print map { "$_\n" } sort $macro->implements();
 $macro->implements( $name )
     and print "Implements $name\n";
 $macro->implements( $name, required => 1 );

This method has several overloads dealing with what macros this object implements.

If $name is omitted or undef, it returns the names of all macros implemented by this object, in no particular order.

If $name is specified, it returns a true value if the object implements the named macro, and false otherwise. No commitment is made as to exactly what value is returned, and the caller is to regard this value as opaque.

After the $name argument, optional name/value pairs can be specified. The only one defined at the moment is required, which causes an exception to be thrown if this object does not implement the named macro.

init

 $self->init();

This method performs initialization and checking of attributes. It should not be called by the user. Subclasses that override this method to add extra attributes should call $self->SUPER::init().

Nothing is returned.

wail

 $macro->wail( 'Something bad happened' );

This convenience method simply delegates to the corresponding Astro::App::Satpass2::Warner method.

weep

 $macro->wail( 'Something bad happened' );

This convenience method simply delegates to the corresponding Astro::App::Satpass2::Warner method.

whinge

 $macro->wail( 'Something bad happened' );

This convenience method simply delegates to the corresponding Astro::App::Satpass2::Warner method.

ATTRIBUTES

This class has the following attributes:

generate

This attribute is optional, but if specified as something other than undef must be a code reference.

This code will be called by the generator() method after it has validated or defaulted the arguments, and whatever it returns will be returned by generator().

The idea is to provide a way to recover a macro definition, given that only the creator of the class knows what user-provided information it needs to perform this function. The return need not be the exact information originally provided, but it must be information that, if provided again, will generate the same macro. In the case of string data, this means that it may be quoted or escaped differently, but after the quotes and escapes are processed you must get the same string that you got by processing the quotes and escapes in the string originally provided. If the object implements more than one macro, it should be capable of returning the information on any one of them by itself.

name

This required attribute is the name of the object. It is returned by the name() method.

parent

This required attribute is the Astro::App::Satpass2 object that this object's execute() method is to operate on. It must be a subclass of Astro::App::Satpass2. We actually hold a weak reference to this object, so it can be garbage-collected. It is returned by the parent() method.

warner

This optional attribute is an Astro::App::Satpass2::Warner object used to report errors. If omitted, one will be generated. It is returned by the warner() method.

SEE ALSO

<<< replace or remove boilerplate >>>

SUPPORT

Support is by the author. Please file bug reports at http://rt.cpan.org, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

Copyright (C) 2013-2014 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.