summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--Bugzilla/FlagType.pm263
1 files changed, 225 insertions, 38 deletions
diff --git a/Bugzilla/FlagType.pm b/Bugzilla/FlagType.pm
index 8a6eb0272..cf8b5d0f3 100644
--- a/Bugzilla/FlagType.pm
+++ b/Bugzilla/FlagType.pm
@@ -19,9 +19,39 @@
#
# Contributor(s): Myk Melez <myk@mozilla.org>
-################################################################################
+=head1 NAME
+
+Bugzilla::FlagType - A module to deal with Bugzilla flag types.
+
+=head1 SYNOPSIS
+
+FlagType.pm provides an interface to flag types as stored in Bugzilla.
+See below for more information.
+
+=head1 NOTES
+
+=over
+
+=item *
+
+Prior to calling routines in this module, it's assumed that you have
+already done a C<require CGI.pl>. This will eventually change in a
+future version when CGI.pl is removed.
+
+=item *
+
+Use of private functions/variables outside this module may lead to
+unexpected results after an upgrade. Please avoid using private
+functions in other files/modules. Private functions are functions
+whose names start with _ or are specifically noted as being private.
+
+=back
+
+=cut
+
+######################################################################
# Module Initialization
-################################################################################
+######################################################################
# Make it harder for us to do dangerous things in Perl.
use strict;
@@ -36,14 +66,24 @@ use Bugzilla::Error;
use Bugzilla::Util;
use Bugzilla::Config;
-# Note! This module requires that its caller have said "require CGI.pl"
-# to import relevant functions from that script and its companion globals.pl.
-
-################################################################################
+######################################################################
# Global Variables
-################################################################################
+######################################################################
-# basic sets of columns and tables for getting flag types from the database
+=begin private
+
+=head1 PRIVATE VARIABLES/CONSTANTS
+
+=over
+
+=item C<@base_columns>
+
+basic sets of columns and tables for getting flag types from the
+database. B<Used by get, match, sqlify_criteria and perlify_record>
+
+=back
+
+=cut
my @base_columns =
("1", "flagtypes.id", "flagtypes.name", "flagtypes.description",
@@ -52,20 +92,44 @@ my @base_columns =
"flagtypes.is_requesteeble", "flagtypes.is_multiplicable",
"flagtypes.grant_group_id", "flagtypes.request_group_id");
-# Note: when adding tables to @base_tables, make sure to include the separator
-# (i.e. a comma or words like "LEFT OUTER JOIN") before the table name,
-# since tables take multiple separators based on the join type, and therefore
-# it is not possible to join them later using a single known separator.
+=pod
+
+=over
+
+=item C<@base_tables>
+
+Which database(s) is the data coming from?
+
+Note: when adding tables to @base_tables, make sure to include the separator
+(i.e. a comma or words like C<LEFT OUTER JOIN>) before the table name,
+since tables take multiple separators based on the join type, and therefore
+it is not possible to join them later using a single known separator.
+B<Used by get, match, sqlify_criteria and perlify_record>
+
+=back
+
+=end private
+
+=cut
my @base_tables = ("flagtypes");
-################################################################################
+######################################################################
# Public Functions
-################################################################################
+######################################################################
+=head1 PUBLIC FUNCTIONS/METHODS
-sub get {
- # Returns a hash of information about a flag type.
+=over
+
+=item C<get($id)>
+
+Returns a hash of information about a flag type.
+
+=back
+=cut
+
+sub get {
my ($id) = @_;
my $select_clause = "SELECT " . join(", ", @base_columns);
@@ -80,16 +144,52 @@ sub get {
return $type;
}
+=pod
+
+=over
+
+=item C<get_inclusions($id)>
+
+Someone please document this
+
+=back
+
+=cut
+
sub get_inclusions {
my ($id) = @_;
return get_clusions($id, "in");
}
+=pod
+
+=over
+
+=item C<get_exclusions($id)>
+
+Someone please document this
+
+=back
+
+=cut
+
sub get_exclusions {
my ($id) = @_;
return get_clusions($id, "ex");
}
+=pod
+
+=over
+
+=item C<get_clusions($id, $type)>
+
+Someone please document this
+
+=back
+
+=cut
+
sub get_clusions {
my ($id, $type) = @_;
@@ -111,10 +211,20 @@ sub get_clusions {
return \@clusions;
}
-sub match {
- # Queries the database for flag types matching the given criteria
- # and returns the set of matching types.
+=pod
+=over
+
+=item C<match($criteria, $include_count)>
+
+Queries the database for flag types matching the given criteria
+and returns the set of matching types.
+
+=back
+
+=cut
+
+sub match {
my ($criteria, $include_count) = @_;
my @tables = @base_tables;
@@ -157,9 +267,19 @@ sub match {
return \@types;
}
+=pod
+
+=over
+
+=item C<count($criteria)>
+
+Returns the total number of flag types matching the given criteria.
+
+=back
+
+=cut
+
sub count {
- # Returns the total number of flag types matching the given criteria.
-
my ($criteria) = @_;
# Generate query components.
@@ -184,14 +304,25 @@ sub count {
return $count;
}
+=pod
+
+=over
+
+=item C<validate($data, $bug_id, $attach_id)>
+
+Get a list of flag types to validate. Uses the "map" function
+to extract flag type IDs from form field names by matching columns
+whose name looks like "flag_type-nnn", where "nnn" is the ID,
+and returning just the ID portion of matching field names.
+
+=back
+
+=cut
+
sub validate {
my $user = Bugzilla->user;
my ($data, $bug_id, $attach_id) = @_;
- # Get a list of flag types to validate. Uses the "map" function
- # to extract flag type IDs from form field names by matching columns
- # whose name looks like "flag_type-nnn", where "nnn" is the ID,
- # and returning just the ID portion of matching field names.
my @ids = map(/^flag_type-(\d+)$/ ? $1 : (), keys %$data);
foreach my $id (@ids)
@@ -273,10 +404,20 @@ sub validate {
}
}
+=pod
+
+=over
+
+=item C<normalize(@ids)>
+
+Given a list of flag types, checks its flags to make sure they should
+still exist after a change to the inclusions/exclusions lists.
+
+=back
+
+=cut
+
sub normalize {
- # Given a list of flag types, checks its flags to make sure they should
- # still exist after a change to the inclusions/exclusions lists.
-
# A list of IDs of flag types to normalize.
my (@ids) = @_;
@@ -309,17 +450,30 @@ sub normalize {
Bugzilla::Flag::clear(&::FetchOneColumn()) while &::MoreSQLData();
}
-################################################################################
+######################################################################
# Private Functions
-################################################################################
+######################################################################
+
+=begin private
+
+=head1 PRIVATE FUNCTIONS
+
+=over
+
+=item C<sqlify_criteria($criteria, Rtables, $columns, $having)>
+
+Converts a hash of criteria into a list of SQL criteria.
+$criteria is a reference to the criteria (field => value),
+$tables is a reference to an array of tables being accessed
+by the query, $columns is a reference to an array of columns
+being returned by the query, and $having is a reference to
+a criterion to put into the HAVING clause.
+
+=back
+
+=cut
sub sqlify_criteria {
- # Converts a hash of criteria into a list of SQL criteria.
- # $criteria is a reference to the criteria (field => value),
- # $tables is a reference to an array of tables being accessed
- # by the query, $columns is a reference to an array of columns
- # being returned by the query, and $having is a reference to
- # a criterion to put into the HAVING clause.
my ($criteria, $tables, $columns, $having) = @_;
# the generated list of SQL criteria; "1=1" is a clever way of making sure
@@ -379,9 +533,20 @@ sub sqlify_criteria {
return @criteria;
}
+=pod
+
+=over
+
+=item C<perlify_record()>
+
+Converts data retrieved from the database into a Perl record. Depends on the
+formatting as described in @base_columns.
+
+=back
+
+=cut
+
sub perlify_record {
- # Converts data retrieved from the database into a Perl record.
-
my $type = {};
$type->{'exists'} = $_[0];
@@ -402,4 +567,26 @@ sub perlify_record {
return $type;
}
+=end private
+
+=head1 SEE ALSO
+
+=over
+
+=item B<Bugzilla::Flags>
+
+=back
+
+=head1 CONTRIBUTORS
+
+=over
+
+=item Myk Melez <myk@mozilla.org>
+
+=item Kevin Benton <kevin.benton@amd.com>
+
+=back
+
+=cut
+
1;
generated by cgit v1.2.3-24-g4f1b (git 2.32.0) at 2024-11-23 02:38:51 +0100