ColSpec format 'include_colspec'

The include_colspec attribute defines joins and columns to include. It consists of a list of "ColSpecs"

The ColSpec format is a string format consisting of consists of 2 parts: an optional 'relspec' followed by a 'colspec'. The last dot "." in the string separates the relspec on the left from the colspec on the right. A string without periods has no (or an empty '') relspec.

The relspec is a chain of relationship names delimited by dots. These must be exact relnames in the correct order. These are used to create the base DBIC join attr. For example, this relspec (to the left of .*):

object.owner.contact.*

Would become this join:

{ object => { owner => 'contact' } }

Multple overlapping rels are collapsed in an inteligent manner. For example, this:

object.owner.contact.*
object.owner.notes.*

Gets collapsed into this join:

{ object => { owner => [ 'contact', 'notes' ] } }

The colspec to the right of the last dot "." is a glob pattern match string to identify which columns of that last relationship to include. Standard simple glob wildcards * ? [ ] are supported (this is powered by the Text::Glob module. ColSpecs with no relspec apply to the base table/class. If no base colspecs are defined, '*' is assumed, which will include all columns of the base table (but not of any related tables).

Note that this ColSpec:

object.owner.contact

Would join { object => 'owner' } and include one column named 'contact' within the owner table.

This ColSpec, on the other hand:

object.owner.contact.*

Would join { object => { owner => 'contact' } } and include all columns within the contact table.

The ! chacter can exclude instead of include. It can only be at the start of the line, and it will cause the colspec to exclude columns that match the pattern. For the purposes of joining, ! ColSpecs are ignored.

EXAMPLE ColSpecs:

'name',
'!id',
'*',
'!*',
'project.*', 
'user.*',
'contact.notes.owner.foo*',
'contact.notes.owner.foo.sd',
'project.dist1.rsm.object.*_ts',
'relation.column',
'owner.*',
'!owner.*_*',