Commit | Line | Data |
4536f655 |
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 ; |