Instantiator

 $fmt = Astro::App::Satpass2::FormatValue->new();

This static method instantiates a new value formatter. It takes as arguments name/value pairs.

Because this class has no mutators you must give it all the information it needs to do its job when you instantiate it.

The following argument names are recognized:

data

This argument is a hash containing the data to be displayed. The keys in the hash are accessed by the various transformation and formatter methods. This argument is technically optional, but unless you have specified "title => 1" (which see) you will not get a very useful object if you omit it.

If this hash contains a {time} key, the Astro::Coord::ECI objects in the "{body}" and "{station}" keys (if any) will be set to that value.

date_format

This argument is the string that the "time_formatter" will use to format dates. It is assumed that this format will not produce any time information, though this is not enforced. The default is whatever the default date format is for the "time_formatter".

default

This optional argument is a hash used to override the defaults for the various formatters. The keys are formatter names, and the values of those keys are hashes containing the specific argument defaults.

desired_equinox_dynamical

This optional argument is the desired equinox in dynamical time. If specified as a non-zero Perl time, inertial coordinates will be precessed to this equinox. The default is 0.

fixed_width

This optional argument specifies whether or not fixed-width fields are to be produced. If true (the default) numeric default widths are applied where needed. If false the default width is '', which is the convention for variable-width fields.

list_formatter

This optional argument provides the implementation of the list() formatter method. If you provide a defined value it must be a code reference. The code reference will be called with the same arguments as were used for "local_coord()", including the invocant.

local_coordinates

This optional argument provides the implementation of the local_coord() formatter method. You can provide either a code reference of one of the following strings:

 az_rng --------- Azimuth and range;
 azel ----------- Elevation and azimuth;
 azel_rng ------- Elevation, azimuth and range;
 equatorial ----- Right ascension and declination;
 equatorial_rng - Right ascension, declination, and range.
    

The code reference will be called with the same arguments as were used for "local_coord()", including the invocant.

The default is "azel_rng".

overflow

If this optional argument is true (in the Perl sense, i.e. anything but "undef", 0, or '') fields will be allowed to overflow their widths. If false (the default) too-long strings will be truncated on the right, and too-long numeric fields will generally be "*"-filled.

report

This optional argument is the name of the report being produced (e.g. 'pass', 'flare', or whatever). If specified, format effectors will use this for report-specific localization of titles, missing data text, and literals.

The localization will come from key "{"-$report"}{string}{$string}", where $report is the value of this argument, and $string is the string being localized.

time_format

This argument is the string that the "time_formatter" will use to format times of day. It is assumed that this format will not produce any date information, though this is not enforced. The default is whatever the default time format is for the "time_formatter".

time_formatter

This argument is either the name or an instance of an Astro::App::Satpass2::FormatTime subclass. This object is used to format times. The default is "Astro::App::Satpass2::FormatTime".

title

If this argument is true, the formatter methods will produce titles rather than values. In this case the "data" hash is unused. The default is false.

title_gravity

This argument specifies the value for the title_gravity attribute. See the title_gravity() documentation for full details.

warner

This optional argument must be an instance of Astro::App::Satpass2::Warner. If not provided, a new "Warner" object will be instantiated.

Accessors

body

 $fmt->body();

This accessor returns the contents of the "{body}" key of the original hash passed to the "data" argument when the object was instantiated. It returns a false value if the "{body}" key exists but is not an "Astro::Coord::ECI|Astro::Coord::ECI", or if the key does not exist.

This accessor exists because the Astro::App::Satpass2::Format::Template list() method needs to look at the body to decide what to display.

Mutators

If called without an argument, all mutators act as accessors, and return the value of the attribute.

If called with an argument, they change the attribute (or croak if the new value is invalid), and return their invocant.

fixed_width

 $fmt->fixed_width( 0 );
 say 'Fixed-width formatting is ',
    $fmt->fixed_width() ? 'on' : 'off';

If false, this boolean attribute causes all widths not explicitly specified to default to '', which is the convention for non-fixed-width fields. It can also be set via the "fixed_width" argument to "new()". The default is 1 (i.e. "true").

If called without an argument, this method acts as an accessor, returning the current value.

This boolean attribute has a mutator because "Template-Toolkit" needs to modify it, and "Template-Toolkit"-style named arguments can't be used for "clone()" because of the way the interface is designed.

title_gravity

 $fmt->title_gravity( 'bottom' );
 say 'Title gravity is ', $fmt->title_gravity();

This attribute specifies how multiline titles are aligned. The possible values are 'top' or 'bottom'. The manifest constants "TITLE_GRAVITY_TOP" and "TITLE_GRAVITY_BOTTOM" are defined to represent these, but they are not exported.

If you specify 'bottom', you get an extra empty line above the titles. This is an annoying behavior necessitated by the fact that the first line of the first title has to be inserted into the output before we know how many lines are needed to print all the titles. So we force an extra line with blanks to get the process rolling.

This hack means that you do not want to use 'bottom' unless you intend to actually display all the lines of each title.

The default is 'top'.

This attribute has a mutator because "Template-Toolkit" needs to modify it.

Transformations

appulse

 my $apls = $fmt->appulse();

This method returns an "Astro::App::Satpass2::FormatValue" object based on the invocant, with the data coming from the "{appulse}" key of the original object's data, augmented with the "{station}" and "{time}" of the original data.

bodies

 my $array_ref = $fmt->bodies();

For reasons that seemed logical at the time, the Astro::App::Satpass2 position() method produces a hash containing the time, some other relevant data, and a "{bodies}" key which contains a reference to an array of all the relevant bodies.

This method extracts an array of more-normally-structured "Astro::App::Satpass2::FormatValue" objects which give access to the original bodies.

center

 $center = $fmt->center();

This method returns an "Astro::App::Satpass2::FormatValue" object based on the invocant, with the data coming from the "{center}" key of the original object's data, augmented with the "{station}" and "{time}" of the original data.

clone

 my $clone = $fmt->( %arg );

This method performs a shallow clone the invocant. That is to say, the clone is a separate object, but it shares all contained objects and references with the original object. If any arguments are passed, they are used to initialize the cloned object, instead of the corresponding data from the invocant.

earth

 my $earth = $fmt->earth();

This method returns an "Astro::App::Satpass2::FormatValue" object based on the invocant, with its "{station}" key set to the center of the Earth.

events

 foreach my $event ( @{ $fmt->events() || [] } ) {
     ... do something with the event ...
 }

This method returns a reference to an array of "Astro::App::Satpass2::FormatValue" objects manufactured out of the contents of the "{events}" key of the invocant's data.

reflections

 $array_ref = $fmt->reflections();

This method returns a reference to an array of "Astro::App::Satpass2::FormatValue" objects which represent the results of calling "$fmt->body()->reflection()", passing it the contents of the "{station}" and "{time}" keys. It will return "undef" if the body does not support this method, or if it is below the horizon or not lit.

station

 my $station = $fmt->station();

This method returns an object identical to the invocant, with the exception that the "{body}" and "{station}" contents are exchanged. With this,

 $fmt->station()->latitude()

(e.g.) gets you the latitude of the observing station, whereas

 $fmt->latitude()

would get you the latitude of the orbiting body.

Formatters

All the formatter arguments are passed by name: that is, as name/value pairs. Because of the idiosyncrasies of "Template-Toolkit", or because of the author's lack of experience with it, some weirdness has been introduced into what would have been a straightforward signature:

* "Template-Toolkit" recognizes special named-argument syntax, and presents the arguments as a hash appended to the argument list. Therefore, if the formatters see a hash as the last argument, that hash will be expanded into a list and prepended to the argument list. Because "Template-Toolkit" does not supply an empty hash if none of its named arguments are seen, you can not pass a hash as the last argument.

* "Template-Toolkit" seems to have a strong preference for dealing with arrays as references. But array references are not flattened when passed as arguments. If the caller wants an array reference flattened, it must be made into an instance of Astro::App::Satpass2::Wrap::Array. This is really (I think and hope!) only a problem for whoever writes the code reference that gets passed to the "local_coordinates" argument of "new()" (i.e. me).

The summary of all this is that arguments are taken in the following order:

1) arguments from the final hash, if any

2) everything else except

3) Astro::App::Satpass2::Wrap::Array objects, which are expanded and put last.

Since arguments are passed by name, you can specify the same argument more than once. If this happens, the "last" specification of the argument is the one taken.

One additional complication: for convenience in overriding default titles, if the list of arguments from item "(2)" above ('everything else') has an odd number of elements, 'title' is prepended. The net result of this is that if $title is an "Astro::App::Satpass2::FormatValue" object with "title => 1", something like $title->azimuth( '' ) will produce an empty field of the proper width.

The following arguments are accepted by all formatters:

align_left

This argument specifies that the given value be left-aligned in its field. This defaults to true for text items, and false for numeric items.

literal

This argument specifies text to be displayed in place of the underlying datum.

missing

This argument specifies the text to be filled in if the underlying datum is not available. It defaults to spaces.

title

This argument specifies the text to be used as the title of the formatter -- that is, the text which is displayed when the formatter is initialized with "title => 1". The default is appropriate to the formatter.

almanac

 print $fmt->almanac();

The "almanac_hash()" method provided by some subclasses of "Astro::Coord::ECI" returns a hash which includes an "{almanac}" key, which contains various items describing the almanac entry. This method provides access to the contents of the "{almanac}" key.

In addition to the standard arguments, it takes the following:

units

This argument specifies the units of the field. Any almanac_pseudo_units units are accepted; anything else will result in an exception. The default is "description".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 40.

altitude

 print $fmt->altitude();

This method formats the altitude of the "{body}" object above sea level.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 1.

units

This argument specifies the units of the field. Any length units are accepted; anything else will result in an exception. The default is "kilometers".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 7.

angle

 print $fmt->angle();

This method formats the "{angle}" value, which typically represents an appulse angle.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 1.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "degrees".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 5.

apoapsis

 print $fmt->apoapsis();

This method formats the apoapsis of the "{body}" object's orbit.

In addition to the standard arguments, it takes the following:

as_altitude

If this boolean argument is true (in the Perl sense) the value is given as altitude above the Earth's surface. If false, the value is given as distance from the Earth's center. The default is 1.

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 0.

units

This argument specifies the units of the field. Any length units are accepted; anything else will result in an exception. The default is "kilometers".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 6.

apogee

 print $fmt->apogee();

This method formats the apogee of the "{body}" object's orbit. Yes, this is the same as the apoapsis.

In addition to the standard arguments, it takes the following:

as_altitude

If this boolean argument is true (in the Perl sense) the value is given as altitude above the Earth's surface. If false, the value is given as distance from the Earth's center. The default is 1.

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 0.

units

This argument specifies the units of the field. Any length units are accepted; anything else will result in an exception. The default is "kilometers".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 6.

argument_of_perigee

 print $fmt->argument_of_perigee();

This method formats the argument of perigee from the "{body}" object's TLE data.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 4.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "degrees".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 9.

ascending_node

 print $fmt->ascending_node();

This method formats the ascending node from the "{body}" object's TLE data.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 2.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "right_ascension".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 11.

azimuth

 print $fmt->azimuth();

This method formats the azimuth of the "{body}" object as seen from the "{station}" object.

In addition to the standard arguments, it takes the following:

bearing

This argument specifies the size of the bearing information to append to the azimuth. If zero or any non-numeric value, no bearing information will be appended. The default is 0.

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 1.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "degrees".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 5.

b_star_drag

 print $fmt->b_star_drag();

This method formats the B* drag from the "{body}" object's TLE data..

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 4.

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 11.

classification

 print $fmt->classification();

This method formats the classification of the "{body}" object's TLE data. This will usually be 'U', for 'unclassified'.

In addition to the standard arguments, it takes the following:

units

This argument specifies the units of the field. Any string_pseudo_units units are accepted; anything else will result in an exception. The default is "string".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 1.

date

 print $fmt->date();

This method formats the "{time}" value using the "date_format" template. This is intended to produce the date, without time information.

In addition to the standard arguments, it takes the following:

delta

This argument specifies a number of seconds to add to the value before it is formatted. The default is 0.

format

This argument specifies the format to use for formatting the value. The default is ...

gmt

If this boolean argument is true, the value is formatted in GMT, regardless of how the time formatter is set up. If false, it is formatted according to the "time_formatter"'s zone setting. The default is the "time_formatter"'s "gmt" setting.

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 5.

units

This argument specifies the units of the field. Any time_units units are accepted; anything else will result in an exception. The default is "local".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is "".

declination

 print $fmt->declination();

This method formats the declination of the "{body}" object as seen from the "{station}" object.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 1.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "degrees".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 5.

eccentricity

 print $fmt->eccentricity();

This method formats the eccentricity of the "{body}" object's orbit.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 5.

units

This argument specifies the units of the field. Any dimensionless units are accepted; anything else will result in an exception. The default is "unity".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 8.

effective_date

 print $fmt->effective_date();

This method formats the effective date of the "{body}" object's TLE data.

In addition to the standard arguments, it takes the following:

format

This argument specifies the format to use for formatting the value. The default is ...

gmt

If this boolean argument is true, the value is formatted in GMT, regardless of how the time formatter is set up. If false, it is formatted according to the "time_formatter"'s zone setting. The default is the "time_formatter"'s "gmt" setting.

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is "".

units

This argument specifies the units of the field. Any time_units units are accepted; anything else will result in an exception. The default is "local".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is "".

element_number

 print $fmt->element_number();

This method formats the number of the "{body}" object's TLE data. This is usually incremented each time a new set is published.

In addition to the standard arguments, it takes the following:

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 4.

elevation

 print $fmt->elevation();

This method formats the elevation of the "{body}" object above the horizon as seen from the "{station}" object.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 1.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "degrees".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 5.

ephemeris_type

 print $fmt->ephemeris_type();

This method formats the ephemeris type of the "{body}" object's TLE data. This is supposed to say which model is to be used to calculate the object's position, but in practice is typically 0 or blank.

In addition to the standard arguments, it takes the following:

units

This argument specifies the units of the field. Any string_pseudo_units units are accepted; anything else will result in an exception. The default is "string".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 1.

epoch

 print $fmt->epoch();

This method formats the epoch from the "{body}" object's TLE data.

In addition to the standard arguments, it takes the following:

format

This argument specifies the format to use for formatting the value. The default is ...

gmt

If this boolean argument is true, the value is formatted in GMT, regardless of how the time formatter is set up. If false, it is formatted according to the "time_formatter"'s zone setting. The default is the "time_formatter"'s "gmt" setting.

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is "".

units

This argument specifies the units of the field. Any time_units units are accepted; anything else will result in an exception. The default is "local".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is "".

event

 print $fmt->event();

This method formats the contents of "{event}", which generally comes from an Astro::Coord::ECI::TLE "pass()" calculation.

In addition to the standard arguments, it takes the following:

units

This argument specifies the units of the field. Any event_pseudo_units units are accepted; anything else will result in an exception. The default is "localized".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 5.

first_derivative

 print $fmt->first_derivative();

This method formats the first derivative from the "{body}" object's TLE data. The units are actually angle per minute squared, but this formatter treats them as angle. That is, it will give you output in radians per minute squared if you so desire, but not in radians per second squared.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 10.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "degrees".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 17.

fraction_lit

 print $fmt->fraction_lit();

This method formats the fraction of the "{body}" object which is lit. This is only available if that object supports the "phase()" method.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 2.

units

This argument specifies the units of the field. Any dimensionless units are accepted; anything else will result in an exception. The default is "unity".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 4.

illumination

 print $fmt->illumination();

This method formats the contents of "{illumination}", which generally comes from an Astro::Coord::ECI::TLE "pass()" calculation, though it is also present if the template calls "data.bodies()".

If the satellite is above the horizon, the illumination returned by "bodies()" is the same as that provided by the pass calculation. Prior to version 0.019_01, nothing was returned if the satellite was below the horizon. Beginning with version 0.019_01, the satellite will be shown as either lit or shadowed if it is below the horizon.

In addition to the standard arguments, it takes the following:

units

This argument specifies the units of the field. Any event_pseudo_units units are accepted; anything else will result in an exception. The default is "localized".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 5.

inclination

 print $fmt->inclination();

This method formats the orbital inclination from the "{body}" object's TLE data.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 4.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "degrees".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 8.

inertial

 print $fmt->inertial()

This method formats the "inertial" attribute of the "{body}" object, as 0 if the attribute is false, or 1 if it is true.

In addition to the standard arguments, it takes the following:

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 1.

international

 print $fmt->international();

This method formats the international launch designator from the "{body}" object's TLE data.

In addition to the standard arguments, it takes the following:

units

This argument specifies the units of the field. Any string_pseudo_units units are accepted; anything else will result in an exception. The default is "string".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 8.

latitude

 print $fmt->latitude();

This method formats the latitude of the "{body}" object.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 4.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "degrees".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 8.

list

 print $fmt->list();

This method formats the object as specified by the "list_formatter" argument when the object was initialized. It has no arguments of its own, but will pass through any arguments given to the methods it calls. See local_coord() below for details.

local_coord

 print $fmt->local_coord();

This method formats the local coordinates as specified by the "local_coordinates" argument when the object was initialized. It has no arguments of its own, but will pass through any arguments given to the methods it calls. You can pass arguments selectively by specifying them as a hash - for example $fmt->local_coord( title => { azimuth => 'azimuth', elevation => 'elevation', }, );

Scalar arguments will be passed to all called methods, except for "append", which will be appended to the entire formatted value.

longitude

 print $fmt->longitude();

This method formats the longitude of the "{body}" object.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 4.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "degrees".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 9.

magnitude

 print $fmt->magnitude();

This method formats the contents of "{data}{magnitude}", which generally represents the magnitude of an Iridium flare. If "{magnitude}" is undefined but the body supports the "magnitude()" method, the body time is set to the contents of "{time}", and then "$body->magnitude( $station )" is called.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 1.

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 4.

maidenhead

 print $fmt->maidenhead();

This method formats the Maidenhead Grid Locator position of the "{body}" object.

In addition to the standard arguments, it takes the following:

places

This argument specifies the precision of the position, as the number of grid levels to provide. The default is half the width, truncated to an integer. If no specific width is provided, the default is 3.

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 6.

mean_anomaly

 print $fmt->mean_anomaly();

This method formats the mean anomaly from the "{body}" object's TLE data.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 4.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "degrees".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 9.

mean_motion

 print $fmt->mean_motion();

This method formats the mean motion from the "{body}" object's TLE data. The units are actually angle per minute, but this formatter treats them as angle. That is, it will give you output in radians per minute if you so desire, but not in radians per second.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 10.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "degrees".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 12.

mma

 print $fmt->mma();

This method formats the contents of "{mma}", which generally indicates the flaring antenna for an Iridium flare.

In addition to the standard arguments, it takes the following:

units

This argument specifies the units of the field. Any string_pseudo_units units are accepted; anything else will result in an exception. The default is "string".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 3.

name

 print $fmt->name();

This method formats the name of the "{body}" object. If the name is missing and you specify "missing => 'oid'" the OID will be displayed instead.

In addition to the standard arguments, it takes the following:

units

This argument specifies the units of the field. Any string_pseudo_units units are accepted; anything else will result in an exception. The default is "string".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 24.

oid

 print $fmt->oid();

This method formats the OID of the "{body}" object.

In addition to the standard arguments, it takes the following:

units

This argument specifies the units of the field. Any string_pseudo_units units are accepted; anything else will result in an exception. The default is "string".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 6.

operational

 print $fmt->operational();

This method formats the operational status of the "{body}" object. This is generally only available if the object represents an Iridium satellite.

In addition to the standard arguments, it takes the following:

units

This argument specifies the units of the field. Any string_pseudo_units units are accepted; anything else will result in an exception. The default is "string".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 1.

periapsis

 print $fmt->periapsis();

This method formats the periapsis of the "{body}" object's orbit.

In addition to the standard arguments, it takes the following:

as_altitude

If this boolean argument is true (in the Perl sense) the value is given as altitude above the Earth's surface. If false, the value is given as distance from the Earth's center. The default is 1.

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 0.

units

This argument specifies the units of the field. Any length units are accepted; anything else will result in an exception. The default is "kilometers".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 6.

perigee

 print $fmt->perigee();

This method formats the perigee of the "{body}" object's orbit. Yes, this is the same as the periapsis.

In addition to the standard arguments, it takes the following:

as_altitude

If this boolean argument is true (in the Perl sense) the value is given as altitude above the Earth's surface. If false, the value is given as distance from the Earth's center. The default is 1.

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 0.

units

This argument specifies the units of the field. Any length units are accepted; anything else will result in an exception. The default is "kilometers".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 6.

period

 print $fmt->period();

This method formats the period of the "{body}" object's orbit.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 0.

units

This argument specifies the units of the field. Any duration units are accepted; anything else will result in an exception. The default is "composite".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 12.

phase

 print $fmt->phase();

This method formats the phase of the "{body}" object. This is only available if that object supports the "phase()" method.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 0.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "degrees".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 4.

range

 print $fmt->range();

This method formats the distance of the "{body}" object from the "{station}" object.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 1.

units

This argument specifies the units of the field. Any length units are accepted; anything else will result in an exception. The default is "kilometers".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 10.

revolutions_at_epoch

 print $fmt->revolutions_at_epoch();

This method formats the revolutions at epoch from the "{body}" object's TLE data.

In addition to the standard arguments, it takes the following:

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 6.

right_ascension

 print $fmt->right_ascension();

This method formats the right ascension of the "{body}" object as seen from the "{station}" object.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 0.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "right_ascension".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 8.

second_derivative

 print $fmt->second_derivative();

This method formats the second derivative from the "{body}" object's TLE data. The units are actually angle per minute cubed, but this formatter treats them as angle. That is, it will give you output in radians per minute cubed if you so desire, but not in radians per second cubed.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 10.

units

This argument specifies the units of the field. Any angle_units units are accepted; anything else will result in an exception. The default is "degrees".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 17.

semimajor

 print $fmt->semimajor();

This method formats the semimajor axis of the "{body}" object's orbit, calculated using that object's "semimajor()" method.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 0.

units

This argument specifies the units of the field. Any length units are accepted; anything else will result in an exception. The default is "kilometers".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 6.

semiminor

 print $fmt->semiminor();

This method formats the semiminor axis of the "{body}" object's orbit, calculated using that object's "semiminor()" method.

In addition to the standard arguments, it takes the following:

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 0.

units

This argument specifies the units of the field. Any length units are accepted; anything else will result in an exception. The default is "kilometers".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 6.

status

 print $fmt->status();

This method formats the contents of "{status}", which usually come from the Astro::App::Satpass2 "position()" method.

In addition to the standard arguments, it takes the following:

units

This argument specifies the units of the field. Any string_pseudo_units units are accepted; anything else will result in an exception. The default is "string".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 60.

time

 print $fmt->time();

This method formats the "{time}" value using the "time_format" template. This is intended to produce the time, without date information.

In addition to the standard arguments, it takes the following:

delta

This argument specifies a number of seconds to add to the value before it is formatted. The default is 0.

format

This argument specifies the format to use for formatting the value. The default is ...

gmt

If this boolean argument is true, the value is formatted in GMT, regardless of how the time formatter is set up. If false, it is formatted according to the "time_formatter"'s zone setting. The default is the "time_formatter"'s "gmt" setting.

places

This argument specifies the number of decimal places in the field. Specify a non-numeric value if you do not wish to enforce a specific number of decimal places. The default is 5.

units

This argument specifies the units of the field. Any time_units units are accepted; anything else will result in an exception. The default is "local".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is "".

tle

 print $fmt->tle();

This method formats the TLE data from the "{body}" object. Unlike the other formatters, which produce a fixed-width string, this formatter produces a block of text, whatever is contained by the "{body}" object's "tle" attribute if any.

type

 print $fmt->type();

This method formats the contents of "{type}". This usually comes from the "flare()" method, and says whether the flare occurred in the am, day, or pm.

In addition to the standard arguments, it takes the following:

units

This argument specifies the units of the field. Any string_pseudo_units units are accepted; anything else will result in an exception. The default is "string".

width

This argument specifies the width of the field. Specify a non-numeric value if you do not wish to enforce a specific width. The default is 3.

Title Control

Nothing special needs to be done to get the first line, other than to initialize the object "title => 1". To get all the lines, you need to use a "while" loop, calling "more_title_lines()" in the test. When this returns false you must exit the loop, otherwise you loop infinitely.

is_valid_title_gravity

Returns a true value if the argument is a valid title gravity setting, and a false value otherwise. Can be called as a static method, or even a subroutine, though it is not exported.

more_title_lines

 my $fmt = Astro::App::Satpass2::Format->new( title => 1 );
 while ( $fmt->more_title_lines() ) {
     print join( ' ',
         $fmt->azimuth( title => 'Azimuth of object',
             bearing => 2 ),
         $fmt->elevation( title => 'Elevation of object' ),
     ), "\n";
 }

This method returns true until there are no more lines of title to display. It also increments the internal line counter causing the next line of title to be displayed.

reset_title_lines

 my $fmt->reset_title_lines();

This method resets the title line logic to its original state. You will not normally need to call this unless you want to display titles more than once and you have previously exited a "more_title_lines()" loop prematurely.

Adding format effectors

 $fmt->add_formatter_method( ... );

This experimental method takes as its arguments one or more Astro::App::Satpass2::FormatValue::Formatter objects, and makes them available for use in formatting values. An exception will be thrown if you try to replace an existing formatter, whether it is built-in or previously added with this method.

It is not anticipated that the user will need to call this directly. Instead the formatter object will call it on the user's behalf.

The whole idea of custom format effectors is highly experimental, and should be considered undocumented and subject to change without notice.

almanac_pseudo_units

"description" = the text description of the event;

"event" = the generic name of the event (e.g. 'horizon' for rise or set);

"detail" = the numeric event detail, whose meaning depends on the event (e.g. for 'horizon', 1 is rise and 0 is set).

The default is 'description'.

angle_units

"bearing" = a compass bearing;

"decimal" = a synonym for "degrees";

"degrees" = angle in decimal degrees;

"radians" = angle in radians;

"phase" = name of phase ('new', 'waxing crescent', and so on);

"right_ascension" = angle in hours, minutes, and seconds of right ascension.

When the angle units are specified as "units => 'bearing'", the precision of the bearing is specified by the "bearing" argument. That is, "bearing => 1" gets you the cardinal points ("N", "E", "S" and "W"), "bearing => 2" gets you the semi-cardinal points, and similarly for "bearing => 3". If "bearing" is not specified it defaults to the same value as the "width" argument, or 2 if no width is specified. The net result is that you need to specify the "bearing" argument if you specify "width => ''" and do not like the default of 2. Yes, I could have equivocated on "places", but this seemed more straight forward.

The default is normally degrees, though this is overridden for right_ascension.

dimensionless

"percent" = display as a percentage value, without the trailing '%';

"unity" = display unaltered.

The default is "unity".

duration

"composite" = days hours:minutes:seconds.fraction;

"days" = duration in days and fractions of days;

"hours" = duration in hours and fractions of hours;

"minutes" = duration in minutes and fractions of minutes;

"seconds" = duration in seconds and fractions of seconds.

The default is "composite".

event_pseudo_units

"integer" = event number (see Astro::Coord::ECI::TLE);

"localized" = localized event name;

"string" = unlocalized event name.

The default is "localized".

length

"feet" = US/British feet;

"ft" = synonym for 'feet';

"kilometers" = standard kilometers;

"km" = synonym for kilometers;

"meters" = standard meters;

"m" = synonym for 'meters';

"miles" = statute miles.

The default is "kilometers".

string_pseudo_units

"lower_case" = all lower case;

"string" = the unmodified string;

"title_case" = lower case, with initial letters upper case,

"upper_case" = all upper case.

time_units

"days_since_epoch" = the number of days and fractions thereof since the epoch of the body (undefined if there is no epoch);

"gmt" = GMT;

"julian" = Julian day (implies GMT -- you may want to set the "places" argument for this);

"local" = local time (actually, whatever zone the time formatter is set to);

"universal" = an alias for "gmt";

"z" = an alias for "gmt";

"zulu" = an alias for "gmt".

The default is "local".