=pod

=encoding utf-8

=for :stopwords Randy Stauner ACKNOWLEDGEMENTS dbh sql resultset TODO arrayrefs cpan
testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto
metadata placeholders metacpan

=head1 NAME

DBIx::RoboQuery - Very configurable/programmable query object

=head1 VERSION

version 0.032

=head1 SYNOPSIS

  my $template_string = < 'birthday'});
  %]
    SELECT
      name,
      user_id,
      dob as birthday,
      favorite_smell
    FROM users
    WHERE dob < [% query.bind(minimum_birthdate()) %]
  SQL

  # create query object from template
  my $query = DBIx::RoboQuery->new(
    sql => $template_string,       # (or use file => $filepath)
    dbh => $dbh,                   # handle returned from DBI->connect()
    transformations => {           # functions available for transformation
      format_date => \&arbitrary_date_format,
      trim => sub { (my $s = $_[0]) =~ s/^\s+|\s+$//g; $s },
    },
    variables => {                 # variables for use in template
      minimum_birthdate => \&arbitrary_date_function,
    }
  );

  # transformations (and other configuration) can be specified in the sql
  # template or in your code if you know you'll always want certain ones
  $query->transform('trim', group => 'non_key_columns');

  my $resultset = $query->resultset;

  $resultset->execute;
  my @non_key = $resultset->non_key_columns;
  # do something where i want to know the difference between key and non-key columns

  # get records (with transformations applied and specified columns dropped)
  my $records = $resultset->hash;            # like DBI/fetchall_hashref
  # OR: my $records = $resultset->array;     # like DBI/fetchall_arrayref

=head1 DESCRIPTION

This robotic query object can be configured to help you
get exactly the result set that you want.

It was designed to run in a completely automated (unmanned) environment and
read in a template that both builds the desired SQL query dynamically
and configures the query output.
It should be usable anywhere you desire
a highly configurable query and result set.

It (and its companion L)
provide various methods for configuring/declaring
what to expect and what to return.
It aims to be as informative as you might need it to be.

The following enhancements are possible:

=over 4

=item *

The query can be built with templates
(currently L)
which allows for perl variables and functions
to interpolate and/or generate the SQL

=item *

The output can be transformed (using L).
You can specify multiple transformations per field
and you can specify transformations that operate on the whole row.
This way you can set the value of one field based on the value of another.

See L (and the C shortcuts),
L,
C (in L)
and L
for more information.

=item *

TODO: list more

=back

See note about L.

=head1 METHODS

=head2 new

  my $query = DBIx::RoboQuery->new(%opts); # or \%opts

Constructor;  Accepts a hash or hashref of options:

=over 4

=item *

C

The SQL query [template] in a string;
This can be a reference to a string in case your template [query]
is large and it makes you feel better to pass it by reference.

=item *

C

The file path of a SQL query [template] (mutually exclusive with C)

=item *

C

A database handle (the return of C<< DBI->connect() >>)

=item *

C

The default slice of the records returned;
It is not used by the query but merely passed to the ResultSet object.
See L.

=item *

C

An arrayref of columns to be dropped from the resultset;  See L.

=item *

C

An arrayref of [primary key] column names;  See L.

=item *

C

An arrayref of column names to specify the sort order;  See L.

=item *

C

A string to be prepended to the SQL before parsing the template

=item *

C

Boolean; If enabled, empty lines (or lines with only whitespace)
will be removed from the compiled template.
This can make it easier to look at sql that has a lot of template directives.
(Disabled by default.)

=item *

C

A string to be appended  to the SQL before parsing the template

=item *

C

A hashref of options that will be merged into the options to
L<< Template->new()|Template >>
You can use this to overwrite the default options, but be sure to use the
C options rather than including C in this hash
unless you don't want the default variables to be available to the template.

=item *

C

B

This is a regexp (which defaults to C<$Template::Stash::PRIVATE>
(which defaults to C)).
Any template variables that match will not be accessible in the template
(but will return undef, which will throw an error under C mode).
If you want to access "private" variables (including "private" hash keys)
in your templates (the main query template or any templates passed to L)
you should set this to C to tell L