Bugzilla::Util - Generic utility functions for bugzilla
use Bugzilla::Util;
# Functions for dealing with variable tainting
$rv = is_tainted($var);
trick_taint($var);
detaint_natural($var);
detaint_signed($var);
# Functions for quoting
html_quote($var);
url_quote($var);
value_quote($var);
xml_quote($var);
# Functions for decoding
$rv = url_decode($var);
# Functions that tell you about your environment
my $is_cgi = i_am_cgi();
my $net_addr = get_netaddr($ip_addr);
my $urlbase = correct_urlbase();
# Functions for searching
$loc = lsearch(\@arr, $val);
# Data manipulation
($removed, $added) = diff_arrays(\@old, \@new);
# Functions for manipulating strings
$val = trim(" abc ");
($removed, $added) = diff_strings($old, $new);
$wrapped = wrap_comment($comment);
$msg = perform_substs($str, $substs);
# Functions for formatting time
format_time($time);
# 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);
This package contains various utility functions which do not belong anywhere else.
It is not intended as a general dumping group for something which people feel might be useful somewhere, someday. 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.
This package provides several types of routines:
Several functions are available to deal with tainted variables. Use these with care to avoid security holes.
is_taintedDetermines whether a particular variable is tainted
trick_taint($val)Tricks perl into untainting a particular variable.
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.
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.
detaint_natural($num)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 MUST check the result of this routine to avoid security holes.
detaint_signed($num)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 MUST check the result of this routine to avoid security holes.
Some values may need to be quoted from perl. However, this should in general be done in the template where possible.
html_quote($val)Returns a value quoted for use in HTML, with &, <, >, and " being replaced with their appropriate HTML entities.
html_light_quote($val)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.
url_quote($val)Quotes characters so that they may be included as part of a url.
css_class_quote($val)Quotes characters so that they may be used as CSS class names. Spaces are replaced by underscores.
value_quote($val)As well as escaping html like html_quote, this routine converts newlines into 
, suitable for use in html attributes.
xml_quote($val)This is similar to html_quote, except that ' is escaped to '. This is kept separate from html_quote partly for compatibility with previous code (for ') and partly for future handling of non-ASCII characters.
url_decode($val)Converts the %xx encoding from the given URL back to its original form.
Functions returning information about your environment or location.
i_am_cgi()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.
get_netaddr($ipaddr)Given an IP address, this returns the associated network address, using Bugzilla-params->{'loginnetmask'}> as the netmask. This can be used to obtain data in order to restrict weak authentication methods (such as cookies) to only some addresses.
correct_urlbase()Returns either the sslbase or urlbase parameter, depending on the current setting for the ssl parameter.
use_attachbase()Returns true if an alternate host is used to display attachments; false otherwise.
Functions for searching within a set of values.
lsearch($list, $item)Returns the position of $item in $list. $list must be a list reference.
If the item is not in the list, returns -1.
diff_arrays(\@old, \@new) 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.
trim($str)Removes any leading or trailing whitespace from a string. This routine does not modify the existing string.
diff_strings($oldstr, $newstr)Takes two strings containing a list of comma- or space-separated items and returns what items were removed from or added to the new one, compared to the old one. Returns a list, where the first entry is a scalar containing removed items, and the second entry is a scalar containing added items.
wrap_comment($comment)Takes a bug comment, and wraps it to the appropriate length. The length is currently specified in Bugzilla::Constants::COMMENT_COLS. Lines beginning with ">" are assumed to be quotes, and they will not be wrapped.
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.
find_wrap_point($string, $maxpos)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.
perform_substs($str, $substs)Performs substitutions for sending out email with variables in it, or for inserting a parameter into some other string.
Takes a string and a reference to a hash containing substitution variables and their values.
If the hash is not specified, or if we need to substitute something that's not in the hash, then we will use parameters to do the substitution instead.
Substitutions are always enclosed with '%' symbols. So they look like: %some_variable_name%. If "some_variable_name" is a key in the hash, then its value will be placed into the string. If it's not a key in the hash, then the value of the parameter called "some_variable_name" will be placed into the string.
is_7bit_clean($str)Returns true is the string contains only 7-bit characters (ASCII 32 through 126, ASCII 10 (LineFeed) and ASCII 13 (Carrage Return).
clean_text($str) 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).
get_textThis 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.
It uses the global/message.txt.tmpl template to return a string.
$message - The identifier for the message.
$vars - A hashref. Any variables you want to pass to the template.A string.
format_time($time)Takes a time, converts it to the desired format and appends the timezone as defined in editparams.cgi, if desired. This routine will be expanded in the future to adjust for user preferences regarding what timezone to display times in.
This routine is mainly called from templates to filter dates, see "FILTER time" in Templates.pm. In this case, $format is undefined and the routine has to "guess" the date format that was passed to $dbh->sql_date_format().
format_time_decimal($time)Returns a number with 2 digit precision, unless the last digit is a 0. Then it returns only 1 digit precision.
file_mod_time($filename)Takes a filename and returns the modification time. It returns it in the format of the "mtime" parameter of the perl "stat" function.
bz_crypt($password)Takes a string and returns a crypted value for it, using a random salt.
Please always use this function instead of the built-in perl "crypt" when initially encrypting a password.
generate_random_password($password_length)Returns an alphanumeric string with the specified length (10 characters by default). Use this function to generate passwords and tokens.
validate_email_syntax($email)Do a syntax checking for a legal email address and returns 1 if the check is successful, else returns 0. Untaints $email if successful.
validate_date($date)Make sure the date has the correct format and returns 1 if the check is successful, else returns 0.