######################## GFF.pm #################################
# Copyright (c) 1999  Richard Bruskiewich (rbsk@sanger.ac.uk)
# Sanger Centre, Wellcome Trust Genome Campus, Cambs, UK
# 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
#
# Name: GFF.pm
#
# Function: a perl library of utility functions 
#           for the GFF module objects
#
# History:
#  24/11/99  - rbsk: see GeneFeatureSet.pm and GifGFF.pm
#   4/10/99  - rbsk: see GeneFeatureSet.pm and GeneFeature.pm
#    8/9/99  - rbsk: GeneFeature.pm valueless [group] tag value fix
#   27/08/99 - rbsk: GeneFeature.pm parse_group bug fix
#   26/08/99: - rbsk: GeneFeature.pm changes...
#   28/1/99 - rbsk: added new() method...
#                   module renamed from GFFObject.pm => GFF.pm
#                   overall GFF object module hierarchy remolded
#                      GFF.pm              => GFF::GeneFeatureSet.pm
#                      GeneFeature.pm      => GFF::GeneFeature.pm
#                      HomolGeneFeature.pm => GFF::HomolGeneFeature.pm
#                   all in GFF subdirectory
#   22/4/99 - rbsk: $TRACE, trace() and verify() added
#   Created: 16/3/99
#
####################################################################

package  GFF;
use Carp;
use strict;
use vars qw($AUTOLOAD @ISA @EXPORT @EXPORT_OK $VERSION $TRACE);
require Exporter;
#
# @ISA has our inheritance.
#
@ISA = qw( Exporter );
#
# Place functions/variables you want to *export*, ie be visible from the caller package into @EXPORT_OK
#
@EXPORT    = qw();
@EXPORT_OK = qw();

$VERSION = '2.13' ;

my %fields = (
              version  => undef, 
	      seqname  => undef, 
);

my $GFF_VERSION = '2.06' ; # rbsk: 2/99 GFF Version 2 in use, new default value for global flag control
 
sub new {
    my $ref     = shift ;
    my $class   = ref($ref) || $ref ;
    my $version = shift ;
    my $seqname = shift ;

    my $self = { '_permitted' => \%fields } ;
    
    if( defined $seqname ) {
        $self->{'seqname'} = $seqname ;
    }
    bless $self, $class ;

    $self->{'version'} = $GFF_VERSION ;
    $self->version($version) ;

    return $self ;
}

#
# Autoload up my field name set/get
#
sub AUTOLOAD {
    my $self = shift;
    my $class = ref($self) || carp "\'$self\' is not an object of mine!";
    my $name = $AUTOLOAD;

    # don't propagate DESTROY messages...

    $name =~ /::DESTROY/ && return;

    $name =~ s/.*://; #get only the bit we want
    unless (exists $self->{'_permitted'}->{$name} ) {
	confess "In type $class, can't access $name - probably passed a wrong variable into Sequence  ";
    }
    if (@_) {
	return $self->{$name} = shift;
    } else {
	return $self->{$name}
    }
}

my $TRACE = 0 ; # user can reset this...

sub trace { my $state = shift ; $TRACE = (defined $state and $state)? $state : 0 ; }

sub TRACE {
    my $level = shift ; 
    if($TRACE >= $level) {
	if( $level == 1 ) { # level 1 is a simple trace mode
	    print STDERR @_  ;
	} else {
	    carp @_ ;
	}
    }
}

sub verify {
    my $self  = shift ;
    my $class = ref($self) || $self ;
    $class = '(GFF|GFF::GeneFeatureSet|GFF::GeneFeature|GFF::HomolGeneFeature)' if $class eq 'GFF' ;
    my $ref   = shift ;

    my $nodie = shift ;
    $nodie = 0 if !defined($nodie) ;

    if(!defined $ref) {
        if($nodie) {
	    carp "verify(): undefined object!" ;
	    return 0 ;
	} else {
	    croak "verify(): undefined object!"  ;
        }
    } elsif(!ref($ref)) {
        if($nodie) {
	    carp "verify(): not a reference!" ;
	    return 0 ;
	} else {
            croak "verify(): not a reference!" ;
        }
    } elsif( ref($ref) !~ /$class/ ) {
        if($nodie) {
	    carp "verify(): ".ref($ref)." is not a $class class object!"  ;
	    return 0 ;
	} else {
            croak "verify(): ".ref($ref)." is not a $class class object!"  ;
        }
    }

    TRACE(2,"$class\:\:verify($ref) OK!\n") ;
    return 1 ;
}

#
# Maintains GFF version in GFF module associated objects
#
sub version  {
    my $self     = shift ;
    my $version  = shift ;

    $version = 0 if !defined($version) ;

    if( ref($self) and GFF->verify($self) ) { 
        # invoked by a GFF object, as an instance method
       if( $version and $version =~/^(\d+)$/  ) { 
            $self->{'version'} = $1 + 0 ; # reset the GFF object version
        } else {
            TRACE(2,ref($self)."->version() $version undefined or invalid: just returning existing object version...\n") ;
        }
        return $self->{'version'} ;
    } else { 
        # invoked as a class method!
        if( defined $version and $version =~/^(\d+)$/  ) { # can reset the default version
           $GFF_VERSION = $1 + 0 ; 
           TRACE(2,"GFF package default version reset to $GFF_VERSION\n") ;
        } else {
            TRACE(2,"Class GFF->version() \$version undefined or invalid: just returning \$GFF_VERSION\n") ;
        }
       return $GFF_VERSION ;
    }
}

use lib 'GFF' ;			
use GFF::GeneFeature ;
use GFF::HomolGeneFeature ;
use GFF::GeneFeatureSet ;
## dgg here
##use GFF::Analysis;

1; # required for GFF

__END__

=head1 NAME

GFF - Perl extension for Gene Finding Feature format

=head1 AUTHORS

Richard Bruskiewich - email B<rbsk@sanger.ac.uk>

Tim Hubbard - email B<th@sanger.ac.uk>

=head1 SYNOPSIS

    use GFF;

=head1 DESCRIPTION

GFF is a Perl Object base class/module for the Gene Finding Feature format.
A GFF object is a base class for GeneFeatureSet, GFF::GeneFeature and
GFF::HomolGeneFeature objects.

B<How to Read Method Protocols>

Normal Perl data type notations are used for argument declarations in
the method protocols. A backslash denotes argument passing by
reference. Arguments shown in italics are optional parameters to the
method calls. Class methods are invoked using the
'class->method(args)' or 'method class args' Perl call formats.

=head1 SOURCE CODE

The most current release of the Perl source code for this module is
available. All bug reports may be submitted to Richard
Bruskiewich (rbsk@sanger.ac.uk). Future releases will likely be
issued as Bioperl archived modules.

=head1 GFF Class Methods and Variables

=over 4

=item version( $version )

This method may actually be called as a class (static) method or
as a virtual (instance) method. When called as a class method,
the method sets and/or queries the package default GFF protocol
version. GFF objects internally record the current default
version value when they are created. If the method is called by
such a derived object, it sets and/or queries the GFF object's
version (thus, one can in principle create and manipulated GFF
objects of various versions). If not otherwise called, the
module currently assumes that Version 2 GFF objects will be
manipulated. If the format of the anticipated input is not the
default protocol version, then this method must be called first,
prior to calling other format sensitive methods, to set the
correct version. The method may be called with or without an
argument. In both cases, the method returns the current (or
newly set) version value, either the package ("class") default
or the GFF object value.

=item verify( $ref, $nodie )

Any derived class can invoke this method, to verify that $ref is
a properly defined object reference in that class. If invoked by
the GFF class, then verifies that the $ref belongs to any one of
the GFF derived classes. Method 'dies' upon failure, unless the 
$nodie variable is non-null (default: null), in which case, the
function merely carps a warning and returns null for failure.

=item trace( $level )

Setting $level to a number greater than 1 triggers a verbose GFF.pm et al.
module diagnostic mode output to STDERR. If $level argument is
omitted, then the trace is turned off. Examples: verify()
(above) reports success; GFF::read() provides user feedback
during file input. Generally speaking, the verbosity of the output
depends upon the $level given: 1 = minimum trace (most useful for
monitoring certain iterative operations like reading in a file),
2 = verbose (debug) trace (not so useful except for GFF.pm coders)

=back

=head1 GFF Construction Methods

Not applicable; derived classes instantiate this class.

=head1 GFF Object Input/Output Methods

Not applicable; derived classes instantiate this class.

=head1 Revision History

2.12    10/11/99 - rbsk: see GeneFeatureSet.pm, GifGFF.pm and Graph.pm
2.11     4/10/99 - rbsk: see GeneFeatureSet.pm and GeneFeature.pm
2.10    27/08/99 - rbsk: GeneFeature parse_group bug fix
2.09    26/08/99 - rbsk: GeneFeature.pm changes...
2.08     28/1/99 - rbsk: module renamed from GFFObject.pm => GFF.pm
                     overall GFF object module hierarchy remolded
                      GFF.pm              => GFF::GeneFeatureSet.pm
                      GeneFeature.pm      => GFF::GeneFeature.pm
                      HomolGeneFeature.pm => GFF::HomolGeneFeature.pm
                   all in GFF subdirectory
    22/4/99 - rbsk: added trace(), verify() and trace() methods
    16/3/99 - rbsk: created this class to abstract "version" method
                   from GFF, GeneFeature and HomolGeneFeature.


=head1 SEE ALSO

http://www.sanger.ac.uk/Software/GFF/GeneFeature.shtml,
http://www.sanger.ac.uk/Software/GFF/GeneFeatureSet.shtml
http://www.sanger.ac.uk/Software/GFF/HomolGeneFeature.shtml,
http://www.sanger.ac.uk/Software/GFF/GifGFF.shtml
http://www.sanger.ac.uk/Software/GFF/Analysis.shtml

=cut