use Bio::OntologyIO;

  # do not use directly -- use via Bio::OntologyIO
  my $parser = Bio::OntologyIO->new
	( -format        => "simplehierarchy",
	  -file          => "pathology_terms.csv",
	  -indent_string => ",",
	  -ontology_name => "eVOC",
	  -term_factory  => $fact,
	);

  my $ontology = $parser->next_ontology();

    my ($self, @args) = @_;
    $self->SUPER::_initialize( @args );

    my ( $indent,$files,$fileisroot,$name,$eng ) =
	$self->_rearrange([qw(INDENT_STRING 
			      FILES
			      FILE_IS_ROOT
			      ONTOLOGY_NAME
			      ENGINE)
			   ], @args);

    $self->_done( FALSE );
    $self->_not_first_record( FALSE );
    $self->_term( "" );
    $self->file_is_root($fileisroot) if defined($fileisroot);
    $self->indent_string($indent || ' '); #reasonable default?
    delete $self->{'_ontologies'};

    # ontology engine (and possibly name if it's an OntologyI)
    $eng = Bio::Ontology::SimpleGOEngine->new() unless $eng;
    if($eng->isa("Bio::Ontology::OntologyI")) {
	$self->ontology_name($eng->name());
	$eng = $eng->engine() if $eng->can('engine');
    }
    $self->_ont_engine($eng);

    # flat files to parse
    $self->{_flat_files} = $files ? ref($files) ? $files : [$files] : [];

    # ontology name (overrides implicit one through OntologyI engine)
    $self->ontology_name($name) if $name;

} # _initialize

    my $self = shift;

    return $self->{'ontology_name'} = shift if @_;
    return $self->{'ontology_name'};

    my $self = shift;
    
    # setup the default term factory if not done by anyone yet
    $self->term_factory(Bio::Ontology::TermFactory->new(
					     -type => "Bio::Ontology::Term"))
	unless $self->term_factory();

    # create the ontology object itself
    my $ont = Bio::Ontology::Ontology->new(-name => $self->ontology_name(),
					   -engine => $self->_ont_engine());

    # set up the ontology of the relationship types
    foreach ($self->_part_of_relationship(), $self->_is_a_relationship()) {
	$_->ontology($ont);
    }

    # pre-seed the IO system with the first flat file if -file wasn't provided
    if(! $self->_fh) {
	$self->_initialize_io(-file => shift(@{$self->_flat_files()}));
    }

    while($self->_fh) {
	  $self->_parse_flat_file($ont);
	  # advance to next flat file if more are available
	  if(@{$self->_flat_files()}) {
	    $self->close();
	    # reset the virtual root so that the next one if generated from
	    # the next file
	    $self->_virtual_root(undef);
	    # now re-initialize the IO object
	    $self->_initialize_io(-file => shift(@{$self->_flat_files()}));
	  } else {
	    last; # nothing else to parse so terminate the loop
	  }
    }
    $self->_add_ontology($ont);
    # not needed anywhere, only because of backward compatibility
    return $self->_ont_engine();
} # parse

    my $self = shift;

    # parse if not done already
    $self->parse() unless exists($self->{'_ontologies'});
    # return next available ontology
    return shift(@{$self->{'_ontologies'}}) if exists($self->{'_ontologies'});
    return undef;

    my $self = shift;

    $self->{_flat_files} = [] unless exists($self->{_flat_files});
    return $self->{_flat_files};

    my $self = shift;

    return $self->{'_defs_io'} = shift if @_;
    return $self->{'_defs_io'};

    my $self = shift;
    $self->{'_ontologies'} = [] unless exists($self->{'_ontologies'});
    foreach my $ont (@_) {
	$self->throw(ref($ont)." does not implement Bio::Ontology::OntologyI")
	    unless ref($ont) && $ont->isa("Bio::Ontology::OntologyI");
	push(@{$self->{'_ontologies'}}, $ont);
    }

    my ( $self, $term, $ont ) = @_;

    $term->ontology($ont) if $ont && (! $term->ontology);
    $self->_ont_engine()->add_term( $term );


} # _add_term

    my ( $self, $term ) = @_;

    $self->{ "_part_of_relationship" } ||= Bio::Ontology::RelationshipType->get_instance( 'PART_OF' );
	return $self->{ "_part_of_relationship" };
#    return $self->_ont_engine()->part_of_relationship();


} # _part_of_relationship 

    my ( $self, $term ) = @_;

    $self->{ "_is_a_relationship" } ||= Bio::Ontology::RelationshipType->get_instance( 'IS_A' );
	return $self->{ "_is_a_relationship" };
#    return $self->_ont_engine()->is_a_relationship();


} # _is_a_relationship 

    my ( $self, $parent, $child, $type, $ont ) = @_;

    # note the triple terminology (subject,predicate,object) corresponds to
    # (child,type,parent)
    $self->_ont_engine()->add_relationship( $child, $type, $parent, $ont );


} # _add_relationship

    my ( $self, $term ) = @_;

    $term = $self->ontology_name() .'|'. $term
	unless ref($term) || !$self->ontology_name();
    return $self->_ont_engine()->has_term( $term );

} # _add_term

    my $self = shift;
    my @args = ();
    
    while(@_) {
	unshift(@args, pop(@_)); # this actually does preserve the order
	$args[0] = $self->ontology_name() .'|'. $args[0]
	    unless ref($args[0]) || !$self->ontology_name();
    }
    return $self->_ont_engine->get_terms(@args);

  my $self = shift;
  my $ont  = shift;

  my @stack       = ();
  my $prev_indent = -1;
  my $parent      = "";
  my $prev_term   = "";

  my $indent_string = $self->indent_string;


  while ( my $line = $self->_readline() ) {
	if ( $line =~ /^[$indent_string]*[\|\-]/ ) { #this is not yet generalized
	  next;
	}

	my($current_term) = $line =~ /^[$indent_string]*(.*)/;
	my $current_indent = $self->_count_indents( $line );
	chomp $current_term;
	# remove extraneous delimiter characters at the end of the name if any
	$current_term =~ s/[$indent_string]+$//;
	# also, the name might contain a synonym
	my $syn = $current_term =~ s/\s+{([^}]+)}// ? $1 : undef;

 	if ( ! $self->_has_term( $current_term ) ) {
 	  my $term = $self->_create_ont_entry($current_term);
	  # add synonym(s) if any
	  $term->add_synonym(split(/;\s*/,$syn)) if $syn;
	  # add to the machine
 	  $self->_add_term( $term, $ont );

	  #go on to the next term if a root node.
	  if($current_indent == 0) {
	      # add the virtual root as parent if there is one
	      if($self->_virtual_root()) {
		  $self->_add_relationship($self->_virtual_root(),
					   $term,
					   $self->_is_a_relationship(),
					   $ont);
	      }
	      $prev_indent = $current_indent;
	      $prev_term = $current_term;
	      push @stack, $current_term;
	      next;
	  }
 	}

 	my $curr_term_obj = $self->_get_terms( $current_term );
 	#$current_term_object->ontology( $ont );

	#we are ensured to see the parent first in this type of file.
	#if ( ! $self->_has_term( $parent ) ) {
	#  my $term = $self->_create_ont_entry( $parent );
	#  $self->_add_term( $term, $ont );
	#}
	
 	if ( $current_indent != $prev_indent  ) {
 	  if ( $current_indent == $prev_indent + 1 ) {
 		push( @stack, $prev_term );
 	  } elsif ( $current_indent < $prev_indent ) {
 		my $n = $prev_indent -  $current_indent;
 		for ( my $i = 0; $i < $n; ++$i ) {
 		  pop( @stack );
 		}
 	  } else {
 		$self->throw( "format error (file ".$self->file.")" );
 	  }
 	}

 	$parent = $stack[-1];

	if($parent ne $current_term) { #this prevents infinite recursion from a parent linking to itself
	  $self->_add_relationship($self->_get_terms($parent),
				   $self->_get_terms($current_term),
				   $self->_is_a_relationship(),
				   $ont);
	}

	$prev_indent = $current_indent;
	$prev_term   = $current_term;
  } 
  return $ont;
} # _parse_relationships_file

    my ( $self, $line ) = @_;
    
    if ( $line =~ /;\s*([A-Z]{1,8}:\d{7})/ ) {
        return $1;
    }
    else {
        $self->throw( "format error: no term id in line\" $line\"" );
    }
    
} # _get_first_termid

  my ( $self, $line ) = @_;

  my $indent = $self->indent_string;

  if ( $line =~ /^($indent+)/ ) {
	return (length($1)/length($indent));
  }
  else {
	return 0;
  }
} # _count_indents

    my ( $self, $value ) = @_;

    if ( defined $value ) {
        $self->{ "_ont_engine" } = $value;
    }
    
    return $self->{ "_ont_engine" };
} # _ont_engine

    my ( $self, $name, $termid ) = @_;

    my $term = $self->term_factory->create_object(-name => $name,
						  -identifier => $termid);

    return $term;

} # _create_ont_entry

    my ( $self, $value ) = @_;

    if ( defined $value ) {
        unless ( $value == FALSE || $value == TRUE ) {
            $self->throw( "Argument to method\" _not_first_record\" must be either ".TRUE." or ".FALSE );
        }
        $self->{ "_not_first_record" } = $value;
    }
    
    return $self->{ "_not_first_record" };
} # _not_first_record

    my ( $self, $value ) = @_;

    if ( defined $value ) {
        unless ( $value == FALSE || $value == TRUE ) {
            $self->throw( "Found [$value] where [" . TRUE
            ." or " . FALSE . "] expected" );
        }
        $self->{ "_done" } = $value;
    }
    
    return $self->{ "_done" };
} # _done

    my ( $self, $value ) = @_;

    if ( defined $value ) {
        $self->{ "_term" } = $value;
    }

    return $self->{ "_term" };
} # _term

    my $self = shift;

    return $self->{'indent_string'} = shift if @_;
    return $self->{'indent_string'};

    my $self = shift;

    return $self->{'file_is_root'} = shift if @_;
    return $self->{'file_is_root'};

    my $self = shift;

    return $self->{'_virtual_root'} = shift if @_;

    # don't return anything if not in file_is_root mode, or if we don't
    # have a file to derive the root node from
    return undef unless $self->file_is_root() && $self->file();

    # construct it if we haven't done this before
    if(! $self->{'_virtual_root'}) {
	my ($rt,undef,undef) = fileparse($self->file(), '\..*');
	$rt =~ s/_/ /g;
	$rt = $self->_create_ont_entry($rt);
	$self->_add_term($rt, $self->ontology_name());
	$self->{'_virtual_root'} = $rt;
    }

    return $self->{'_virtual_root'};

  bioperl-l@bioperl.org                         - General discussion
  http://bio.perl.org/MailList.html             - About the mailing lists

  bioperl-bugs@bio.perl.org
  http://bugzilla.bioperl.org/

 Title   : new
 Usage   : see SYNOPSIS
 Function: Creates a new simplehierarchy parser.
 Returns : A new simplehierarchy parser object, implementing Bio::OntologyIO.
 Args    : -files         => a single ontology flat file holding the
                             term relationships, or an array ref holding
                             the file names
           -file          => if there is only a single flat file, it may
                             also be specified via the -file parameter
           -ontology_name => the name of the ontology, defaults to
                             "Gene Ontology"
           -file_is_root  => Boolean indicating whether a virtual root
                             term is to be added, the name of which will
                             be derived from the file name. Default is false.
                             Enabling this allows to parse multiple input
                             files into the same ontology and still have
                             separately rooted.
           -id_prefix     => The prefix for the term identifiers. Terms
                             in this format often come without identifiers,
                             in which case 
           -engine        => the Bio::Ontology::OntologyEngineI object
                             to be reused (will be created otherwise); note
                             that every Bio::Ontology::OntologyI will
                             qualify as well since that one inherits from the
                             former.
           -indent_string => the string used to indent hierarchical
                             levels in the file.

                             For a file like this:

                             term0
                               subterm1A
                                 subterm2A
                               subterm1B
                               subterm1C

                             indent_string would be "  ".  Defaults to
                             one space (" ").

           -comment_char  => Allows specification of a regular
                             expression string to indicate a comment line.
                             Currently defaults to "[\|\-]".
                             Note: this is not yet implemented.