« lib/Google/Ads/AdWords/Utilities/BatchJobHandlerStatus.pm
↑ Summary
lib/Google/Ads/AdWords/v201809/AccountLabelService/AccountLabelServiceInterfacePort.pm »
| 1 | # Copyright 2018, Google Inc. All Rights Reserved. | ||
| 2 | # | ||
| 3 | # Licensed under the Apache License, Version 2.0 (the "License"); | ||
| 4 | # you may not use this file except in compliance with the License. | ||
| 5 | # You may obtain a copy of the License at | ||
| 6 | # | ||
| 7 | # http://www.apache.org/licenses/LICENSE-2.0 | ||
| 8 | # | ||
| 9 | # Unless required by applicable law or agreed to in writing, software | ||
| 10 | # distributed under the License is distributed on an "AS IS" BASIS, | ||
| 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| 12 | # See the License for the specific language governing permissions and | ||
| 13 | # limitations under the License. | ||
| 14 | # | ||
| 15 | # This utility is a query builder for building AWQL (AdWords Query Language) | ||
| 16 | # queries. This module shouldn't be instantiated directly or extended. | ||
| 17 | # Use ReportQueryBuilder if you want to create a query for reporting or | ||
| 18 | # ServiceQueryBuilder if you want to create a query for services. | ||
| 19 | |||
| 20 | package Google::Ads::AdWords::Utilities::QueryBuilder; | ||
| 21 | |||
| 22 | 2 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 23 | 2 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 24 | 2 | ▶ | use utf8; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 25 | 2 | ▶ | use version; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 26 | |||
| 27 | # The following needs to be on one line because CPAN uses a particularly hacky | ||
| 28 | # eval() to determine module versions. | ||
| 29 | 2 | ▶ | use Google::Ads::AdWords::Constants; our $VERSION = ${Google::Ads::AdWords::Constants::VERSION}; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 30 | |||
| 31 | 2 | ▶ | use Class::Std::Fast; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 32 | |||
| 33 | 1 | my %client_of : ATTR(:name<client> :default<>); | |
| 34 | 1 | my %die_on_faults_of : ATTR(:name<die_on_faults> :default<1>); | |
| 35 | 1 | my %query_builder_of : ATTR(:name<query_builder> :default<>); | |
| 36 | 1 | my %where_builders_of : ATTR(:name<where_builders> :default<[]>); | |
| 37 | |||
| 38 | sub START { | ||
| 39 | my ($self) = @_; | ||
| 40 | |||
| 41 | $self->set_die_on_faults(( | ||
| 42 | defined($self->get_client()) and $self->get_client()->get_die_on_faults() | ||
| 43 | ) ? 1 : 0 | ||
| 44 | ); | ||
| 45 | |||
| 46 | if ($self->get_query_builder()) { | ||
| 47 | push( | ||
| 48 | @{$self->get_where_builders()}, | ||
| 49 | @{$self->get_query_builder()->get_where_builders()}); | ||
| 50 | } | ||
| 51 | return $self; | ||
| 52 | } | ||
| 53 | |||
| 54 | # The specified list of fields to be added to a SELECT clause. | ||
| 55 | # Returns a query builder. | ||
| 56 | sub select { | ||
| 57 | my ($self, $fields) = @_; | ||
| 58 | $self->_log_error( | ||
| 59 | "Not implemented: Use ReportQueryBuilder or ServiceQueryBuilder."); | ||
| 60 | } | ||
| 61 | |||
| 62 | # Creates a WHERE builder using a provided field. | ||
| 63 | # The created WHERE builder. | ||
| 64 | sub where { | ||
| 65 | my ($self, $field) = @_; | ||
| 66 | |||
| 67 | my $where_builder = | ||
| 68 | Google::Ads::AdWords::Utilities::QueryBuilder::WhereBuilder->new({ | ||
| 69 | field => $field, | ||
| 70 | current_query_builder => $self | ||
| 71 | }); | ||
| 72 | push(@{$self->get_where_builders()}, $where_builder); | ||
| 73 | return $where_builder; | ||
| 74 | } | ||
| 75 | |||
| 76 | # Log the error based on the configuration for die on faults. | ||
| 77 | sub _log_error { | ||
| 78 | my ($self, $error) = @_; | ||
| 79 | if ($self->get_die_on_faults()) { | ||
| 80 | die($error); | ||
| 81 | } else { | ||
| 82 | warn($error); | ||
| 83 | } | ||
| 84 | } | ||
| 85 | |||
| 86 | # A WHERE builder for building a WHERE clause in AWQL queries. | ||
| 87 | # This class should be instantiated through _QueryBuilder.Where. Don't call this constructor directly. | ||
| 88 | # | ||
| 89 | # Returns the WHERE builder | ||
| 90 | package Google::Ads::AdWords::Utilities::QueryBuilder::WhereBuilder; | ||
| 91 | |||
| 92 | 2 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 93 | 2 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 94 | 2 | ▶ | use utf8; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 95 | 2 | ▶ | use version; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 96 | |||
| 97 | # The following needs to be on one line because CPAN uses a particularly hacky | ||
| 98 | # eval() to determine module versions. | ||
| 99 | 2 | ▶ | use Google::Ads::AdWords::Constants; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 100 | 1 | our $VERSION = ${Google::Ads::AdWords::Constants::VERSION}; | |
| 101 | |||
| 102 | 2 | ▶ | use Class::Std::Fast; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 103 | |||
| 104 | 1 | my %current_query_builder_of : ATTR(:name<current_query_builder> :default<>); | |
| 105 | 1 | my %field_of : ATTR(:name<field> :default<>); | |
| 106 | 1 | my %awql_of : ATTR(:name<awql> :default<>); | |
| 107 | |||
| 108 | # Sets the type of the WHERE clause as "equal to". | ||
| 109 | # Args: | ||
| 110 | # value: The value to be used in the WHERE condition. | ||
| 111 | # Returns: The query builder that this WHERE builder links to. | ||
| 112 | sub equal_to { | ||
| 113 | my ($self, $value) = @_; | ||
| 114 | $self->set_awql($self->_create_single_value_condition($value, '=')); | ||
| 115 | return $self->get_current_query_builder(); | ||
| 116 | } | ||
| 117 | |||
| 118 | # Sets the type of the WHERE clause as "not equal to". | ||
| 119 | # Args: | ||
| 120 | # value: The value to be used in the WHERE condition. | ||
| 121 | # Returns: The query builder that this WHERE builder links to. | ||
| 122 | sub not_equal_to { | ||
| 123 | my ($self, $value) = @_; | ||
| 124 | $self->set_awql($self->_create_single_value_condition($value, '!=')); | ||
| 125 | return $self->get_current_query_builder(); | ||
| 126 | } | ||
| 127 | |||
| 128 | # Sets the type of the WHERE clause as "greater than". | ||
| 129 | # Args: | ||
| 130 | # value: The value to be used in the WHERE condition. | ||
| 131 | # Returns: The query builder that this WHERE builder links to. | ||
| 132 | sub greater_than { | ||
| 133 | my ($self, $value) = @_; | ||
| 134 | $self->set_awql($self->_create_single_value_condition($value, '>')); | ||
| 135 | return $self->get_current_query_builder(); | ||
| 136 | } | ||
| 137 | # Sets the type of the WHERE clause as "greater than or equal to". | ||
| 138 | # Args: | ||
| 139 | # value: The value to be used in the WHERE condition. | ||
| 140 | # Returns: The query builder that this WHERE builder links to. | ||
| 141 | sub greater_than_or_equal_to { | ||
| 142 | my ($self, $value) = @_; | ||
| 143 | $self->set_awql($self->_create_single_value_condition($value, '>=')); | ||
| 144 | return $self->get_current_query_builder(); | ||
| 145 | } | ||
| 146 | |||
| 147 | # Sets the type of the WHERE clause as "less than". | ||
| 148 | # Args: | ||
| 149 | # value: The value to be used in the WHERE condition. | ||
| 150 | # Returns: The query builder that this WHERE builder links to. | ||
| 151 | sub less_than { | ||
| 152 | my ($self, $value) = @_; | ||
| 153 | $self->set_awql($self->_create_single_value_condition($value, '<')); | ||
| 154 | return $self->get_current_query_builder(); | ||
| 155 | } | ||
| 156 | |||
| 157 | # Sets the type of the WHERE clause as "less than or equal to”. | ||
| 158 | # Args: | ||
| 159 | # value: The value to be used in the WHERE condition. | ||
| 160 | # Returns: The query builder that this WHERE builder links to. | ||
| 161 | sub less_than_or_equal_to { | ||
| 162 | my ($self, $value) = @_; | ||
| 163 | $self->set_awql($self->_create_single_value_condition($value, '<=')); | ||
| 164 | return $self->get_current_query_builder(); | ||
| 165 | } | ||
| 166 | |||
| 167 | # Sets the type of the WHERE clause as "starts with". | ||
| 168 | # Args: | ||
| 169 | # value: The value to be used in the WHERE condition. | ||
| 170 | # Returns: The query builder that this WHERE builder links to. | ||
| 171 | sub starts_with { | ||
| 172 | my ($self, $value) = @_; | ||
| 173 | $self->set_awql($self->_create_single_value_condition($value, 'STARTS_WITH')); | ||
| 174 | return $self->get_current_query_builder(); | ||
| 175 | } | ||
| 176 | |||
| 177 | # Sets the type of the WHERE clause as "starts with ignore case". | ||
| 178 | # Args: | ||
| 179 | # value: The value to be used in the WHERE condition. | ||
| 180 | # Returns: The query builder that this WHERE builder links to. | ||
| 181 | sub starts_with_ignore_case { | ||
| 182 | my ($self, $value) = @_; | ||
| 183 | $self->set_awql( | ||
| 184 | $self->_create_single_value_condition($value, 'STARTS_WITH_IGNORE_CASE')); | ||
| 185 | return $self->get_current_query_builder(); | ||
| 186 | } | ||
| 187 | |||
| 188 | # Sets the type of the WHERE clause as "contains". | ||
| 189 | # Args: | ||
| 190 | # value: The value to be used in the WHERE condition. | ||
| 191 | # Returns: The query builder that this WHERE builder links to. | ||
| 192 | sub contains { | ||
| 193 | my ($self, $value) = @_; | ||
| 194 | $self->set_awql($self->_create_single_value_condition($value, 'CONTAINS')); | ||
| 195 | return $self->get_current_query_builder(); | ||
| 196 | } | ||
| 197 | |||
| 198 | # Sets the type of the WHERE clause as "contains ignore case". | ||
| 199 | # Args: | ||
| 200 | # value: The value to be used in the WHERE condition. | ||
| 201 | # Returns: The query builder that this WHERE builder links to. | ||
| 202 | sub contains_ignore_case { | ||
| 203 | my ($self, $value) = @_; | ||
| 204 | $self->set_awql( | ||
| 205 | $self->_create_single_value_condition($value, 'CONTAINS_IGNORE_CASE')); | ||
| 206 | return $self->get_current_query_builder(); | ||
| 207 | } | ||
| 208 | |||
| 209 | # Sets the type of the WHERE clause as "does not contain". | ||
| 210 | # Args: | ||
| 211 | # value: The value to be used in the WHERE condition. | ||
| 212 | # Returns: The query builder that this WHERE builder links to. | ||
| 213 | sub does_not_contain { | ||
| 214 | my ($self, $value) = @_; | ||
| 215 | $self->set_awql( | ||
| 216 | $self->_create_single_value_condition($value, 'DOES_NOT_CONTAIN')); | ||
| 217 | return $self->get_current_query_builder(); | ||
| 218 | } | ||
| 219 | |||
| 220 | # Sets the type of the WHERE clause as "does not contain ignore case". | ||
| 221 | # Args: | ||
| 222 | # value: The value to be used in the WHERE condition. | ||
| 223 | # Returns: The query builder that this WHERE builder links to. | ||
| 224 | sub does_not_contain_ignore_case { | ||
| 225 | my ($self, $value) = @_; | ||
| 226 | $self->set_awql( | ||
| 227 | $self->_create_single_value_condition( | ||
| 228 | $value, 'DOES_NOT_CONTAIN_IGNORE_CASE' | ||
| 229 | )); | ||
| 230 | return $self->get_current_query_builder(); | ||
| 231 | } | ||
| 232 | |||
| 233 | # Sets the type of the WHERE clause as "in". | ||
| 234 | # Args: | ||
| 235 | # values: The values to be used in the WHERE condition. | ||
| 236 | # Returns: The query builder that this WHERE builder links to. | ||
| 237 | sub in { | ||
| 238 | my ($self, $values) = @_; | ||
| 239 | $self->set_awql($self->_create_multiple_values_condition($values, 'IN')); | ||
| 240 | return $self->get_current_query_builder(); | ||
| 241 | } | ||
| 242 | |||
| 243 | # Sets the type of the WHERE clause as "in". | ||
| 244 | # Args: | ||
| 245 | # values: The values to be used in the WHERE condition. | ||
| 246 | # Returns: The query builder that this WHERE builder links to. | ||
| 247 | sub not_in { | ||
| 248 | my ($self, $values) = @_; | ||
| 249 | $self->set_awql($self->_create_multiple_values_condition($values, 'NOT_IN')); | ||
| 250 | return $self->get_current_query_builder(); | ||
| 251 | } | ||
| 252 | |||
| 253 | # Sets the type of the WHERE clause as "contains any". | ||
| 254 | # Args: | ||
| 255 | # values: The values to be used in the WHERE condition. | ||
| 256 | # Returns: The query builder that this WHERE builder links to. | ||
| 257 | sub contains_any { | ||
| 258 | my ($self, $values) = @_; | ||
| 259 | $self->set_awql( | ||
| 260 | $self->_create_multiple_values_condition($values, 'CONTAINS_ANY')); | ||
| 261 | return $self->get_current_query_builder(); | ||
| 262 | } | ||
| 263 | |||
| 264 | # Sets the type of the WHERE clause as "contains none". | ||
| 265 | # Args: | ||
| 266 | # values: The values to be used in the WHERE condition. | ||
| 267 | # Returns: The query builder that this WHERE builder links to. | ||
| 268 | sub contains_none { | ||
| 269 | my ($self, $values) = @_; | ||
| 270 | $self->set_awql( | ||
| 271 | $self->_create_multiple_values_condition($values, 'CONTAINS_NONE')); | ||
| 272 | return $self->get_current_query_builder(); | ||
| 273 | } | ||
| 274 | |||
| 275 | # Sets the type of the WHERE clause as "contains all". | ||
| 276 | # Args: | ||
| 277 | # values: The values to be used in the WHERE condition. | ||
| 278 | # Returns: The query builder that this WHERE builder links to. | ||
| 279 | sub contains_all { | ||
| 280 | my ($self, $values) = @_; | ||
| 281 | $self->set_awql( | ||
| 282 | $self->_create_multiple_values_condition($values, 'CONTAINS_ALL')); | ||
| 283 | return $self->get_current_query_builder(); | ||
| 284 | } | ||
| 285 | |||
| 286 | # Builds the WHERE clause by returning the stored AWQL. | ||
| 287 | # Returns: The resulting WHERE clause in AWQL format. | ||
| 288 | sub build { | ||
| 289 | my ($self) = @_; | ||
| 290 | return $self->get_awql(); | ||
| 291 | } | ||
| 292 | |||
| 293 | # Creates a single-value condition with the provided value and operator. | ||
| 294 | sub _create_single_value_condition { | ||
| 295 | my ($self, $value, $operator) = @_; | ||
| 296 | # Put a single quote around strings, but leave numbers alone. | ||
| 297 | $value = ($value & ~$value) ? sprintf('"%s"', $value) : $value; | ||
| 298 | return sprintf("%s %s %s", $self->get_field(), $operator, $value); | ||
| 299 | } | ||
| 300 | |||
| 301 | # Creates a condition with the provided list of values and operator. | ||
| 302 | sub _create_multiple_values_condition { | ||
| 303 | my ($self, $values, $operator) = @_; | ||
| 304 | foreach my $value (@{$values}) { | ||
| 305 | $value = ($value =~ /^\d+$/) ? $value : sprintf('"%s"', $value); | ||
| 306 | } | ||
| 307 | return | ||
| 308 | sprintf("%s %s [%s]", $self->get_field(), $operator, join(",", @{$values})); | ||
| 309 | } | ||
| 310 | |||
| 311 | 1 | 1; | |
| 312 | |||
| 313 | =pod | ||
| 314 | |||
| 315 | =head1 NAME | ||
| 316 | |||
| 317 | Google::Ads::AdWords::Utilities::QueryBuilder | ||
| 318 | |||
| 319 | =head1 DESCRIPTION | ||
| 320 | |||
| 321 | This utility is a query builder for building AWQL (AdWords Query | ||
| 322 | Language) queries. This module shouldn't be instantiated directly or extended. | ||
| 323 | Use ReportQueryBuilder if you want to create a query for reporting or the | ||
| 324 | ServiceQueryBuilder if you want to create service queries. | ||
| 325 | |||
| 326 | =head1 ATTRIBUTES | ||
| 327 | |||
| 328 | The attributes may be set in new() and accessed using get_ATTRIBUTE | ||
| 329 | methods: | ||
| 330 | |||
| 331 | =head2 client | ||
| 332 | |||
| 333 | Google::Ads::AdWords::Client is used to find out if we should die on faults. | ||
| 334 | |||
| 335 | =head2 die_on_faults | ||
| 336 | |||
| 337 | Set to true if we are requested to die on faults in | ||
| 338 | Google::Ads::AdWords::Client. | ||
| 339 | |||
| 340 | =head2 query_builder | ||
| 341 | |||
| 342 | Google::Ads::AdWords::Utilities::QueryBuilder is the current builder. | ||
| 343 | |||
| 344 | =head2 where_builders | ||
| 345 | |||
| 346 | An array of incline package | ||
| 347 | Google::Ads::AdWords::Utilities::QueryBuilder::WhereBuilder. | ||
| 348 | |||
| 349 | =back | ||
| 350 | |||
| 351 | =head1 METHODS | ||
| 352 | |||
| 353 | =head2 new | ||
| 354 | |||
| 355 | Constructor. The following data structure may be passed to new(): | ||
| 356 | |||
| 357 | { # Google::Ads::AdWords::Utilities::QueryBuilder | ||
| 358 | client # Required: Google::Ads::AdWords::Client | ||
| 359 | query_builder # Optional: the Google::Ads::AdWords::Utilities::QueryBuilder | ||
| 360 | # to be copied | ||
| 361 | }, | ||
| 362 | |||
| 363 | =head1 METHODS | ||
| 364 | |||
| 365 | =head2 select | ||
| 366 | |||
| 367 | Sets the specified list of fields to be added to a SELECT clause. | ||
| 368 | |||
| 369 | =head3 Parameters | ||
| 370 | |||
| 371 | =over | ||
| 372 | |||
| 373 | =item * | ||
| 374 | |||
| 375 | A reference to an array of fields selected. Not implemented. | ||
| 376 | |||
| 377 | =back | ||
| 378 | |||
| 379 | =head3 Returns | ||
| 380 | |||
| 381 | A query builder (this instance). | ||
| 382 | |||
| 383 | =head2 where | ||
| 384 | |||
| 385 | Set the filters in the WHERE clause for the query. | ||
| 386 | |||
| 387 | =head3 Parameters | ||
| 388 | |||
| 389 | =over | ||
| 390 | |||
| 391 | =item * | ||
| 392 | |||
| 393 | The name of the field to be filtered on. | ||
| 394 | |||
| 395 | =back | ||
| 396 | |||
| 397 | =head3 Returns | ||
| 398 | |||
| 399 | A query builder (this instance). | ||
| 400 | |||
| 401 | =cut | ||