lib/Stem/Id.pm

   1 #  File: Stem/Id.pm
   2
   3 #  This file is part of Stem.
   4 #  Copyright (C) 1999, 2000, 2001 Stem Systems, Inc.
   5
   6 #  Stem is free software; you can redistribute it and/or modify
   7 #  it under the terms of the GNU General Public License as published by
   8 #  the Free Software Foundation; either version 2 of the License, or
   9 #  (at your option) any later version.
  10
  11 #  Stem is distributed in the hope that it will be useful,
  12 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 #  GNU General Public License for more details.
  15
  16 #  You should have received a copy of the GNU General Public License
  17 #  along with Stem; if not, write to the Free Software
  18 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  19
  20 #  For a license to use the Stem under conditions other than those
  21 #  described here, to purchase support for this software, or to purchase a
  22 #  commercial warranty contract, please contact Stem Systems at:
  23
  24 #       Stem Systems, Inc.              781-643-7504
  25 #       79 Everett St.                  info@stemsystems.com
  26 #       Arlington, MA 02474
  27 #       USA
  28
  29 package Stem::Id ;
  30
  31 use strict ;
  32
  33 =pod
  34
  35 This module generates unique Id strings for use as names in Stem
  36 addresses. Its most common use is by parent Cells which clone
  37 themselves and need a unique Target. The parent Cell uses its Cell
  38 name and the new Target to register the cloned Cell.
  39
  40 =cut
  41
  42 my $attr_spec = [
  43
  44         {
  45                 'name'          => 'size',
  46                 'default'       => 6,
  47                 'help'          => <<HELP,
  48 This sets the number of characters in the Id.  It defaults to 6.
  49 HELP
  50         },
  51
  52 ] ;
  53
  54
  55 ###########
  56 # This POD section is autoegenerated. Any edits to it will be lost.
  57
  58 =head2 Constructor Attributes for Class Stem::Id
  59
  60 =over 4
  61
  62
  63 =item * Attribute - B<size>
  64
  65 =over 4
  66
  67
  68 =item Description:
  69 This sets the number of characters in the Id.  It defaults to 6.
  70
  71
  72 =item It B<defaults> to: 6
  73
  74 =back
  75
  76 =back
  77
  78 =cut
  79
  80 # End of autogenerated POD
  81 ###########
  82
  83
  84
  85 =head2 new
  86
  87 The new method constructs a Stem::Id object. It initializes the Id
  88 string to a string of 'a's. The string size determines how long this
  89 object can go before it has to reuse previously deleted Id strings.
  90
  91 =cut
  92
  93 sub new {
  94
  95         my( $class ) = shift ;
  96
  97         my $self = Stem::Class::parse_args( $attr_spec, @_ ) ;
  98         return $self unless ref $self ;
  99
 100         my $size = $self->{'size'} ;
 101
 102         $self->{'start'}  = 'a' x $size ;
 103         $self->{'next'}   = 'a' x $size ;
 104         $self->{'end'}    = 'a' x ( $size + 1 ) ;
 105         $self->{'in_use'} = {} ;
 106
 107         return $self ;
 108 }
 109
 110 =head2 next
 111
 112 The next method returns the next available Id in the object and marks
 113 that as in use.  It fails if all possible Id's are in use.
 114
 115 =cut
 116
 117 sub next {
 118
 119         my( $self ) = @_ ;
 120
 121         my $next = $self->{'next'} ;
 122         my $curr_next = $next ;
 123         my $end = $self->{'end'} ;
 124         my $in_use = $self->{'in_use'} ;
 125
 126         while( exists( $in_use->{$next} ) ) {
 127
 128                 $next++ ;
 129
 130 # fail if we looped around.
 131
 132 #print "curr $curr_next $next\n" ;
 133
 134                 return if $next eq $curr_next ;
 135
 136                 $next = $self->{'start'} if $next eq $end ;
 137         }
 138
 139         $in_use->{$next} = 1 ;
 140         $self->{'next'} = $next ;
 141
 142         return $next ;
 143 }
 144
 145 =head2 delete
 146
 147 The delete method allows this Id to be reused by a call to the next
 148 method.
 149
 150 =cut
 151
 152 sub delete {
 153
 154         my( $self, $id ) = @_ ;
 155
 156         delete $self->{'in_use'}{ $id } ;
 157 }
 158
 159 =head2 dump
 160
 161 The dump method returns a the list of Ids that are in use.  used. It
 162 either returns the list of keys or an anonymous array with them
 163 depending on the calling context.
 164
 165 =cut
 166
 167 sub dump {
 168
 169         my( $self ) = @_ ;
 170
 171         return( wantarray ? keys %{ $self->{'in_use'} } :
 172                           [ keys %{ $self->{'in_use'} } ] ) ;
 173 }
 174
 175 1 ;