# File: Stem/Id.pm
# This file is part of Stem.
# Copyright (C) 1999, 2000, 2001 Stem Systems, Inc.
# Stem 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; either version 2 of the License, or
# (at your option) any later version.
# Stem is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with Stem; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
# For a license to use the Stem under conditions other than those
# described here, to purchase support for this software, or to purchase a
# commercial warranty contract, please contact Stem Systems at:
# Stem Systems, Inc. 781-643-7504
# 79 Everett St. info@stemsystems.com
# Arlington, MA 02474
# USA
package Stem::Id ;
use strict ;
=pod
This module generates unique Id strings for use as names in Stem
addresses. Its most common use is by parent Cells which clone
themselves and need a unique Target. The parent Cell uses its Cell
name and the new Target to register the cloned Cell.
=cut
my $attr_spec = [
{
'name' => 'size',
'default' => 6,
'help' => <<HELP,
This sets the number of characters in the Id. It defaults to 6.
HELP
},
] ;
###########
# This POD section is autoegenerated. Any edits to it will be lost.
=head2 Constructor Attributes for Class Stem::Id
=over 4
=item * Attribute - B<size>
=over 4
=item Description:
This sets the number of characters in the Id. It defaults to 6.
=item It B<defaults> to: 6
=back
=back
=cut
# End of autogenerated POD
###########
=head2 new
The new method constructs a Stem::Id object. It initializes the Id
string to a string of 'a's. The string size determines how long this
object can go before it has to reuse previously deleted Id strings.
=cut
sub new {
my( $class ) = shift ;
my $self = Stem::Class::parse_args( $attr_spec, @_ ) ;
return $self unless ref $self ;
my $size = $self->{'size'} ;
$self->{'start'} = 'a' x $size ;
$self->{'next'} = 'a' x $size ;
$self->{'end'} = 'a' x ( $size + 1 ) ;
$self->{'in_use'} = {} ;
return $self ;
}
=head2 next
The next method returns the next available Id in the object and marks
that as in use. It fails if all possible Id's are in use.
=cut
sub next {
my( $self ) = @_ ;
my $next = $self->{'next'} ;
my $curr_next = $next ;
my $end = $self->{'end'} ;
my $in_use = $self->{'in_use'} ;
while( exists( $in_use->{$next} ) ) {
$next++ ;
# fail if we looped around.
#print "curr $curr_next $next\n" ;
return if $next eq $curr_next ;
$next = $self->{'start'} if $next eq $end ;
}
$in_use->{$next} = 1 ;
$self->{'next'} = $next ;
return $next ;
}
=head2 delete
The delete method allows this Id to be reused by a call to the next
method.
=cut
sub delete {
my( $self, $id ) = @_ ;
delete $self->{'in_use'}{ $id } ;
}
=head2 dump
The dump method returns a the list of Ids that are in use. used. It
either returns the list of keys or an anonymous array with them
depending on the calling context.
=cut
sub dump {
my( $self ) = @_ ;
return( wantarray ? keys %{ $self->{'in_use'} } :
[ keys %{ $self->{'in_use'} } ] ) ;
}
1 ;