Ben Sommer

NAME

Myco::Query::Part::Filter - a Myco entity class

SYNOPSIS

  use Myco;

  # Constructors. See Myco::Entity for more.
  my $filter = Myco::Query::Part::Filter->new;

  $filter->set_relevance( 1 ); # this filter is relevant to the query,
                               # required, even

  $filter->set_parts(
                      [
                        # starting with just one part...

                        { remote => '$sample_base_entity_',
                          attr => 'chicken',
                          oper => '==',
                          param => '$params{chk}' }
                      ]
                    );

  # Note that 'set_parts' accepts a precompiled (see below) filter or clause
  # object or just an attribute hash that is constructor-friendly.

  # See Myco::Entity::SampleEntity for more on this 'poultry' example

  # We must be able to nest filters inside of other filters, ad infinitum.
  my $parent_filter = Myco::Query::Part::Filter->new
                        ( relevance => 0,
                          parts => [ $filter ], # here we're passing in a
                                                # pre-compiled filter object
                        );

  # See below for examples of instance methods

DESCRIPTION

This class of object encapsulates Tangram::Filter objects. It stores metadata about the filter object, facilitates the addition and removal of metadata, and gathers the metadata together when the time comes for Myco::QueryTemplate to render these objects into usable Tangram query filters when a query is run. A key feature of this class is to recursively include other Myco::Query::Part::Filter objects into each other, via the parts attribute.

COMMON ENTITY INTERFACE

Constructor, accessors, and other methods -- as inherited from Myco::Entity.

ATTRIBUTES

Attributes may be initially set during object construction (with new()) but otherwise are accessed solely through accessor methods. Typical usage:

  • Set attribute value

     $obj->set_attribute($value);

    Check functions (see Class::Tangram) perform data validation. If there is any concern that the set method might be called with invalid data then the call should be wrapped in an eval block to catch exceptions that would result.

  • Get attribute value

     $value = $obj->get_attribute;

A listing of available attributes follows:

parts

 type: transient

An array reference of the parts of the query filter. These parts consist of clauses and (potentially) other filter objects.

relevance

 type: transient - boolean (1 | 0)

A boolean attribute that determines if a Filter is 'relevant', i.e. whether its inclusion in a query should be by default even if none of the params relevant to it were passed at query-run-time. On its own, this attribute is useless. To dynamically determine if a filter is relevant just prior to query-run-time, use $filter->is_relevant( %query_run_params ).

ADDED CLASS / INSTANCE METHODS

add_part

  $query_filter->add_part( $query_part );

Pushes a Myco::Query::Part object onto the end of the parts array.

remove_part

  $query_filter->remove_part( $query_part );

Deletes a Myco::Query::Part object from the parts array. Accpets and object reference or an object ID.

get_combined_parts

  my $filter_string = $query_filter->get_combined_parts;

Returns all the filter parts into a string.

is_relevant

  my $is_relevant = $query_filter->is_relevant( \%query_run_time_params );

Calculates whether this filter is relevant to its containing query - i.e. its clauses having to do with 'remote' object comparison will be ignored if their attendant paramters were not passed to run_query.

LICENSE AND COPYRIGHT

Copyright (c) 2006 the myco project. All rights reserved. This software is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Myco::Query::Part::Filter::Test, Myco::Entity, Myco, Tangram, Class::Tangram, myco-mkentity