/ 
RapidApp-0.99650
River stage one • 5 direct dependents • 5 total dependents
/ RapidApp::DBIC::RelationTreeSpec

NAME

RapidApp::DBIC::RelationTreeSpec

SYNOPSIS

RapidApp::DBIC::RelationTreeSpec->new(
  source => $schema->source('Object'),
  colSpec => [ qw(
    col1 col2 col3 col4
    foo.*
    foo.bar.*
    baz.col1
    baz.col5
    blah.*
    -blah.internal
    -blah.secret
  )],
);

DESCRIPTION

This package describes a set of columns, and a set of utility methods to query which things are in the set. And thats all, really.

It lets you specify columns, wildcard "*" columns, and exclusions "-". You can specify the names of DBIC relations using dot notation, and they will be followed.

This package is used by other useful packages like RelationTreeExtractor and RelationTreeFlattener and DbicLink to reduce the burden of having to use awkward attributes to describe which columns should or should not be part of the result.

ATTRIBUTES

source : DBIx::Class::ResultSource

The result source that the column spec is relative to.

colSpec : array[scalar]

The exact structure that was passed to the constructor. It is read-only. ( in fact, this entire class is read-only )

colArray : array[array[scalar]]

An array of all columns, each as an arrayref of relation names followed by a column name.

The columns are each blessed as RapidApp::DBIC::ColPath, but feel free to use them as arrays.

This list is sorted alphabetically by relation and column name.

Example return value: [ bless([ 'foo', 'bar', 'col1' ], RapidApp::DBIC::ColPath), bless([ 'foo', 'bar', 'col2' ], RapidApp::DBIC::ColPath), bless([ 'id' ], RapidApp::DBIC::ColPath) ]

colList : list( array[scalar] )

This is simply the de-referenced $self->colArray. Handy when you want to iterate them.

colTree : hash[ rel => rel => ... => col => 1 ]

The tree of relations and columns that the spec refers to. This is the most definitive attribute, and the only one that is never lazily built.

Example return value: { foo => { bar => { col1 => 1, col2 => 1, }, }, id => 1 }

relTree : hash[ rel => rel => {} ]

Returns a tree of only the relations. Same as colTree, but minus the columns.

Example return value: { foo => { bar => {} } }

METHODS

$class->new( source => $optionalDbicSource, colSpec => \@colList )

Create a new RelationTreeSpec, from the colSpec, using the source to resolve wildcards.

(You can also pass "colTree" as a parameter, but make sure it is correctly built!)

$self->intersect( @spec || \@spec || $RelationTreeSpec )

Takes either a arrayref of column specifications, a direct list of column specifications, or another RelationTreeSpec object.

Calculates a new RelationTreeSpec object which is the intersection of the columns and relations in common between the two sets.

$self->union( @spec || \@spec || $relationTreeSpec )

Takes either a arrayref of column specifications, a direct list of column specifications, or another RelationTreeSpec object.

Calculates a new RelationTreeSpec object which includes all columns and relations of each.

$self->subtract( @spec || \@spec || $relationTreeSpec )

Takes either a arrayref of column specifications, a direct list of column specifications, or another RelationTreeSpec object.

Calculates a new RelationTreeSpec object which is the current spec's columns excluding any of the columns in the given spec.

$class->validateSpec( \@spec )

Returns the spec if it is valid. Throws an exception if it is not.

$colTree= $class->resolveSpec( $dbicSource, $colSpec )

Calculate a colTree from a colSpec.

This method is usually run during the constructor, but can be used externally to avoid creating objects and just cut to the chase.