This file is indexed.

/usr/share/perl5/Stone/Cursor.pm is in libboulder-perl 1.30-4.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
# A simple iterator on a Stone.
package Stone::Cursor;

=head1 NAME

Stone::Cursor - Traverse tags and values of a Stone

=head1 SYNOPSIS

 use Boulder::Store;
$store = Boulder::Store->new('./soccer_teams');

 my $stone = $store->get(28);
 $cursor = $stone->cursor;
 while (my ($key,$value) = $cursor->each) {
   print "$value: Go Bluejays!\n" if $key eq 'State' and $value eq 'Katonah';
 }

=head1 DESCRIPTION

Boulder::Cursor is a utility class that allows you to create one or
more iterators across a L<Stone> object.  This is used for traversing
large Stone objects in order to identify or modify portions of the
record.

=head2 CLASS METHODS

=over 4

=item Boulder::Cursor->new($stone)

Return a new Boulder::Cursor over the specified L<Stone> object.  This
will return an error if the object is not a L<Stone> or a
descendent. This method is usually not called directly, but rather
indirectly via the L<Stone> cursor() method:

  my $cursor = $stone->cursor;

=back

=head2 OBJECT METHODS

=over 4

=item $cursor->each() 

Iterate over the attached B<Stone>.  Each iteration will return a
two-valued list consisting of a tag path and a value.  The tag path is
of a form that can be used with B<Stone::index()> (in fact, a cursor
is used internally to implement the B<Stone::dump()> method.  When the
end of the B<Stone> is reached, C<each()> will return an empty list,
after which it will start over again from the beginning.  If you
attempt to insert or delete from the stone while iterating over it,
all attached cursors will reset to the beginnning.

For example:

	$cursor = $s->cursor;
	while (($key,$value) = $cursor->each) {
           print "$value: BOW WOW!\n" if $key=~/pet/;		
	}

=item $cursor->reset()

This resets the cursor back to the beginning of the associated
B<Stone>.

=back

=head1 AUTHOR

Lincoln D. Stein <lstein@cshl.org>.

=head1 COPYRIGHT

Copyright 1997-1999, Cold Spring Harbor Laboratory, Cold Spring Harbor
NY.  This module can be used and distributed on the same terms as Perl
itself.

=head1 SEE ALSO

L<Boulder>, L<Stone>

=cut


#------------------- Boulder::Cursor---------------


*next_pair = \&each;

# New expects a Stone object as its single
# parameter.
sub new {
    my($package,$stone) = @_;
    die "Boulder::Cursor: expect a Stone object parameter"
	unless ref($stone);

    my $self = bless {'stone'=>$stone},$package;
    $self->reset;
    $stone->_register_cursor($self,'true');
    return $self;
}

# This procedure does a breadth-first search
# over the entire structure.  It returns an array that looks like this
# (key1[index1].key2[index2].key3[index3],value)
sub each {
  my $self = shift;
  my $short_keys = shift;

  my $stack = $self->{'stack'};

  my($found,$key,$value);
  my $top = $stack->[$#{$stack}];
  while ($top && !$found) {
    $found++ if ($key,$value) = $top->next;
    if (!$found) {		# this iterator is done
      pop @{$stack};
      $top = $stack->[$#{$stack}];
      next;
    }
    if ( ref $value && !exists $value->{'.name'} ) { # found another record to begin iterating on
      if (%{$value}) {
	undef $found;
	$top = $value->cursor;
	push @{$stack},$top;
	next;
      } else {
	undef $value;
      }
    }
  }
  unless ($found) {
    $self->reset;
    return ();
  }
  return ($key,$value) if $short_keys;
  
  my @keylist = map {($_->{'keys'}->[$_->{'hashindex'}]) 
		       . "[" . ($_->{'arrayindex'}-1) ."]"; } @{$stack};
  return (join(".",@keylist),$value);
}

sub reset {
    my $self = shift;
    $self->{'arrayindex'} = 0;
    $self->{'hashindex'} = 0;
    $self->{'keys'}=[$self->{'stone'}->tags];
    $self->{'stack'}=[$self];
}

sub DESTROY {
    my $self = shift;
    if (ref $self->{'stone'}) {
	$self->{'stone'}->_register_cursor($self,undef);
    }
}

# Next will return the next index in its Stone object,
# indexing first through the members of the array, and then through
# the individual keys.  When iteration is finished, it resets itself
# and returns an empty array.
sub next {
    my $self = shift;
    my($arrayi,$hashi,$stone,$keys) = ($self->{'arrayindex'},
				       $self->{'hashindex'},
				       $self->{'stone'},
				       $self->{'keys'});
    unless ($stone->exists($keys->[$hashi],$arrayi)) {
	$self->{hashindex}=++$hashi;
	$self->{arrayindex}=$arrayi=0;
	unless (defined($keys->[$hashi]) &&
		defined($stone->get($keys->[$hashi],$arrayi))) {
	    $self->reset;
	    return ();
	}
    }
    $self->{arrayindex}++;
    return ($keys->[$hashi],$stone->get($keys->[$hashi],$arrayi));
}


1;