#---------------------------------------------------------------------#
# This source code is (c)1999 Dave Belfer-Shevett - shevett@pobox.com #
# see http://www.stonekeep.com/license.html for licensing information #
#---------------------------------------------------------------------#

# ----------------------------------------------------------------------
#  Written by David H. Silber for Stonekeep Consulting.
#  david@SilberSoft.com -- http://www.SilberSoft.com/
# ----------------------------------------------------------------------

# ----------------------------------------------------------------------
#  Status.pm
#  $Id:
# ----------------------------------------------------------------------

# ----------------------------------------------------------------------
package Status;

# ----------------------------------------------------------------------
#  To keep me honest.
use strict;


=head1 NAME

Status - The Keystone database C<status> table

=head1 SYNOPSIS 

	require Status;

	expand Status ( $flag );

=head1 DESCRIPTION

Status provides expanded status labels to replace single-letter status flags.

=head1 METHODS

=cut # +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

=head2 expand() -- Turn the one-letter status code into a full word.

Get the full name of a status from the database.

Return the label that matches the flag.
Selects from the status table, based on the flag value.

=over 4

=item Use:

  require Status;

  $label = expand Status ( $initial );

=item Parameters:

=over 4

=item initial

The flag letter for a status.

=back

=item Returns:

The full name of the status, or an empty string.

=back

=cut # +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

sub expand {
  my $package = shift;   #  Package name.
  my ($initial) = @_;    #  Status code.

  $main::debug && print STDERR "Entering " . $package . "::expand().\n";


  my $query;   #  SQL command to check if user is a registered Keystone
               #  user.
  my $sth;     #  Statement handle.

  $main::debug && print "Status code: " . $initial .  ".\n";

  #  Build a query to see if $main::username is listed in the status
  #  table.
  $query = "SELECT label FROM status WHERE flag = '" . $initial .  "'";

  #  Query the database.
  $sth = $main::keystone->{dbh}->prepare( $query );
  $sth->execute() || die "execute('$query'): $DBI::errstr";

  #  This really is only going to fetch a single row.
  my $arrayref = $sth->fetchrow_arrayref;


  $main::debug && print STDERR "Returning from " . $package .
      "::expand().  " .  "Status label: " . @$arrayref[0] . ".\n";

  return @$arrayref[0];
}

1;

__END__

=head1 CAVEATS

This currently does a SELECT for each usage.
It would probably be more efficient to grab the whole B<status> table
into a hash and then access the hash on subsequent calls.
This can be addresses later, if speed becomes an issue.

=head1 BUGS

=head1 AUTHOR

David H. Silber
of Silber Software Engineering
F<E<lt>david@SilberSoft.comE<gt>>
wrote this for StoneKeep Consulting
as part of the B<keycli> development effort.

=head1 SEE ALSO

L<Keystone>

=cut
