NAME

Astro::FITS::CFITSIO::FileName - parse and generate CFITSIO extended file names.

VERSION

version 0.08

SYNOPSIS

  $fobj = Astro::FITS::CFITSIO::FileName->new( $filename );

  $attr = Astro::FITS::CFITSIO::FileName->parse_filename( $filename );

DESCRIPTION

CFITSIO packs a lot of functionality into a filename; it can include row and column filtering, binning and histogramming, image slicing, etc. It can be handy to manipulate the various parts that make up a fully specified CFITSIO filename.

Astro::FITS::CFITSIO::FileName slices and dices a CFITSIO extended filename into its constituent pieces. Or, given the constituent pieces, it can craft an extended CFITSIO filename.

Documentation for the CFITSIO extended filename syntax is available in Chapter 10 of

  https://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c_user/cfitsio.html

Warning!

This module does not actually parse row filters, so it's possible that it'll confuse an illegal component as one. For example, in this example, foo.fits[1:512], the illegal, partial image specification [1:512] will be identified as a row filter. Oops.

So many object attributes!

There are many attributes that an object might have; most are optional. Each optional attribute has a corresponding predicate method (has_XXX) which will return true if the attribute was set. For example, the pix_filter attribute is optional; to check if it was set, use the has_pix_filter method.

Manipulating a filename

Astro::FITS::CFITSIO::FileName objects are meant to be immutable, so manipulating attributes has to be done outside of the object.

One way is to call the "parse_filename" class method on the original filename. It returns a hash of attributes. Another is to call the "to_hash" object method, which returns a hash of attributes for a particular object. Both of these hashes may be fed into the class constructor.

OBJECT ATTRIBUTES

base_filename

The name of the file, without any trailing specifications (e.g. anything in square brackets or parenthesis) or a leading URI.

This attribute is always present.

file_type

The type of file. CFITSIO uses a URI style specification (e.g. mem://, http:// ).

This is optional. See "has_file_type"

output_name

An output or template name, depending upon the context that it's used with CFITSIO.

This is optional. See "has_output_name"

extname

The name of the HDU provided by the EXTNAME header keyword.

This is optional. See "has_extname"

extver

The version of the HDU specified by the "extname" attribute. "extname" must also be specified.

This is optional. See "has_extver".

xtension

The type of the HDU. It is case insensitive and may be one of

 A | ASCII |  I | IMAGE | T | TABLE | B | BINTABLE

This is optional. See "has_xtension"

image_cell_spec

Images can be stored in vector cells; this specifies which cell to access.

This is optional. See "has_image_cell_spec".

hdunum

The HDU index. 0 is the primary HDU. Do not use this with "extname".

This is optional. See "has_hdunum".

compress_spec

The image tile compression specification. The specification is not validated.

This is optional. See "has_compress_spec".

image_section

Returns an arrayref of two elements containing (as strings) the pixel ranges for the image axes.

This is optional. See "has_image_section".

pix_filter

A hashref containing the pixel filter.

The hash has the following entries:

datatype: Optional.
discard_hdus: Optional.
expr: The filter expression.

This is optional. See "has_pix_filter".

col_filter

Returns an array of column filters, as strings.

This is optional. See "has_col_filter".

row_filter

Returns an array of row filters, as strings.

This is optional. See "has_row_filter"

bin_spec

Returns an arrayref of hashrefs containing binning/histogram specifications.

The hashes have the following entries:

datatype: Optional.
expr: The binning expression.

This is optional. See "has_bin_spec".

filename

This returns the full CFITSIO filename based on all of the attributes.

CONSTRUCTORS

new

   $fileobj = Astro::FITS::CFITSIO::FileName->new( $filename );
   $fileobj = Astro::FITS::CFITSIO::FileName->new( \%args );
   $fileobj = Astro::FITS::CFITSIO::FileName->new( \%args );

In the first example, parse a fully specified CFITSIO filename and populate the attributes.

In the second example the following arguments are available.

base_filename Str

filename Str

One (and only one) of these is Required.

If base_filename is specified, it provides the value for the base_filename attribute.

If filename is provided, it is parsed using "parse_filename" and provides an initial set of attributes; additional attributes specified in the constructor will override them.

file_type Enum

Optional

One of the CFITSIO supported file types, as a string.

output_name Str

Optional

extname Str

Optional

Don't use this with the "hdunum" option.

extver PositiveInt

Optional

Don't use this with "hdunum". "extname" must also be set.

xtension Enum

Optional

The type of the HDU. It is case insensitive and may be one of

 A | ASCII |  I | IMAGE | T | TABLE | B | BINTABLE

image_cell_spec

Optional

Images can be stored in vector cells; this specifies which cell to access. Its value is not validated.

hdunum Positive Non Zero Integer

Optional

The HDU index. 0 is the primary HDU. Do not use this with "extname".

compress_spec

Optional

The image tile compression specification. Its value is not validated.

image_section

Optional

An array of two elements containing (as strings) the pixel ranges for the image axes.

pix_filter

Optional

A hashref containing the pixel filter. The hash has the following entries:

datatype: Optional
discard_hdus: Optional
expr: Required The filter expression.

col_filter

Optional

An array of column filters, as strings. Not validated.

row_filter

Optional

An array of row filters, as strings. Not validated.

bin_spec

Optional

An arrayref of hashrefs containing binning/histogram specifications.

The hashes have the following entries:

datatype: Optional.
expr: The binning expression.

clone_with

  $new = $old->clone_with( %attr | \%attr );

Create a new Astro::FITS::CFITSIO::FileName object based on an existing one with the specified modified attributes.

CLASS METHODS

parse_filename

  $attr = $class->parse_filename( $filename );

Parses an extended CFITSIO filename and returns a hash which may be fed into the Astro::FITS::CFITSIO::FileName constructor. Typically it's easier to just call the class constructor with the filename as a single argument.

If a subclass needs to amend the parsing, this is the method to override.

METHODS

has_file_type

returns true if the "file_type" attribute is present.

has_output_name

returns true if the "output_name" attribute is present.

has_extname

returns true if the "extname" attribute is present.

has_extver

returns true if the "extver" attribute is present.

has_xtension

returns true if the "xtension" attribute is present.

has_image_cell_spec

returns true if the "image_cell_spec" attribute is present.

has_hdunum

returns true if the "hdunum" attribute is present.

has_compress_spec

returns true if the "compress_spec" attribute is present.

has_image_section

returns true if the "image_section" attribute is present.

has_pix_filter

returns true if the "pix_filter" attribute is present.

has_col_filter

returns true if the "col_filter" attribute is present.

has_row_filter

returns true if the "row_filter" attribute is present.

has_bin_spec

returns true if the "bin_spec" attribute is present.

render_base_filename

render_file_type

render_output_name

render_compress_spec

render_hdu

render_image_section

render_pix_filter

render_col_filter

render_row_filter

render_bin_spec

return a string version of the attribute which can be concatenated to construct an extended syntax CFITSIO filename. For example,

  $self->render_hdu

might return

  [extname, 2]

is_compressed

  $bool = $file->is_compressed.

Returns true if the filename ends in .gz.

to_hash (deprecated)

TO_HASH

  $hash = $self->TO_HASH;

returns a hashref containing the object's attributes. This can be used to modify the attributes and then pass them to the class constructor to create a modified object.

OVERLOAD

""

Stringification is overloaded to return the filename as returned by the "filename" attribute.

INTERNALS

SUPPORT

Bugs

Please report any bugs or feature requests to bug-astro-fits-cfitsio-filename@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=Astro-FITS-CFITSIO-FileName

Source

Source is available at

  https://gitlab.com/djerius/astro-fits-cfitsio-filename

and may be cloned from

  https://gitlab.com/djerius/astro-fits-cfitsio-filename.git

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007

To install Astro::FITS::CFITSIO::FileName, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Astro::FITS::CFITSIO::FileName

CPAN shell

perl -MCPAN -e shell
install Astro::FITS::CFITSIO::FileName

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

Warning!

So many object attributes!

Manipulating a filename

OBJECT ATTRIBUTES

base_filename

file_type

output_name

extname

extver

xtension

image_cell_spec

hdunum

compress_spec

image_section

pix_filter

col_filter

row_filter

bin_spec

filename

CONSTRUCTORS

new

clone_with

CLASS METHODS

parse_filename

METHODS

has_file_type

has_output_name

has_extname

has_extver

has_xtension

has_image_cell_spec

has_hdunum

has_compress_spec

has_image_section

has_pix_filter

has_col_filter

has_row_filter

has_bin_spec

render_base_filename

render_file_type

render_output_name

render_compress_spec

render_hdu

render_image_section

render_pix_filter

render_col_filter

render_row_filter

render_bin_spec

is_compressed

to_hash (deprecated)

TO_HASH

OVERLOAD

""

INTERNALS

SUPPORT

Bugs

Source

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions