File Coverage

blib/lib/News/Active/Entry.pm
Criterion Covered Total %
statement 3 26 11.5
branch 0 12 0.0
condition 0 27 0.0
subroutine 1 12 8.3
pod 11 11 100.0
total 15 88 17.0


line stmt bran cond sub pod time code
1             $VERSION = "0.10";
2             package News::Active::Entry;
3             our $VERSION = "0.10";
4              
5             # -*- Perl -*- # Wed Apr 28 08:59:14 CDT 2004
6             ###############################################################################
7             # Written by Tim Skirvin . Copyright 2003-2004,
8             # Tim Skirvin. Redistribution terms are below.
9             ###############################################################################
10              
11             =head1 NAME
12              
13             News::Active::Entry - an object for storing specific active file information
14              
15             =head1 SYNOPSIS
16              
17             use News::Active::Entry;
18             use News::Active;
19              
20             my $item = new News::Active::Entry("humanities.philosophy.objectivism");
21             $item->add_article(1);
22             my $string = $item->output;
23              
24             See below for more specific information about related functions.
25              
26             =head1 DESCRIPTION
27              
28             News::Active::Entry contains the actual active file entries for
29             News::Active. Each entry consists of a group name, flags, and information
30             about the article numbers in the group. Within that, it is a very simple
31             module (significantly more lines dedicated to documentation than actual
32             code).
33              
34             =head1 USAGE
35              
36             News::Active::Entry is accessed through the following functions:
37              
38             =cut
39              
40             ###############################################################################
41             ### main() ####################################################################
42             ###############################################################################
43              
44 1     1   5 use strict;
  1         2  
  1         627  
45              
46             =head2 Functions
47              
48             =over 4
49              
50             =item new ( STRING )
51              
52             Creates and returns a new News::Active::Entry object. C is a
53             scalar containing the group name, first article, final article, group
54             flags, and article count for the given group, separated by '::'.
55              
56             Only the group name is really required; the rest will be worked on on
57             their own. Therefore, just passing in the group name will work fine.
58              
59             =cut
60              
61             sub new {
62 0     0 1   my ($proto, $string) = @_;
63 0           my ($group, $first, $final, $flags, $count) = split('::', $string);
64 0 0         return undef unless $group;
65 0   0       my $class = ref($proto) || $proto;
66 0   0       my $self = {
      0        
      0        
      0        
      0        
67             'count' => $count || 0,
68             'first' => $first || 0,
69             'final' => $final || 0,
70             'flags' => $flags || 'y',
71             'name' => $group || '',
72             };
73 0           bless $self, $class;
74             }
75              
76             =item first ( [NUMBER] )
77              
78             =item final ( [NUMBER] )
79              
80             =item count ( [NUMBER] )
81              
82             =item name ( [STRING] )
83              
84             =item flags ( [STRING] )
85              
86             Returns the relevant information from the object, as indicated above. If
87             an argument is passed to these functions, then the value is set to that
88             value; otherwise, we just return the existing value.
89              
90             =cut
91              
92 0 0 0 0 1   sub first { defined $_[1] ? $_[0]->{first} = $_[1] : $_[0]->{first} || 0 }
93 0 0 0 0 1   sub final { defined $_[1] ? $_[0]->{final} = $_[1] : $_[0]->{final} || 0 }
94 0 0 0 0 1   sub count { defined $_[1] ? $_[0]->{count} = $_[1] : $_[0]->{count} || 0 }
95 0 0 0 0 1   sub name { defined $_[1] ? $_[0]->{name} = $_[1] : $_[0]->{name} || "" }
96 0 0 0 0 1   sub flags { defined $_[1] ? $_[0]->{flags} = $_[1] : $_[0]->{flags} || "" }
97              
98             =item arrayref ()
99              
100             Returns an array reference containing C, C, and
101             C (the same information stored by INN's active file).
102              
103             =cut
104              
105             sub arrayref {
106 0     0 1   my ($self) = @_;
107 0           [ $self->final, $self->first, $self->flags ];
108             }
109              
110             =item print ()
111              
112             Makes a human-readable string containing the information from name(),
113             first(), final(), flags(), and count().
114              
115             =cut
116              
117             sub print {
118 0     0 1   my ($self) = @_;
119 0           sprintf("%-41s %010d %010d %5s %010d",
120             $self->name, $self->first, $self->final, $self->flags, $self->count);
121             }
122              
123             =item add_article ( [COUNT] )
124              
125             Indicates that we've added a single article to the given newsgroup, by
126             incrementing both final() and count() by C (defaults to 1).
127             first() is set to one if it was not set. Returns the number of articles
128             we added.
129              
130             =cut
131              
132             sub add_article {
133 0   0 0 1   my ($self, $count) = @_; $count ||= 1;
  0            
134 0           $$self{final} += $count; $$self{count} += $count;
  0            
135 0   0       $$self{first} ||= 1;
136 0           $count;
137             }
138              
139             =item next_number ()
140              
141             Returns the next article number that we will be saving to.
142              
143             =cut
144              
145 0     0 1   sub next_number { shift->{final} + 1 }
146              
147             =item output ()
148              
149             Returns the string that is needed by new() - ie, a string containing
150             name(), first(), final(), flags(), and count() separated by '::'.
151              
152             =cut
153              
154 0     0 1   sub output { join("::", $_[0]->name, $_[0]->first, $_[0]->final,
155             $_[0]->flags, $_[0]->count ); }
156              
157             =back
158              
159             =cut
160              
161             1;
162              
163             =head1 REQUIREMENTS
164              
165             B
166              
167             =head1 SEE ALSO
168              
169             B
170              
171             =head1 AUTHOR
172              
173             Tim Skirvin
174              
175             =head1 HOMEPAGE
176              
177             B
178              
179             B
180              
181             =head1 LICENSE
182              
183             This code may be redistributed under the same terms as Perl itself.
184              
185             =head1 COPYRIGHT
186              
187             Copyright 2003-2004, Tim Skirvin.
188              
189             =cut
190              
191             ###############################################################################
192             ##### Version History #########################################################
193             ###############################################################################
194             # v0.10 Wed Apr 28 09:03:05 CDT 2004
195             ### First documented version; it's been working since last year, though.