remove things deprecated since v3
[freeside.git] / FS / FS / detail_format.pm
1 package FS::detail_format;
2
3 use strict;
4 use vars qw( $DEBUG );
5 use FS::Conf;
6 use FS::cdr;
7 use FS::cust_bill_pkg_detail;
8 use FS::L10N;
9 use Date::Language;
10 use Text::CSV_XS;
11
12 my $me = '[FS::detail_format]';
13
14 =head1 NAME
15
16 FS::detail_format - invoice detail formatter
17
18 =head1 DESCRIPTION
19
20 An FS::detail_format object is a converter to create invoice details 
21 (L<FS::cust_bill_pkg_detail>) from call detail records (L<FS::cdr>)
22 or other usage information.  FS::detail_format inherits from nothing.
23
24 Subclasses of FS::detail_format represent specific detail formats.
25
26 =head1 CLASS METHODS
27
28 =over 4
29
30 =item new FORMAT, OPTIONS
31
32 Returns a new detail formatter.  The FORMAT argument is the name of 
33 a subclass.
34
35 OPTIONS may contain:
36
37 - buffer: an arrayref to store details into.  This may avoid the need for a
38 large copy operation at the end of processing.  However, since summary formats
39 will produce nothing until the end of processing, C<finish> must be called
40 after all CDRs have been appended.
41
42 - inbound: a flag telling the formatter to format CDRs for display to the
43 receiving party, rather than the originator.  In this case, the
44 L<FS::cdr_termination> object will be fetched and its values used for
45 rated_price, rated_seconds, rated_minutes, and svcnum.  This can be changed
46 with the C<inbound> method.
47
48 - locale: a locale string to use for static text and date formats.  This is
49 optional.
50
51 =cut
52
53 sub new {
54   my $class = shift;
55   if ( $class eq 'FS::detail_format' ) {
56     my $format = shift
57       or die "$me format name required";
58     $class = "FS::detail_format::$format"
59       unless $format =~ /^FS::detail_format::/;
60   }
61   eval "use $class";
62   die "$me error loading $class: $@" if $@;
63   my %opt = @_;
64
65   my $locale = $opt{'locale'} || '';
66   my $conf = FS::Conf->new({ locale => $locale });
67   $locale ||= $conf->config('locale') || 'en_US';
68
69   my %locale_info = FS::Locales->locale_info($locale);
70   my $language_name = $locale_info{'name'};
71
72   my $self = { conf => FS::Conf->new({ locale => $locale }),
73                csv  => Text::CSV_XS->new({ binary => 1 }),
74                inbound  => ($opt{'inbound'} ? 1 : 0),
75                buffer   => ($opt{'buffer'} || []),
76                _lh      => FS::L10N->get_handle($locale),
77                _dh      => eval { Date::Language->new($language_name) } ||
78                            Date::Language->new()
79              };
80   bless $self, $class;
81 }
82
83 =back
84
85 =head1 METHODS
86
87 =over 4
88
89 =item inbound VALUE
90
91 Set/get the 'inbound' flag.
92
93 =cut
94
95 sub inbound {
96   my $self = shift;
97   $self->{inbound} = ($_[0] > 0) if (@_);
98   $self->{inbound};
99 }
100
101 =item phonenum VALUE
102
103 Set/get the locally meaningful phone number.  This is used to tag call details
104 for presentation on certain kinds of invoices.
105
106 =cut
107
108 sub phonenum {
109   my $self = shift;
110   $self->{phonenum} = shift if @_;
111   $self->{phonenum};
112 }
113
114 =item append CDRS
115
116 Takes any number of call detail records (as L<FS::cdr> objects),
117 formats them, and appends them to the internal buffer.
118
119 By default, this simply calls C<single_detail> on each CDR in the 
120 set.  Subclasses should override C<append> and maybe C<finish> if 
121 they do not produce detail lines from CDRs in a 1:1 fashion.
122
123 The 'billpkgnum', 'invnum', 'pkgnum', and 'phonenum' fields will 
124 be set later.
125
126 =cut
127
128 sub append {
129   my $self = shift;
130   foreach (@_) {
131     push @{ $self->{buffer} }, $self->single_detail($_);
132   }
133 }
134
135 =item details
136
137 Returns all invoice detail records in the buffer.  This will perform 
138 a C<finish> first.  Subclasses generally shouldn't override this.
139
140 =cut
141
142 sub details {
143   my $self = shift;
144   $self->finish;
145   @{ $self->{buffer} }
146 }
147
148 =item finish
149
150 Ensures that all invoice details are generated given the CDRs that 
151 have been appended.  By default, this does nothing.
152
153 =cut
154
155 sub finish {}
156
157 =item header
158
159 Returns a header row for the format, as an L<FS::cust_bill_pkg_detail>
160 object.  By default this has 'format' = 'C', 'detail' = the value 
161 returned by C<header_detail>, and all other fields empty.
162
163 This is called after C<finish>, so it can use information from the CDRs.
164
165 =cut
166
167 sub header {
168   my $self = shift;
169
170   FS::cust_bill_pkg_detail->new(
171     { 'format' => 'C', 'detail' => $self->header_detail }
172   )
173 }
174
175 =item single_detail CDR
176
177 Takes a single CDR and returns an invoice detail to describe it.
178
179 By default, this maps the following fields from the CDR:
180
181 acctid            => acctid
182 rated_price       => amount
183 rated_classnum    => classnum
184 rated_seconds     => duration
185 rated_regionname  => regionname
186 accountcode       => accountcode
187 startdate         => startdate
188
189 'phonenum' is set to the internal C<phonenum> value set on the formatter
190 object.
191
192 It then calls C<columns> on the CDR to obtain a list of detail
193 columns, formats them as a CSV string, and stores that in the 
194 'detail' field.
195
196 =cut
197
198 sub single_detail {
199   my $self = shift;
200   my $cdr = shift;
201
202   my @columns = $self->columns($cdr);
203   my $status = $self->csv->combine(@columns);
204   die "$me error combining ".$self->csv->error_input."\n"
205     if !$status;
206
207   my $object = $self->{inbound} ? $cdr->cdr_termination(1) : $cdr;
208   my $price = $object->rated_price if $object;
209   $price = 0 if $cdr->freesidestatus eq 'no-charge';
210
211   FS::cust_bill_pkg_detail->new( {
212       'acctid'      => $cdr->acctid,
213       'amount'      => $price,
214       'classnum'    => $cdr->rated_classnum,
215       'duration'    => $cdr->rated_seconds,
216       'regionname'  => $cdr->rated_regionname,
217       'accountcode' => $cdr->accountcode,
218       'startdate'   => $cdr->startdate,
219       'format'      => 'C',
220       'detail'      => $self->csv->string,
221       'phonenum'    => $self->phonenum,
222   });
223 }
224
225 =item columns CDR
226
227 Returns a list of CSV columns (to be shown on the invoice) for
228 the CDR.  This is the method most subclasses should override.
229
230 =cut
231
232 sub columns {
233   my $self = shift;
234   die "$me no columns method in ".ref($self);
235 }
236
237 =item header_detail
238
239 Returns the 'detail' field for the header row.  This should 
240 probably be a CSV string of column headers for the values returned
241 by C<columns>.
242
243 =cut
244
245 sub header_detail {
246   my $self = shift;
247   die "$me no header_detail method in ".ref($self);
248 }
249
250 # convenience methods for subclasses
251
252 sub conf { $_[0]->{conf} }
253
254 sub csv { $_[0]->{csv} }
255
256 sub date_format {
257   my $self = shift;
258   $self->{date_format} ||= ($self->conf->config('date_format') || '%m/%d/%Y');
259 }
260
261 sub money_char {
262   my $self = shift;
263   $self->{money_char} ||= ($self->conf->config('money_char') || '$');
264 }
265
266 # localization methods
267
268 sub time2str_local {
269   my $self = shift;
270   $self->{_dh}->time2str(@_);
271 }
272
273 # header strings are now localized in FS::TemplateItem_Mixin::detail
274
275 #imitate previous behavior for now
276
277 sub duration {
278   my $self = shift;
279   my $cdr = shift;
280   my $object = $self->{inbound} ? $cdr->cdr_termination(1) : $cdr;
281   my $sec = $object->rated_seconds if $object;
282   $sec ||= 0;
283   # XXX termination objects don't have rated_granularity so this may 
284   # result in inbound CDRs being displayed as min/sec when they shouldn't.
285   # Should probably fix this.
286   if ( $cdr->rated_granularity eq '0' ) {
287     '1 call';
288   }
289   elsif ( $cdr->rated_granularity eq '60' ) {
290     sprintf('%dm', ($sec + 59)/60);
291   }
292   else {
293     sprintf('%dm %ds', $sec / 60, $sec % 60);
294   }
295 }
296
297 sub price {
298   my $self = shift;
299   my $cdr = shift;
300   my $object = $self->{inbound} ? $cdr->cdr_termination(1) : $cdr;
301   my $price = $object->rated_price if $object;
302   $price = '0.00' if $object->freesidestatus eq 'no-charge';
303   length($price) ? $self->money_char . $price : '';
304 }
305
306 1;