README
1NAME
2 Template::Plugin::Number::Format - Plugin/filter interface to
3 Number::Format
4
5SYNOPSIS
6 [% USE Number.Format %]
7 [% num | format_number %]
8
9ABSTRACT
10 Template::Plugin::Number::Format makes the number-munging grooviness of
11 Number::Format available to your templates. It is used like a plugin,
12 but installs filters into the current context.
13
14DESCRIPTION
15 All filters created by Template::Plugin::Number::Format can be
16 configured by constructor options and options that can be passed to
17 individual filters. See "METHODS" in Number::Format for all the details.
18
19 Constructor Parameters
20 The USE line accepts the following parameters, all optional, which
21 define the default behavior for filters within the current Context:
22
23 THOUSANDS_SEP
24 character inserted between groups of 3 digits
25
26 DECIMAL_POINT
27 character separating integer and fractional parts
28
29 MON_THOUSANDS_SEP
30 like THOUSANDS_SEP, but used for format_price
31
32 MON_DECIMAL_POINT
33 like DECIMAL_POINT, but used for format_price
34
35 INT_CURR_SYMBOL
36 character(s) denoting currency (see format_price())
37
38 DECIMAL_DIGITS
39 number of digits to the right of dec point (def 2)
40
41 DECIMAL_FILL
42 boolean; whether to add zeroes to fill out decimal
43
44 NEG_FORMAT
45 format to display negative numbers (def -x)
46
47 KILO_SUFFIX
48 suffix to add when format_bytes formats kilobytes
49
50 MEGA_SUFFIX
51 suffix to add when format_bytes formats megabytes
52
53 GIGA_SUFFIX
54 suffix to add when format_bytes formats gigabytes
55
56Using Template::Plugin::Number::Format
57 When you invoke:
58
59 [% USE Number.Format(option = value) %]
60
61 the following filters are installed into the current Context:
62
63 round($precision)
64 Rounds the number to the specified precision. If "$precision" is
65 omitted, the value of the "DECIMAL_DIGITS" parameter is used
66 (default value 2).
67
68 format_number($precision, $trailing_zeros)
69 Formats a number by adding "THOUSANDS_SEP" between each set of 3
70 digits to the left of the decimal point, substituting
71 "DECIMAL_POINT" for the decimal point, and rounding to the specified
72 precision using "round()". Note that "$precision" is a maximum
73 precision specifier; trailing zeroes will only appear in the output
74 if "$trailing_zeroes" is provided, or the parameter "DECIMAL_FILL"
75 is set, with a value that is true (not zero, undef, or the empty
76 string). If "$precision" is omitted, the value of the
77 "DECIMAL_DIGITS" parameter (default value of 2) is used.
78
79 format_negative($picture)
80 Formats a negative number. Picture should be a string that contains
81 the letter "x" where the number should be inserted. For example, for
82 standard negative numbers you might use "-x", while for accounting
83 purposes you might use "(x)". If the specified number begins with a
84 - character, that will be removed before formatting, but formatting
85 will occur whether or not the number is negative.
86
87 format_picture($picture)
88 Returns a string based on "$picture" with the "#" characters
89 replaced by digits from "$number". If the length of the integer part
90 of $number is too large to fit, the "#" characters are replaced with
91 asterisks ("*") instead.
92
93 format_price($precision)
94 Returns a string containing "$number" formatted similarly to
95 "format_number()", except that the decimal portion may have trailing
96 zeroes added to make it be exactly "$precision" characters long, and
97 the currency string will be prefixed.
98
99 If the "INT_CURR_SYMBOL" attribute of the object is the empty
100 string, no currency will be added.
101
102 If "$precision" is not provided, the default of 2 will be used.
103
104 format_bytes($precision)
105 Returns a string containing "$number" formatted similarly to
106 "format_number()", except that if the number is over 1024, it will
107 be divided by 1024 and the value of KILO_SUFFIX appended to the end;
108 or if it is over 1048576 (1024*1024), it will be divided by 1048576
109 and MEGA_SUFFIX appended to the end. Negative values will result in
110 an error.
111
112 If "$precision" is not provided, the default of 2 will be used.
113
114 unformat_number
115 Converts a string as returned by "format_number()",
116 "format_price()", or "format_picture()", and returns the
117 corresponding value as a numeric scalar. Returns "undef" if the
118 number does not contain any digits.
119
120SEE ALSO
121 Template, Number::Format
122
123AUTHOR
124 darren chamberlain <darren@cpan.org>
125
126