NAME

UR::BoolExpr - a "where clause" for objects

SYNOPSIS

    my $o = Acme::Employee->create(
        ssn => '123-45-6789',
        name => 'Pat Jones',
        status => 'active', 
        start_date => UR::Context->current->now,
        payroll_category => 'hourly',
    );    
        
    my $bx = Acme::Employee->define_boolexpr(
        payroll_category => 'hourly',
        status => ['active','terminated'],
        'name like' => '%Jones',
        'ssn matches' => '\d{3}-\d{2}-\d{4}',
        'start_date between' => ['2009-01-01','2009-02-01'],
    );
    
    $bx->evaluate($o); # true 
    
    $bx->specifies_value_for('payroll_category') # true 
    
    $bx->value_for('payroll_cagtegory') # 'hourly'
        
    $o->payroll_category('salary');
    $bx->evaluate($o); # false

    # these could take either a boolean expression, or a list of params
    # from which it will generate one on-the-fly
    my $set     = Acme::Employee->define_set($bx);  # same as listing all of the params
    my @matches = Acme::Employee->get($bx);         # same as above, but returns the members 
       

DESCRIPTION

A UR::BoolExpr object captures a set of match criteria for some class of object.

Calls to get(), create(), and define_set() all use this internally to objectify their paramters. If given a boolean expression object directly they will use it. Otherwise they will construct one from the parameters given.

They have a 1:1 correspondence within the WHERE clause in an SQL statement where RDBMS persistance is used. They also imply the FROM clause in these cases, since the query properties control which joins must be included to return the matching object set.

REFLECTION

The data used to create the rule can be re-extracted:

    my $c = $r->subject_class_name;
    # $c eq "GSC::Clone"

    my @p = $r->params_list;
    # @p = four items
    
    my %p = $r->params_list;
    # %p = two key value pairs

SUBCLASSES

 The ::Rule class is abstract, but the primary constructor (resolve_normalized_rule_for_class_and_params),
 automatically returns rules of the correct subclass for the specified parameters.  
 
 Currently it always returns a ::Rule::And object, which is the composite of all key-value pairs passed-in.
::Rule::And
 Rules of this type contain a list of other rules, ALL of which must be true for the given rule to be true.
 Inherits from the intermediate class ::Rule::Composite.
 
::Rule::Or
 Rules of this type contain a list of other rules, ANY of which must be true for the given rule to be true.
 Inherits from the intermediate class ::Rule::Composite.
::Rule::PropertyComparison
 Rules of this type compare a single property on the subject, using a specific comparison operator,
 against a specific value (or value set for certain operators).  This is the low-level non-composite rule.

CONSTRUCTOR

      my $bx = UR::BoolExpr->resolve('Some::Class', property_1 => 'value_1', ... property_n => 'value_n');
      my $bx1 = Some::Class->define_boolexpr(property_1 => value_1, ... property_n => 'value_n');
      my $bx2 = Some::Class->define_boolexpr('property_1 >' => 12345);

    Returns a UR::BoolExpr object that can be used to perform tests on the given class and properties. The default comparison for each property is equality. The last example shows using greater-than operator for property_1.

METHODS

evaluate
    $bx->($object)

Returns true if the given object satisfies the BoolExpr

template_and_values
  ($template, @values) = $bx->template_and_values();

Returns the UR::BoolExpr::Template and list of the values for the given BoolExpr

is_subset_of
  $bx->is_subset_of($other_bx)

Returns true if the set of objects that matches this BoolExpr is a subset of the set of objects that matches $other_bx. In practice this means:

  * The subject class of $bx isa the subject class of $other_bx
  * all the properties from $bx also appear in $other_bx
  * the operators and values for $bx's properties match $other_bx
values
  @values = $bx->values

Return a list of the values from $bx. The values will be in the same order the BoolExpr was created from

value_for_id
  $id = $bx->value_for_id

If $bx's properties include all the ID properties of its subject class, value_for_id returns that value. Otherwise, it returns the empty list. If the subject class has more than one ID property, this returns the value of the composite ID.

specifies_value_for
  $bx->specifies_value_for('property_name');

Returns true if the filter list of $bx includes the given property name

value_for
  my $value = $bx->value_for('property_name');

Return the value for the given property

operator_for
  my $operator = $bx->operator_for('property_name');

Return a string for the operator of the given property. A value of '' (the empty string) means equality ("="). Other possible values inclue '<', '>', '<=', '>=', 'between', 'true', 'false', 'in', 'not <', 'not >', etc.

INTERNAL STRUCTURE

A rule has an "id", which completely describes the rule in stringified form, and a method called evaluate($o) which tests the rule on a given object.

The id is composed of two parts: - A template_id. - A value_id.

Nearly all real work delegates to the template to avoid duplication of cached details.

The template_id embeds several other properties, for which the rule delegates to it: - subject_class_name, objects of which the rule can be applied-to - subclass_name, the subclass of rule (property comparison, and, or "or") - the body of the rule either key-op-val, or a list of other rules

For example, the rule GSC::Clone name=x,chromosome>y: - the template_id embeds: subject_class_name = GSC::Clone subclass_name = UR::BoolExpr::And and the key-op pairs in sorted order: "chromosome>,name=" - the value_id embeds the x,y values in a special format

EXAMPLES

my $bool = $x->evaluate($obj);

my $t = GSC::Clone->template_for_params( "status =", "chromosome []", "clone_name like", "clone_size between" );

my @results = $t->get_matching_objects( "active", [2,4,7], "Foo%", [100000,200000] );

my $r = $t->get_rule($v1,$v2,$v3);

my $t = $r->template;

my @results = $t->get_matching_objects($v1,$v2,$v3); my @results = $r->get_matching_objects();

@r = $r->underlying_rules(); for (@r) { print $r->evaluate($c1); }

my $rt = $r->template(); my @rt = $rt->get_underlying_rule_templates();

$r = $rt->get_rule_for_values(@v);

SEE ALSO

UR(3), UR::Object(3), UR::Object::Set(3), UR::BoolExpr::Template(3)

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 1013:

'=item' outside of any '=over'

Around line 1028:

You forgot a '=back' before '=head1'