Astro::FITS::Header - Object Orientated interface to FITS HDUs

  $header = new Astro::FITS::Header( Cards => \@array );

Stores information about a FITS header block in an object. Takes an hash with an array reference as an arguement. The array should contain a list of FITS header cards as input.

$Id: Header.pm,v 1.26 2003/10/23 03:28:28 bradc Exp $

new

Create a new instance from an array of FITS header cards.

  $item = new Astro::FITS::Header( Cards => \@header );

returns a reference to a Header object. If you pass in no cards, you get the (required) first SIMPLE card for free.

tieRetRef

Indicates whether the tied object should return multiple values as a single string joined by newline characters (false) or it should return a reference to an array containing all the values. Only affects the tied interface.

  tie %keywords, "Astro::FITS::Header", $header, tiereturnsref => 1;
  $ref = $keywords{COMMENT};

Defaults to returning a single string in all cases (for backwards compatibility)

subhdrs

Set or return the subheaders for a Header object

    $header->subhdrs(@hdrs);
    @hdrs = $header->subhdrs;

item

Returns a FITS::Header:Item object referenced by index, CWundef if it does not exist.

   $item = $header->item($index);

keyword

Returns keyword referenced by index, CWundef if it does not exist.

   $keyword = $header->keyword($index);

itembyname

Returns an array of Header::Items for the requested keyword if called in list context, or the first matching Header::Item if called in scalar context. Returns CWundef if the keyword does not exist. The keyword may be a regular expression created with the CWqr operator.

   @items = $header->itembyname($keyword);
   $item = $header->itembyname($keyword);

index

Returns an array of indices for the requested keyword if called in list context, or an empty array if it does not exist. The keyword may be a regular expression created with the CWqr operator.

   @index = $header->index($keyword);

If called in scalar context it returns the first item in the array, or CWundef if the keyword does not exist.

   $index = $header->index($keyword);

value

Returns an array of values for the requested keyword if called in list context, or an empty array if it does not exist. The keyword may be a regular expression created with the CWqr operator.

   @value = $header->value($keyword);

If called in scalar context it returns the first item in the array, or CWundef if the keyword does not exist.

comment

Returns an array of comments for the requested keyword if called in list context, or an empty array if it does not exist. The keyword may be a regular expression created with the CWqr operator.

   @comment = $header->comment($keyword);

If called in scalar context it returns the first item in the array, or CWundef if the keyword does not exist.

   $comment = $header->comment($keyword);

insert

Inserts a FITS header card object at position CW$index

   $header->insert($index, $item);

the object CW$item is not copied, multiple inserts of the same object mean that future modifications to the one instance of the inserted object will modify all inserted copies.

replace

Replace FITS header card at index CW$index with card CW$item

   $card = $header->replace($index, $item);

returns the replaced card.

remove

Removes a FITS header card object at position CW$index

   $card = $header->remove($index);

returns the removed card.

replacebyname

Replace FITS header cards with keyword CW$keyword with card CW$item

   $card = $header->replacebyname($keyword, $item);

returns the replaced card. The keyword may be a regular expression created with the CWqr operator.

removebyname

Removes a FITS header card object by name

  @card = $header->removebyname($keyword);

returns the removed cards. The keyword may be a regular expression created with the CWqr operator.

splice

Implements a standard splice operation for FITS headers

   @cards = $header->splice($offset [,$length [, @list]]);
   $last_card = $header->splice($offset [,$length [, @list]]);

Removes the FITS header cards from the header designated by CW$offset and CW$length, and replaces them with CW@list (if specified) which must be an array of FITS::Header::Item objects. Returns the cards removed. If offset is negative, counts from the end of the FITS header.

cards

Return the object contents as an array of FITS cards.

  @array = $header->cards;

allitems

Returns the header as an array of FITS::Header:Item objects.

   @items = $header->allitems();

configure

Configures the object, takes an array of FITS header cards or an array of Astro::FITS::Header::Item objects as input. If you feed in nothing at all, it uses a default array containing just the SIMPLE card required at the top of all FITS files.

  $header->configure( Cards => \@array );
  $header->configure( Items => \@array );

Does nothing if the array is not supplied.

These operators are overloaded: When the object is used in a string context the FITS header block is returned as a single string.

These methods are for internal use only.

_rebuild_lookup

Private function used to rebuild the lookup table after modifying the header block, its easier to do it this way than go through and add one to the indices of all header cards following the modifed card.

The CWFITS::Header object can also be tied to a hash:

   use Astro::FITS::Header;

   $header = new Astro::FITS::Header( Cards => \@array );
   tie %hash, "Astro::FITS::Header", $header

   $value = $hash{$keyword};
   $hash{$keyword} = $value;

   print "keyword $keyword is present" if exists $hash{$keyword};

   foreach my $key (keys %hash) {
      print "$key = $hash{$key}\n";
   }

Header value type is determined on-the-fly by parsing of the input values. Anything that parses as a number or a logical is converted to that before being put in a card (but see below).

Per-card comment fields can be accessed using the tied interface by specifying a key name of key_COMMENT. This works because in general _COMMENT is too long to be confused with a normal key name.

  $comment = $hdr{CRPIX1_COMMENT};

will return the comment associated with CRPIX1 header item. The comment can be modified in the same way:

  $hdr{CRPIX1_COMMENT} = "An axis";

You can also modify the comment by slash-delimiting it when setting the associated keyword:

  $hdr{CRPIX1} = "34 / Set this field manually";

If you want an actual slash character in your string field you must escape it with a backslash. (If you're in double quotes you have to use a double backslash):

  $hdr{SLASHSTR} = 'foo\/bar / field contains "foo/bar"';

Keywords are CaSE-inNSEnSiTIvE, unlike normal hash keywords. All keywords are translated to upper case internally, per the FITS standard.

Aside from the SIMPLE and END keywords, which are automagically placed at the beginning and end of the header respectively, keywords are included in the header in the order received. This gives you a modicum of control over card order, but if you actually care what order they're in, you probably don't want the tied interface.

Comment cards are a special case because they have no normal value and their comment field is treated as the hash value. The keywords COMMENT and HISTORY are magic and refer to comment cards; nearly all other keywords create normal valued cards. (see SIMPLE and END cards, below).

Multiline string values are broken up, one card per line in the string. Extra-long string values are handled gracefully: they get split among multiple cards, with a backslash at the end of each card image. They're transparently reassembled when you access the data, so that there is a strong analogy between multiline string values and multiple cards.

In general, appending to hash entries that look like strings does what you think it should. In particular, comment cards have a newline appended automatically on FETCH, so that

  $hash{HISTORY} .= "Added multi-line string support";

adds a new HISTORY comment card, while

  $hash{TELESCOP} .= " dome B";

only modifies an existing TELESCOP card.

You can make multi-line values by feeding in newline-delimited strings, or by assigning from an array ref. If you ask for a tag that has a multiline value it's always expanded to a multiline string, even if you fed in an array ref to start with. That's by design: multiline string expansion often acts as though you are getting just the first value back out, because perl string-to-number conversion stops at the first newline. So:

  $hash{CDELT1} = [3,4,5];
  print $hash{CDELT1} + 99,"\n$hash{CDELT1}";

prints 102\n3\n4\n5, and then

  $hash{CDELT1}++;
  print $hash{CDELT1};

prints 4.

In short, most of the time you get what you want. But you can always fall back on the non-tied interface by calling methods like so:

  ((tied $hash)->method())

If you prefer to have multi-valued items automagically become array refs, then you can get that behavior using the CWtiereturnsref method:

  tie %keywords, "Astro::FITS::Header", $header, tiereturnsref => 1;

When tiereturnsref is true, multi-valued items will be returned via a reference to an array (ties do not respect calling context). Note that if this is configured you will have to test each return value to see whether it is returning a real value or a reference to an array if you are not sure whether there will be more than one card with a duplicate name.

Because perl uses behind-the-scenes typing, there is an ambiguity between strings and numeric and/or logical values: sometimes you want to create a STRING card whose value could parse as a number or as a logical value, and perl kindly parses it into a number for you. To force string evaluation, feed in a trivial array ref:

  $hash{NUMSTR} = 123;     # generates an INT card containing 123.
  $hash{NUMSTR} = "123";   # generates an INT card containing 123.
  $hash{NUMSTR} = ["123"]; # generates a STRING card containing "123".
  $hash{NUMSTR} = [123];   # generates a STRING card containing "123".

  $hash{ALPHA} = "T";      # generates a LOGICAL card containing T. 
  $hash{ALPHA} = ["T"];    # generates a STRING card containing "T".

Calls to keys() or each() will, by default, return the keywords in the order n which they appear in the header.

When the key refers to a subheader entry, a hash reference is returned. If a hash reference is stored in a value it is converted to a CWAstro::FITS::Header object.

No FITS interface would becomplete without special cases.

When you assign to SIMPLE or END, the tied interface ensures that they are first or last, respectively, in the deck as the FITS standard requires. Other cards are inserted in between the first and last elements, in the order that you define them.

The SIMPLE card is forced to FITS LOGICAL (boolean) type. The FITS standard forbids you from setting it to F, but you can if you want we're not the FITS police.

The END card is forced to a null type, so any value you assign to it will fall on the floor. If present in the deck, the END keyword always contains the value , which is both more-or-less invisible when printed and also true so you can test the return value to see if an END card is present.

SIMPLE and END come pre-defined from the constructor. If for some nefarious reason you want to remove them you must explicitly do so with delete or the appropriate method call from the object interface.

Copyright (C) 2001-2002 Particle Physics and Astronomy Research Council and portions Copyright (C) 2002 Southwest Research Institute. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Alasdair Allan <aa@astro.ex.ac.uk>, Tim Jenness <t.jenness@jach.hawaii.edu>, Craig DeForest <deforest@boulder.swri.edu>, Jim Lewis <jrl@ast.cam.ac.uk>