File: Format.pm

package info (click to toggle)
libtemplate-plugin-number-format-perl 1.06-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid, stretch
  • size: 84 kB
  • ctags: 4
  • sloc: perl: 132; makefile: 2
file content (255 lines) | stat: -rw-r--r-- 7,709 bytes parent folder | download
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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
package Template::Plugin::Number::Format;

# ----------------------------------------------------------------------
#  Template::Plugin::Number::Format - Plugin/filter interface to Number::Format
#  Copyright (C) 2002-2015 Darren Chamberlain <darren@cpan.org>
#
#  This program is free software: you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation, either version 3 of the License, or
#  (at your option) any later version.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
#  You should have received a copy of the GNU General Public License
#  along with this program.  If not, see <http://www.gnu.org/licenses/>.
# -------------------------------------------------------------------

use strict;
use vars qw($VERSION $DYNAMIC $AUTOLOAD);

$VERSION = '1.06';
$DYNAMIC = 1;

use Number::Format;
use base qw(Template::Plugin::Filter);

# ----------------------------------------------------------------------
# filter($text)
#
# The default filter is format_number, i.e., commify.
# ----------------------------------------------------------------------
sub filter {
    my ($self, $text, $args) = @_;
    $self->{ _NFO }->format_number($text, @$args);
}


# ----------------------------------------------------------------------
# init($config)
#
# Initialize the instance.  Creates a Number::Format object, which is
# used to create closures that implement the filters.
# ----------------------------------------------------------------------
sub init {
    my ($self, $config) = @_;
    my ($sub, $filter, $nfo);
    $nfo = Number::Format->new(%$config);
    
    $self->{ _DYNAMIC } = 1;
    $self->{ _NFO } = $nfo;

    # ------------------------------------------------------------------
    # This makes is dependant upon Number::Format not changing the 
    # Exporter interface it advertises, which is unlikely.
    #
    # It is likely that each of these subroutines should accept all
    # the configuration options of the constructor, and instantiate a
    # new Number::Format instance.  This is easier, for now.
    # ------------------------------------------------------------------
    for my $sub (@{$Number::Format::EXPORT_TAGS{"subs"}}) {
        my $filter = sub {
            my ($context, @args) = @_;
            return sub {
                my $text = shift;
                return $nfo->$sub($text, @args);
            };
        };
        $self->{ _CONTEXT }->define_filter($sub, $filter, 1);
    }

    return $self;
}

# ----------------------------------------------------------------------
# AUTOLOAD
#
# Catches method calls; so that the plugin can be used like you'd
# expect a plugin to work:
#
# [% USE nf = Number.Format; nf.format_number(num) %]
# ----------------------------------------------------------------------
sub AUTOLOAD {
    my $self = shift;
   (my $autoload = $AUTOLOAD) =~ s/.*:://;

    return if $autoload eq 'DESTROY';

    $self->{ _NFO }->$autoload(@_);
}

1;

__END__

=head1 NAME

Template::Plugin::Number::Format - Plugin/filter interface to Number::Format

=head1 SYNOPSIS

    [% USE Number.Format %]
    [% num | format_number %]

=head1 ABSTRACT

Template::Plugin::Number::Format makes the number-munging grooviness
of Number::Format available to your templates.  It is used like a
plugin, but installs filters into the current context.

=head1 DESCRIPTION

All filters created by Template::Plugin::Number::Format can be
configured by constructor options and options that can be passed to
individual filters.  See L<Number::Format/"METHODS"> for all the details.

=head2 Constructor Parameters

The USE line accepts the following parameters, all optional, which
define the default behavior for filters within the current Context:

=over 4

=item THOUSANDS_SEP

character inserted between groups of 3 digits

=item DECIMAL_POINT

character separating integer and fractional parts

=item MON_THOUSANDS_SEP

like THOUSANDS_SEP, but used for format_price

=item MON_DECIMAL_POINT

like DECIMAL_POINT, but used for format_price

=item INT_CURR_SYMBOL

character(s) denoting currency (see format_price())

=item DECIMAL_DIGITS

number of digits to the right of dec point (def 2)

=item DECIMAL_FILL

boolean; whether to add zeroes to fill out decimal

=item NEG_FORMAT

format to display negative numbers (def -x)

=item KILO_SUFFIX

suffix to add when format_bytes formats kilobytes

=item MEGA_SUFFIX

suffix to add when format_bytes formats megabytes

=item GIGA_SUFFIX

suffix to add when format_bytes formats gigabytes

=back

=head1 Using Template::Plugin::Number::Format

When you invoke:

    [% USE Number.Format(option = value) %]

the following filters are installed into the current Context:

=over 4

=item B<round($precision)>

Rounds the number to the specified precision.  If "$precision" is
omitted, the value of the "DECIMAL_DIGITS" parameter is used
(default value 2).

=item B<format_number($precision, $trailing_zeros)>

Formats a number by adding "THOUSANDS_SEP" between each set of 3
digits to the left of the decimal point, substituting "DECIMAL_POINT"
for the decimal point, and rounding to the specified precision using
"round()".  Note that "$precision" is a maximum precision specifier;
trailing zeroes will only appear in the output if "$trailing_zeroes"
is provided, or the parameter "DECIMAL_FILL" is set, with a value that
is true (not zero, undef, or the empty string).  If "$precision" is
omitted, the value of the "DECIMAL_DIGITS" parameter (default value
of 2) is used.

=item B<format_negative($picture)>

Formats a negative number.  Picture should be a string that contains
the letter "x" where the number should be inserted.  For example, for
standard negative numbers you might use "-x", while for
accounting purposes you might use "(x)".  If the specified number
begins with a - character, that will be removed before formatting, but
formatting will occur whether or not the number is negative.

=item B<format_picture($picture)>

Returns a string based on "$picture" with the "#" characters replaced
by digits from "$number".  If the length of the integer part of
$number is too large to fit, the "#" characters are replaced with
asterisks ("*") instead. 

=item B<format_price($precision)>

Returns a string containing "$number" formatted similarly to
"format_number()", except that the decimal portion may have trailing
zeroes added to make it be exactly "$precision" characters long, and
the currency string will be prefixed.

If the "INT_CURR_SYMBOL" attribute of the object is the empty string,
no currency will be added.

If "$precision" is not provided, the default of 2 will be used. 

=item B<format_bytes($precision)>

Returns a string containing "$number" formatted similarly to
"format_number()", except that if the number is over 1024, it will be
divided by 1024 and the value of KILO_SUFFIX appended to the end; or
if it is over 1048576 (1024*1024), it will be divided by 1048576 and
MEGA_SUFFIX appended to the end.  Negative values will result in an
error.

If "$precision" is not provided, the default of 2 will be used.

=item B<unformat_number>

Converts a string as returned by "format_number()", "format_price()",
or "format_picture()", and returns the corresponding value as a
numeric scalar.  Returns "undef" if the number does not contain any
digits.

=back

=head1 SEE ALSO

L<Template|Template>, L<Number::Format|Number::Format>

=head1 AUTHOR

darren chamberlain E<lt>darren@cpan.orgE<gt>