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
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>
Bugzilla::Util</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" title="style" type="text/css" href=".././../../../style.css" media="all" >
</head>
<body id="pod">
<p class="backlinktop"><b><a name="___top" href="../index.html" accesskey="1" title="All Documents"><<</a></b></p>
<h1>Bugzilla::Util</h1>
<div class='indexgroup'>
<ul class='indexList indexList1'>
<li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
<li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
<li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
<li class='indexItem indexItem1'><a href='#FUNCTIONS'>FUNCTIONS</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#Tainting'>Tainting</a>
<li class='indexItem indexItem2'><a href='#Quoting'>Quoting</a>
<li class='indexItem indexItem2'><a href='#Environment_and_Location'>Environment and Location</a>
<li class='indexItem indexItem2'><a href='#Data_Manipulation'>Data Manipulation</a>
<li class='indexItem indexItem2'><a href='#String_Manipulation'>String Manipulation</a>
<li class='indexItem indexItem2'><a href='#Formatting_Time'>Formatting Time</a>
<li class='indexItem indexItem2'><a href='#Files'>Files</a>
<li class='indexItem indexItem2'><a href='#Cryptography'>Cryptography</a>
<li class='indexItem indexItem2'><a href='#Validation'>Validation</a>
<li class='indexItem indexItem2'><a href='#Database'>Database</a>
</ul>
</ul>
</div>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>Bugzilla::Util - Generic utility functions for bugzilla</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre class="code"> use Bugzilla::Util;
# Functions for dealing with variable tainting
trick_taint($var);
detaint_natural($var);
detaint_signed($var);
# Functions for quoting
html_quote($var);
url_quote($var);
xml_quote($var);
email_filter($var);
# Functions for decoding
$rv = url_decode($var);
# Functions that tell you about your environment
my $is_cgi = i_am_cgi();
my $urlbase = correct_urlbase();
# Data manipulation
($removed, $added) = diff_arrays(\@old, \@new);
# Functions for manipulating strings
$val = trim(" abc ");
$wrapped = wrap_comment($comment);
# Functions for formatting time
format_time($time);
datetime_from($time, $timezone);
# Functions for dealing with files
$time = file_mod_time($filename);
# Cryptographic Functions
$crypted_password = bz_crypt($password);
$new_password = generate_random_password($password_length);
# Validation Functions
validate_email_syntax($email);
validate_date($date);
# DB-related functions
on_main_db {
... code here ...
};</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>This package contains various utility functions which do not belong anywhere else.</p>
<p><b>It is not intended as a general dumping group for something which people feel might be useful somewhere, someday</b>. Do not add methods to this package unless it is intended to be used for a significant number of files, and it does not belong anywhere else.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="FUNCTIONS"
>FUNCTIONS</a></h1>
<p>This package provides several types of routines:</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Tainting"
>Tainting</a></h2>
<p>Several functions are available to deal with tainted variables. <b>Use these with care</b> to avoid security holes.</p>
<dl>
<dt><a name="trick_taint($val)"
><code class="code">trick_taint($val)</code></a></dt>
<dd>
<p>Tricks perl into untainting a particular variable.</p>
<p>Use trick_taint() when you know that there is no way that the data in a scalar can be tainted, but taint mode still bails on it.</p>
<p><b>WARNING!! Using this routine on data that really could be tainted defeats the purpose of taint mode. It should only be used on variables that have been sanity checked in some way and have been determined to be OK.</b></p>
<dt><a name="detaint_natural($num)"
><code class="code">detaint_natural($num)</code></a></dt>
<dd>
<p>This routine detaints a natural number. It returns a true value if the value passed in was a valid natural number, else it returns false. You <b>MUST</b> check the result of this routine to avoid security holes.</p>
<dt><a name="detaint_signed($num)"
><code class="code">detaint_signed($num)</code></a></dt>
<dd>
<p>This routine detaints a signed integer. It returns a true value if the value passed in was a valid signed integer, else it returns false. You <b>MUST</b> check the result of this routine to avoid security holes.</p>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Quoting"
>Quoting</a></h2>
<p>Some values may need to be quoted from perl. However, this should in general be done in the template where possible.</p>
<dl>
<dt><a name="html_quote($val)"
><code class="code">html_quote($val)</code></a></dt>
<dd>
<p>Returns a value quoted for use in HTML, with &, <, >, " and @ being replaced with their appropriate HTML entities. Also, Unicode BiDi controls are deleted.</p>
<dt><a name="html_light_quote($val)"
><code class="code">html_light_quote($val)</code></a></dt>
<dd>
<p>Returns a string where only explicitly allowed HTML elements and attributes are kept. All HTML elements and attributes not being in the whitelist are either escaped (if HTML::Scrubber is not installed) or removed.</p>
<dt><a name="url_quote($val)"
><code class="code">url_quote($val)</code></a></dt>
<dd>
<p>Quotes characters so that they may be included as part of a url.</p>
<dt><a name="css_class_quote($val)"
><code class="code">css_class_quote($val)</code></a></dt>
<dd>
<p>Quotes characters so that they may be used as CSS class names. Spaces and forward slashes are replaced by underscores.</p>
<dt><a name="xml_quote($val)"
><code class="code">xml_quote($val)</code></a></dt>
<dd>
<p>This is similar to <code class="code">html_quote</code>, except that ' is escaped to &apos;. This is kept separate from html_quote partly for compatibility with previous code (for &apos;) and partly for future handling of non-ASCII characters.</p>
<dt><a name="url_decode($val)"
><code class="code">url_decode($val)</code></a></dt>
<dd>
<p>Converts the %xx encoding from the given URL back to its original form.</p>
<dt><a name="email_filter"
><code class="code">email_filter</code></a></dt>
<dd>
<p>Removes the hostname from email addresses in the string, if the user currently viewing Bugzilla is logged out. If the user is logged-in, this filter just returns the input string.</p>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Environment_and_Location"
>Environment and Location</a></h2>
<p>Functions returning information about your environment or location.</p>
<dl>
<dt><a name="i_am_cgi()"
><code class="code">i_am_cgi()</code></a></dt>
<dd>
<p>Tells you whether or not you are being run as a CGI script in a web server. For example, it would return false if the caller is running in a command-line script.</p>
<dt><a name="correct_urlbase()"
><code class="code">correct_urlbase()</code></a></dt>
<dd>
<p>Returns either the <code class="code">sslbase</code> or <code class="code">urlbase</code> parameter, depending on the current setting for the <code class="code">ssl_redirect</code> parameter.</p>
<dt><a name="use_attachbase()"
><code class="code">use_attachbase()</code></a></dt>
<dd>
<p>Returns true if an alternate host is used to display attachments; false otherwise.</p>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Data_Manipulation"
>Data Manipulation</a></h2>
<dl>
<dt><a name="diff_arrays(\@old,_\@new)"
><code class="code">diff_arrays(\@old, \@new)</code></a></dt>
<dd>
<pre class="code"> Description: Takes two arrayrefs, and will tell you what it takes to
get from @old to @new.
Params: @old = array that you are changing from
@new = array that you are changing to
Returns: A list of two arrayrefs. The first is a reference to an
array containing items that were removed from @old. The
second is a reference to an array containing items
that were added to @old. If both returned arrays are
empty, @old and @new contain the same values.</pre>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="String_Manipulation"
>String Manipulation</a></h2>
<dl>
<dt><a name="trim($str)"
><code class="code">trim($str)</code></a></dt>
<dd>
<p>Removes any leading or trailing whitespace from a string. This routine does not modify the existing string.</p>
<dt><a name="wrap_hard($string,_$size)"
><code class="code">wrap_hard($string, $size)</code></a></dt>
<dd>
<p>Wraps a string, so that a line is <i>never</i> longer than <code class="code">$size</code>. Returns the string, wrapped.</p>
<dt><a name="wrap_comment($comment)"
><code class="code">wrap_comment($comment)</code></a></dt>
<dd>
<p>Takes a bug comment, and wraps it to the appropriate length. The length is currently specified in <code class="code">Bugzilla::Constants::COMMENT_COLS</code>. Lines beginning with ">" are assumed to be quotes, and they will not be wrapped.</p>
<p>The intended use of this function is to wrap comments that are about to be displayed or emailed. Generally, wrapped text should not be stored in the database.</p>
<dt><a name="find_wrap_point($string,_$maxpos)"
><code class="code">find_wrap_point($string, $maxpos)</code></a></dt>
<dd>
<p>Search for a comma, a whitespace or a hyphen to split $string, within the first $maxpos characters. If none of them is found, just split $string at $maxpos. The search starts at $maxpos and goes back to the beginning of the string.</p>
<dt><a name="is_7bit_clean($str)"
><code class="code">is_7bit_clean($str)</code></a></dt>
<dd>
<p>Returns true is the string contains only 7-bit characters (ASCII 32 through 126, ASCII 10 (LineFeed) and ASCII 13 (Carrage Return).</p>
<dt><a name="disable_utf8()"
><code class="code">disable_utf8()</code></a></dt>
<dd>
<p>Disable utf8 on STDOUT (and display raw data instead).</p>
<dt><a
><code class="code">clean_text($str)</code> Returns the parameter "cleaned" by exchanging non-printable characters with spaces. Specifically characters (ASCII 0 through 31) and (ASCII 127) will become ASCII 32 (Space).</a></dt>
<dd>
<dt><a name="get_text"
><code class="code">get_text</code></a></dt>
<dd>
<dl>
<dt><a name="Description"
><b>Description</b></a></dt>
<dd>
<p>This is a method of getting localized strings within Bugzilla code. Use this when you don't want to display a whole template, you just want a particular string.</p>
<p>It uses the <em class="code">global/message.txt.tmpl</em> template to return a string.</p>
<dt><a name="Params"
><b>Params</b></a></dt>
<dd>
<dl>
<dt><a name="$message_-_The_identifier_for_the_message."
><code class="code">$message</code> - The identifier for the message.</a></dt>
<dd>
<dt><a name="$vars_-_A_hashref._Any_variables_you_want_to_pass_to_the_template."
><code class="code">$vars</code> - A hashref. Any variables you want to pass to the template.</a></dt>
</dl>
<dt><a name="Returns"
><b>Returns</b></a></dt>
<dd>
<p>A string.</p>
</dd>
</dl>
<dt><a name="template_var"
><code class="code">template_var</code></a></dt>
<dd>
<p>This is a method of getting the value of a variable from a template in Perl code. The available variables are in the <code class="code">global/field-descs.none.tmpl</code> template. Just pass in the name of the variable that you want the value of.</p>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Formatting_Time"
>Formatting Time</a></h2>
<dl>
<dt><a name="format_time($time)"
><code class="code">format_time($time)</code></a></dt>
<dd>
<p>Takes a time and converts it to the desired format and timezone. If no format is given, the routine guesses the correct one and returns an empty array if it cannot. If no timezone is given, the user's timezone is used, as defined in his preferences.</p>
<p>This routine is mainly called from templates to filter dates, see "FILTER time" in <a href="../Bugzilla/Template.html" class="podlinkpod"
>Bugzilla::Template</a>.</p>
<dt><a name="format_time_decimal($time)"
><code class="code">format_time_decimal($time)</code></a></dt>
<dd>
<p>Returns a number with 2 digit precision, unless the last digit is a 0. Then it returns only 1 digit precision.</p>
<dt><a name="datetime_from($time,_$timezone)"
><code class="code">datetime_from($time, $timezone)</code></a></dt>
<dd>
<p>Returns a DateTime object given a date string. If the string is not in some valid date format that <code class="code">strptime</code> understands, we return <code class="code">undef</code>.</p>
<p>You can optionally specify a timezone for the returned date. If not specified, defaults to the currently-logged-in user's timezone, or the Bugzilla server's local timezone if there isn't a logged-in user.</p>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Files"
>Files</a></h2>
<dl>
<dt><a name="file_mod_time($filename)"
><code class="code">file_mod_time($filename)</code></a></dt>
<dd>
<p>Takes a filename and returns the modification time. It returns it in the format of the "mtime" parameter of the perl "stat" function.</p>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Cryptography"
>Cryptography</a></h2>
<dl>
<dt><a name="bz_crypt($password,_$salt)"
><code class="code">bz_crypt($password, $salt)</code></a></dt>
<dd>
<p>Takes a string and returns a hashed (encrypted) value for it, using a random salt. An optional salt string may also be passed in.</p>
<p>Please always use this function instead of the built-in perl <code class="code">crypt</code> function, when checking or setting a password. Bugzilla does not use <code class="code">crypt</code>.</p>
<dt><a name="generate_random_password($password_length)"
><code class="code">generate_random_password($password_length)</code></a></dt>
<dd>
<p>Returns an alphanumeric string with the specified length (10 characters by default). Use this function to generate passwords and tokens.</p>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Validation"
>Validation</a></h2>
<dl>
<dt><a name="validate_email_syntax($email)"
><code class="code">validate_email_syntax($email)</code></a></dt>
<dd>
<p>Do a syntax checking for a legal email address and returns 1 if the check is successful, else returns 0. Untaints <code class="code">$email</code> if successful.</p>
<dt><a name="validate_date($date)"
><code class="code">validate_date($date)</code></a></dt>
<dd>
<p>Make sure the date has the correct format and returns 1 if the check is successful, else returns 0.</p>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Database"
>Database</a></h2>
<dl>
<dt><a name="on_main_db"
><code class="code">on_main_db</code></a></dt>
<dd>
<p>Runs a block of code always on the main DB. Useful for when you're inside a subroutine and need to do some writes to the database, but don't know if Bugzilla is currently using the shadowdb or not. Used like:</p>
<pre class="code"> on_main_db {
my $dbh = Bugzilla->dbh;
$dbh->do("INSERT ...");
}</pre>
</dd>
</dl>
<p class="backlinkbottom"><b><a name="___bottom" href="../index.html" title="All Documents"><<</a></b></p>
<!-- end doc -->
</body></html>
|
GitWeb