NAME

       Astro::FITS::Header::Item - A card image from a FITS header

SYNOPSIS

         $item = new Astro::FITS::Header::Item( Card => $card );

         $item = new Astro::FITS::Header::Item( Keyword => $keyword,
                                                Value => $value,
                                                Comment => $comment,
                                                Type => 'int'
                                              );

         $value = $item->value();
         $comment = $item->comment();

         $card = $item->card();

         $card = "$item";

DESCRIPTION

       Stores information about a FITS header item (in the FITS standard these are called Card
       Images). FITS 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.

METHODS

   Constructor
       new Create a new instance. Optionally can be given a hash containing information from a
           header item or the card image itself.

             $item = new Astro::FITS::Header::Item( Card => $card );

             $item = new Astro::FITS::Header::Item( Keyword => $keyword,
                                                    Value => $value );

           The list of allowed hash keys is documented in the configure method.

           Returns "undef" if the information supplied was insufficient to generate a valid
           header item.

       copy
           Make a copy of an Astro::FITS::Header::Item object.

             $newitem = $item->copy;

   Accessor Methods
       keyword
           Return (or set) the value of the keyword associated with the FITS card.

             $keyword = $item->keyword();
             $item->keyword( $key );

           When a new value is supplied any "card" in the cache is invalidated.

           Supplied value is always upper-cased.

       value
           Return (or set) the value of the value associated with the FITS card.

             $value = $item->value();
             $item->value( $val );

           When a new value is supplied any "card" in the cache is invalidated.

           If the value is an "Astro::FITS::Header" object, the type is automatically set to
           "HEADER".

       comment
           Return (or set) the value of the comment associated with the FITS card.

             $comment = $item->comment();
             $item->comment( $comment );

           When a new value is supplied any "card" in the cache is invalidated.

       type
           Return (or set) the value of the variable type associated with the FITS card.

             $type = $item->type();
             $item->type( "INT" );

           Allowed types are "LOGICAL", "INT", "FLOAT", "STRING", "COMMENT", "HEADER" and
           "UNDEF".

           The special type, "HEADER", is used to specify that this item refers to a subsidiary
           header (eg a header in an MEFITS file or a header in an NDF in an HDS container). See
           also the "subhdrs" method in "Astro::FITS::Header" for an alternative way of
           specifying a sub-header.

           The type is case-insensitive, but will always be returned up-cased.

       card
           Return (or set) the 80 character header card associated with this object.  It is
           created if there is no cached version.

             $card = $item->card();

           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 "undef"
           on assignment failure (else returns the supplied string).

             $status = $item->card( $card );

           "undef" is returned if there is insufficient information in the object to create a new
           card. Can assign "undef" to clear the cache.

           This method is called automatically when attempting to stringify the object.

            $card = "$item";

   General Methods
       configure
           Configures the object from multiple pieces of information.

             $item->configure( %options );

           Takes a hash as argument with the following keywords:

           Card    If supplied, the value is assumed to be a standard 80 character FITS header
                   card. This is sent to the "parse_card" method directly.  Takes priority over
                   any other key.

                   If it is an "Astro::FITS::Header::Item" it will be copied rather than parsed.

           Keyword Used to specify the keyword associated with this object.

           Value   Used to specify the value associated with this FITS item.

           Comment Used to specify the comment associated with this FITS item.

           Type    Used to specify the variable type. See the "type" method for more details. A
                   type will be guessed if one is not supplied.  The guess may well be wrong.

           Does nothing if these keys are not supplied.

       freeze
           Method to return a blessed reference to the object so that we can store ths object on
           disk using Data::Dumper module.

       parse_card
           Parse a FITS card image and store the keyword, value and comment into the object.

             ($key, $val, $com) = $item->parse_card( $card );

           Returns an empty list on error.

       equals
           Compares this Item with another and returns true if the keyword, value, type and
           comment are all equal.

             $isident = $item->equals( $item2 );

SEE ALSO

       "Astro::FITS::Header"

COPYRIGHT

       Copyright (C) 2008-2009 Science and Technology Facilities Council.  Copyright (C)
       2001-2007 Particle Physics and Astronomy Research Council.  All Rights Reserved.

       This program is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation; either
       version 3 of the License, or (at your option) any later version.

       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.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program;
       if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA
       02111-1307, USA

AUTHORS

       Tim Jenness <t.jenness@jach.hawaii.edu>, Alasdair Allan <aa@astro.ex.ac.uk>