Astro:...r::Item(3pm)

🎀 Astro::FITS::Header::Item — the manual page, but make it cute 🎀

okay bestie, listen. this is a page from the User Contributed Perl Documentation for Astro::FITS::Header::Item(3pm). yes the manual name is doing the most with those dots, we love her anyway. let's get into it 💅

---

✨ NAME ✨

Astro::FITS::Header::Item — literally just a card image from a FITS header. that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

here's the group chat version of how you talk to her:

  $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";

look at that. building her from a card, building her from pieces, asking her things, and even just stringifying her with "$item". main character energy fr fr ✨

---

💖 DESCRIPTION 💖

So. This module stores all the info about a FITS header item — and in the FITS standard those are officially called Card Images, no cap. FITS Card Images can be parsed and broken down into their component keyword, values and comments. And also — plot twist — Card Images can be created from those same components: keyword, value and comment. it's giving reversible jacket 🧥✨

---

👑 METHODS 👑

🍼 Constructor

• new — creates a new instance. Optionally you can hand her a hash containing info from a header item, or the card image itself. so generous of you.

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

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

The full list of allowed hash keys is documented down in the configure method, go read her. 📖

Returns undef if the info you supplied was insufficient to generate a valid header item. like girl, you didn't give me enough to work with 😭

• copy — makes a copy of an Astro::FITS::Header::Item object. twin moment 🫶

  $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 💀 (she's not going to hold onto stale data, that's embarrassing).

Supplied value is always upper-cased. always. no exceptions, bestie. 🔠

• 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 again. same energy.

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

• 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. (yes, every single time. the cache is not safe here. 🙈)

• 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. that's the whole roster, periodt.

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. iykyk 🌈

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. she'll make one, don't worry.

  $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. bye felicia 👋

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. she's the queen of the group chat 👑

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. 😬 (not me trusting the guess… bestie, verify.)

Does nothing if these keys are not supplied. (she's not going to invent work for herself.)

• freeze — method to return a blessed reference to the object so that we can store ths object on disk using the Data::Dumper module. popsicle-coded 🍧
• 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. no drama, just emptiness 💀

• equals — compares this Item with another and returns true if the keyword, value, type and comment are all equal. all four or it's a no from me.

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

---

🦋 SEE ALSO 🦋

"Astro::FITS::Header" — go say hi, she's the main one 💖

---

📜 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

real talk bestie, that "WITHOUT ANY WARRANTY" part is in ALL CAPS for a reason. no promises, no take-backsies. 🚨

---

🫶 AUTHORS 🫶

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

---

okay and that's the whole page!! she was documented as perl v5.36.0, dated 2023-04-21, and filed under Astro:...r::Item(3pm) in the User Contributed Perl Documentation. love that for her. go forth and parse some cards, bestie 💖✨🎀