$catalog = new Astro::Catalog(Stars  => \@array);
    $catalog = new Astro::Catalog(Format => 'Cluster', File => $file_name);
    $catalog = new Astro::Catalog(Format => 'JCMT', Data => $scalar);
    

returns a reference to an "Astro::Catalog" object. See the "configure" method for a list of allowed arguments.

    $catalog->write_catalog(
        File => $file_name, Format => $file_type, [%opts])
    or die $catalog->errstr;
    

returns true on sucess and false if the write failed (the reason can be obtained using the "errstr" method). The %opts are optional arguments and are dependent on the output format chosen. Current valid output formats are 'Simple', 'Cluster', 'JCMT' and 'VOTable'.

The File argument can refer to a file name on disk (simple scalar), a glob (eg \*STDOUT), an IO::Handle object (for example something returned by the File::Temp constructor) a reference to a scalar (\$content) or reference to an array. For the last two options, the contents of the catalogue file are stored in the scalar or in the array (a line per array entry with no new lines).

    $catalog->origin('JCMT');
    $origin = $catalog->origin();
    

    my $type = $catalog->preferred_magnitude_type;
    $catalog->preferred_magnitude_type('MAG_ISO');
    

    $num = $catalog->sizeof();
    

    $catalog->pushstar(@stars);
    

returns the number of stars now in the Catalog object (even if no arguments were supplied). The method guarantees that the stars are pushed onto the internal original list and the filtered/sorted version.

Currently no check is made to make sure that the star is already on one of the two lists.

    $star = $catalog->popstar();
    

the method deletes the star and returns the deleted "Astro::Catalog::Item" object.

    @stars = $catalog->popstarbyid( $id );
    

The method deletes the stars and returns the deleted "Astro::Catalog::Item" objects. If no star exists with the given ID, the method returns an empty list.

If called in scalar context this method returns an array reference, and if called in list context returns an array of "Astro::Catalog::Item" objects.

This is effectively an inverse filter (see "filter_by_id" for complementary method).

    @allstars = $catalog->allstars();
    $ref = $catalog->allstars();
    

In list context returns all the stars, in scalar context returns a reference to the internal array. This allows the primary array to be modified in place so use this with care.

Addendum: This is pretty much for internal use only, but if you do this

    $catalog->allstars(@stars);
    

you repalce the stars array with the array passed. Don't do this, it's bad!

    @stars = $catalog->stars();
    

in list context the copy of the array is returned, while in scalar context a reference to the array is return. In scalar context, the referenced array will always be that of the current list of valid stars. If the current list is empty the primary list will be copied into the current array so that it can be modified independently of the original list. This may cost you a lot of memory. Note that changes to the array ordering or content may be lost in this case whenever the "reset_list" method is used.

    $star = $catalog->starbyindex($index);
    

the first star is at index 0 (not 1). Returns undef if no arguments are provided.

    $catalog->fieldcentre(
        RA     => $ra,
        Dec    => $dec,
        Radius => $radius,
        Coords => new Astro::Coords());
    

RA and Dec must be given together or as Coords. Coords (an Astro::Coords object) supercedes RA/Dec.

    $catalog->set_radius($radius);
    

    $catalog->set_coords($c);
    

    $c = $catalog->get_coords();
    

    $ra = $catalog->get_ra();
    

    $dec = $catalog->get_dec();
    

    $radius = $catalog->get_radius();
    

    $ref = $catalog->reference;
    $catalog->reference($c);
    

If a reference position is not specified explicitly the field centre will be used instead (if defined).

    $reftime = $src->reftime();

    $src->reftime($newtime);
    

Time must be a "Time::Piece" object. This is only really important for moving objects such as planets or asteroids or for occasions when you are calcualting azimuth or elevation.

    $fielddate = $src->fielddate;

    $src->fielddate($date);
    

Date must be a "Time::Piece" object. This defaults to the current time when the "Astro::Catalog" object was instantiated.

Default is false.

    $newcat = $catalog->configure(%options);
    

Takes a hash as argument with the list of keywords. Supported options are:

    Format => Format of supplied catalog
    File => File name for catalog on disk. Not used if 'Data' supplied.
    Data => Contents of catalogue, either as a scalar variable,
            reference to array of lines or reference to glob (file handle).
            This key is used in preference to 'File' if both are present

    Stars => Array of Astro::Catalog::Item objects. Supercedes all other options.
    ReadOpt => Reference to hash of options to be forwarded onto the
               format specific catalogue reader. See the IO documentation
               for details.
    

If Format is supplied without any other options, a default file is requested from the class implementing the formatted read. If no default file is forthcoming the method croaks.

If no options are specified the method does nothing, assumes you will be supplying stars at a later time.

The options are case-insensitive.

Note that in some cases (when reading a catalogue) this method will act as a constructor. In any case, always returns a catalog object (either the same one that went in or a modified one).

API uncertainty - in principal Data is not needed since File could be overloaded (in a similar way to write_catalog).

    $catalog->reset_list();
    

If "auto_filter_observability" is true, the list will be immediately filtered for observability.

    $catalog->force_ref_time();
    

After this, the times in the coordinate objects will be set and will no longer reflect current time (if they had it originally).

    $catalog->calc_xy($frameset);
    

The supplied argument must be a Starlink::AST::FrameSet.

    @new = $catalog->filter_by_observability();
    

Returns the newly selected stars (as if the "stars" method was called immediately, unless called in a non-list context.

    @stars = $catalog->filter_by_id("IRAS");
    

Would result in a catalog with all the stars with "IRAS" in their name. This is just a convenient alternative to "filter_by_cb" and is equivalent to

    @stars = $catalog->filter_by_cb(sub {$_[0]->id =~ /IRAS/i;});
    

A regular expression can be supplied explicitly using qr//:

    @stars = $catalog->filter_by_id(qr/^IRAS/i);
    

See "popstarbyid" for a similar method that returns stars that are an exact match to ID and removes them from the current list.

    @selected = $catalog->filter_by_distance( $radius, $refpos );
    

The radius is in radians. The reference position defaults to the value returned by the "reference" method if none supplied.

API uncertainty:

    - Should the radius default to the get_radius() method?
    - Should this method take hash arguments?
    - Should there be a units argument? (radians, arcmin, arcsec, degrees)
    

    @selected = $catalog->filter_by_cb(sub {$_[0]->id == "HLTau"});
    @selected = $catalog->filter_by_cb(sub {$_[0]->id =~ /^IRAS/;});
    

    $catalog->sort_catalog($mode);
    

where mode can be one of

    "unsorted"
    "id"
    "ra"
    "dec"
    "az"
    "el"
    

and

    "distance"
    "distance_az"
    

if a reference position is available. "az" and "el" require that the star coordinates have an associated telescope and that the reference time is correct.

If mode is a code reference, that will be passed to the sort routine directly. Note that the callback must expect $a and $b to be set.

The method "force_ref_time" is invoked prior to sorting unless the mode is "id". "name" is a synonym for "id".

Currently the "unsorted" option simply forces a "reset_list" since there is currently no tracking of the applied filters. It should be possible to step through the original list and the current filtered list and end up with a filtered but unsorted list. This is not implemented.

Pre-canned sorts are optimized because the values are precalculated prior to doing the sort rather than calculated each time through the sort.