.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Astro::FITS::Header::Item 3pm"
.TH Astro::FITS::Header::Item 3pm "2021-01-06" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Astro::FITS::Header::Item \- A card image from a FITS header
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  $item = new Astro::FITS::Header::Item( Card => $card );
\&
\&  $item = new Astro::FITS::Header::Item( Keyword => $keyword,
\&                                         Value => $value,
\&                                         Comment => $comment,
\&                                         Type => \*(Aqint\*(Aq
\&                                       );
\&
\&  $value = $item\->value();
\&  $comment = $item\->comment();
\&
\&  $card = $item\->card();
\&
\&  $card = "$item";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Stores information about a \s-1FITS\s0 header item (in the \s-1FITS\s0 standard these
are called \fBCard Images\fR). \s-1FITS\s0 Card Images can be parsed and broken
into their component keyword, values and comments. Card Images can also
be created from its components keyword, value and comment.
.SH "METHODS"
.IX Header "METHODS"
.SS "Constructor"
.IX Subsection "Constructor"
.IP "\fBnew\fR" 4
.IX Item "new"
Create a new instance. Optionally can be given a hash containing
information from a header item or the card image itself.
.Sp
.Vb 1
\&  $item = new Astro::FITS::Header::Item( Card => $card );
\&
\&  $item = new Astro::FITS::Header::Item( Keyword => $keyword,
\&                                         Value => $value );
.Ve
.Sp
The list of allowed hash keys is documented in the
\&\fBconfigure\fR method.
.Sp
Returns \f(CW\*(C`undef\*(C'\fR if the information supplied was insufficient
to generate a valid header item.
.IP "\fBcopy\fR" 4
.IX Item "copy"
Make a copy of an Astro::FITS::Header::Item object.
.Sp
.Vb 1
\&  $newitem = $item\->copy;
.Ve
.SS "Accessor Methods"
.IX Subsection "Accessor Methods"
.IP "\fBkeyword\fR" 4
.IX Item "keyword"
Return (or set) the value of the keyword associated with
the \s-1FITS\s0 card.
.Sp
.Vb 2
\&  $keyword = $item\->keyword();
\&  $item\->keyword( $key );
.Ve
.Sp
When a new value is supplied any \f(CW\*(C`card\*(C'\fR in the cache is invalidated.
.Sp
Supplied value is always upper-cased.
.IP "\fBvalue\fR" 4
.IX Item "value"
Return (or set) the value of the value associated with
the \s-1FITS\s0 card.
.Sp
.Vb 2
\&  $value = $item\->value();
\&  $item\->value( $val );
.Ve
.Sp
When a new value is supplied any \f(CW\*(C`card\*(C'\fR in the cache is invalidated.
.Sp
If the value is an \f(CW\*(C`Astro::FITS::Header\*(C'\fR object, the type is automatically
set to \*(L"\s-1HEADER\*(R".\s0
.IP "\fBcomment\fR" 4
.IX Item "comment"
Return (or set) the value of the comment associated with
the \s-1FITS\s0 card.
.Sp
.Vb 2
\&  $comment = $item\->comment();
\&  $item\->comment( $comment );
.Ve
.Sp
When a new value is supplied any \f(CW\*(C`card\*(C'\fR in the cache is invalidated.
.IP "\fBtype\fR" 4
.IX Item "type"
Return (or set) the value of the variable type associated with
the \s-1FITS\s0 card.
.Sp
.Vb 2
\&  $type = $item\->type();
\&  $item\->type( "INT" );
.Ve
.Sp
Allowed types are \*(L"\s-1LOGICAL\*(R", \*(L"INT\*(R", \*(L"FLOAT\*(R", \*(L"STRING\*(R", \*(L"COMMENT\*(R",
\&\*(L"HEADER\*(R"\s0 and \*(L"\s-1UNDEF\*(R".\s0
.Sp
The special type, \*(L"\s-1HEADER\*(R",\s0 is used to specify that this item refers to
a subsidiary header (eg a header in an \s-1MEFITS\s0 file or a header in an
\&\s-1NDF\s0 in an \s-1HDS\s0 container). See also the \f(CW\*(C`subhdrs\*(C'\fR method in
\&\f(CW\*(C`Astro::FITS::Header\*(C'\fR for an alternative way of specifying a
sub-header.
.Sp
The type is case-insensitive, but will always be returned up-cased.
.IP "\fBcard\fR" 4
.IX Item "card"
Return (or set) the 80 character header card associated with this
object.  It is created if there is no cached version.
.Sp
.Vb 1
\&  $card = $item\->card();
.Ve
.Sp
If a new card is supplied it will only be accepted if it is 80
characters long or fewer.  The string is padded with spaces if it is too
short. No attempt (yet) )is made to shorten the string if it is too
long since that may require a check to see if the value is a string
that must be shortened with a closing single quote.  Returns \f(CW\*(C`undef\*(C'\fR
on assignment failure (else returns the supplied string).
.Sp
.Vb 1
\&  $status = $item\->card( $card );
.Ve
.Sp
\&\f(CW\*(C`undef\*(C'\fR is returned if there is insufficient information in the object
to create a new card. Can assign \f(CW\*(C`undef\*(C'\fR to clear the cache.
.Sp
This method is called automatically when attempting to stringify
the object.
.Sp
.Vb 1
\& $card = "$item";
.Ve
.SS "General Methods"
.IX Subsection "General Methods"
.IP "\fBconfigure\fR" 4
.IX Item "configure"
Configures the object from multiple pieces of information.
.Sp
.Vb 1
\&  $item\->configure( %options );
.Ve
.Sp
Takes a hash as argument with the following keywords:
.RS 4
.IP "\fBCard\fR" 8
.IX Item "Card"
If supplied, the value is assumed to be a standard 80 character
\&\s-1FITS\s0 header card. This is sent to the \f(CW\*(C`parse_card\*(C'\fR method directly.
Takes priority over any other key.
.Sp
If it is an \f(CW\*(C`Astro::FITS::Header::Item\*(C'\fR it will be copied rather
than parsed.
.IP "\fBKeyword\fR" 8
.IX Item "Keyword"
Used to specify the keyword associated with this object.
.IP "\fBValue\fR" 8
.IX Item "Value"
Used to specify the value associated with this \s-1FITS\s0 item.
.IP "\fBComment\fR" 8
.IX Item "Comment"
Used to specify the comment associated with this \s-1FITS\s0 item.
.IP "\fBType\fR" 8
.IX Item "Type"
Used to specify the variable type. See the \f(CW\*(C`type\*(C'\fR method
for more details. A type will be guessed if one is not supplied.
The guess may well be wrong.
.RE
.RS 4
.Sp
Does nothing if these keys are not supplied.
.RE
.IP "\fBfreeze\fR" 4
.IX Item "freeze"
Method to return a blessed reference to the object so that we can store
ths object on disk using Data::Dumper module.
.IP "\fBparse_card\fR" 4
.IX Item "parse_card"
Parse a \s-1FITS\s0 card image and store the keyword, value and comment
into the object.
.Sp
.Vb 1
\&  ($key, $val, $com) = $item\->parse_card( $card );
.Ve
.Sp
Returns an empty list on error.
.IP "\fBequals\fR" 4
.IX Item "equals"
Compares this Item with another and returns true if the keyword,
value, type and comment are all equal.
.Sp
.Vb 1
\&  $isident = $item\->equals( $item2 );
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\f(CW\*(C`Astro::FITS::Header\*(C'\fR
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2008\-2009 Science and Technology Facilities Council.
Copyright (C) 2001\-2007 Particle Physics and Astronomy Research Council.
All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify it under
the terms of the \s-1GNU\s0 General Public License as published by the Free Software
Foundation; either version 3 of the License, or (at your option) any later
version.
.PP
This program is distributed in the hope that it will be useful,but \s-1WITHOUT ANY
WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A
PARTICULAR PURPOSE.\s0 See the \s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place,Suite 330, Boston, \s-1MA\s0  02111\-1307, \s-1USA\s0
.SH "AUTHORS"
.IX Header "AUTHORS"
Tim Jenness <t.jenness@jach.hawaii.edu>,
Alasdair Allan <aa@astro.ex.ac.uk>