NAME

Querylet::Query - renders and performs queries for Querylet

VERSION

version 0.402

SYNOPSIS

 use DBI;
 my $dbh = DBI->connect('dbi:Pg:dbname=drinks');
 
 use Querylet::Query;
 # Why am I using this package?  I'm a human, not Querylet!

 my $q = new Querylet::Query;

 $q->set_dbh($dbh);

 $q->set_query("
   SELECT *
   FROM   drinks d
   WHERE  abv > [% min_abv %]
     AND  ? IN (
            SELECT liquor FROM ingredients WHERE i i.drink_id = d.drink_id
          )
   ORDER BY d.name
 ");

 $q->set_query_vars({ min_abv => 25 });

 $q->bind("rum");

 $q->run;

 $q->output_type('html');

 $q->output;

DESCRIPTION

Querylet::Query is used by Querylet-generated code to make that code go. It renders templatized queries, executes them, and hangs on to the results until they're ready to go to output.

This module is probably not particularly useful outside of its use in code written by Querylet, but there you have it.

PERL VERSION SUPPORT

This code is effectively abandonware. Although releases will sometimes be made to update contact info or to fix packaging flaws, bug reports will mostly be ignored. Feature requests are even more likely to be ignored. (If someone takes up maintenance of this code, they will presumably remove this notice.)

METHODS

new

  Querylet::Query->new;

This creates and returns a new Querylet::Query.

set_dbh

  $q->set_dbh($dbh);

This method sets the database handle to be used for running the query.

set_query

  $q->set_query($query);

This method sets the query to run. The query may be a plain SQL query or a template to be rendered later.

bind

  $q->bind(@parameters);

This method sets the bind parameters, overwriting any existing parameters.

bind_more

  $q->bind_more(@parameters);

This method pushes the given parameters onto the list of bind parameters to use when executing the query.

set_query_vars

  $q->set_query_vars(\%variables);

This method sets the given variables, to be used when rendering the query. It also indicates that the query that was given is a template, and should be rendered. (In other words, if this method is called at least once, even with an empty hashref, the query will be considered a template, and rendered.)

Note that if query variables are set, but the template rendering engine can't be loaded, the program will die.

render_query

  $q->render_query;

This method renders the query using a templating engine (Template Toolkit, by default) and returns the result. This method is called internally by the run method, if query variables have been set.

Normal Querylet code will not need to call this method.

run

  $q->run;

This method runs the query and sets up the results. It is called internally by the results method, if the query has not yet been run.

Normal Querylet code will not need to call this method.

results

  $q->results;

This method returns the results of the query, first running the query (by calling run) if needed.

The results are returned as a reference to an array of rows, each row a reference to a hash. These are not copies, and may be altered in place.

set_results

  $q->set_results( \@new_results );

This method replaces the result set with the provided results. This method does not call the results method, so if the query has not been run, it will not be run by this method.

columns

  $q->columns;

This method returns the column names (as an arrayref) for the query's results. The query will first be run (by calling run) if needed.

set_columns

  $q->set_columns( \@new_columns );

This method replaces the list of column names for the current query result. It does not call the columns method, so if the query has not been run, it will not be run by this method.

header

  $q->header( $column );

This method returns the header name for the given column, or the column name, if none is defined.

set_headers

  $q->set_headers( \%headers );

This method sets up header names for columns. It's passed a list of column-header pairs, which it stores for lookup with the header method.

option

  $q->option($option_name);

This method returns the named option's value. At present, this just retrieves a scratchpad entry.

scratchpad

  $q->scratchpad;

This method returns a reference to a hash for general-purpose note-taking. I've put this here for really simple, mediocre communication between handlers. I'm tempted to warn you that it might go away, but I think it's unlikely.

input_type

  $q->input_type($type);

This method sets or retrieves the input type, which is used to find the input handler.

input

  $q->input($parameter);

This method tells the Query to ask the current input handler to request that the named parameter be received from input.

register_input_handler

  Querylet::Query->register_input_handler($type => \&handler);

This method registers an input handler routine for the given type.

If a type is registered that already has a handler, the old handler is quietly replaced. (This makes replacing the built-in, naive handlers quite painless.)

output_filename

  $q->output_filename($filename);

This method sets a filename to which output should be directed.

If called with no arguments, it returns the name. If called with undef, it unassigns the currently assigned filename.

write_type

  $q->write_type($type);

This method sets or retrieves the write-out method for the query.

output_type

  $q->output_type($type);

This method sets or retrieves the format of the output to be generated.

output

  $q->output;

This method tells the Query to send the current results to the proper output handler and return them. If the outputs have already been generated, they are not re-generated.

write

  $q->write;

This method tells the Query to send its formatted output to the writing handler and return them.

write_output

  $q->write_output;

This method tells the Query to write the query output. If no filename has been set for output, the results are just printed.

If the result of the output method is a coderef, the coderef will be evaluated and nothing will be printed.

register_output_handler

  Querylet::Query->register_output_handler($type => \&handler);

This method registers an output handler routine for the given type. (The prototype sort of documents itself, doesn't it?)

It can be called on an instance, too. It doesn't mind.

If a type is registered that already has a handler, the old handler is quietly replaced. (This makes replacing the built-in, naive handlers quite painless.)

as_csv

  as_csv($q);

This is the default, built-in output handler. It outputs the results of the query as a CSV file. That is, a series of comma-delimited fields, with each record separated by a newline.

If a output filename was specified, the output is sent to that file (unless it exists). Otherwise, it's printed standard output.

as_template

  as_template($q);

This is the default, built-in output handler. It outputs the results of the query by rendering a template using Template Toolkit. If the option "template_file" is set, the file named in that option is used as the template. If no template_file is set, a built-in template is used, generating a simple HTML document.

This handler is by default registered to the types "template" and "html".

register_write_handler

  Querylet::Query->register_write_handler($type => \&handler);

This method registers a write handler routine for the given type.

If a type is registered that already has a handler, the old handler is quietly replaced.

to_file

This write handler sends the output to a file on the disk.

to_stdout

This write handler sends the output to the currently selected output stream.

from_term($q, $parameter)

This is a simple built-in input handler to prompt the user interactively for parameter inputs. It is the default input handler.

SEE ALSO

Querylet, Querylet::Input, Querylet::Output

AUTHOR

Ricardo SIGNES <rjbs@semiotic.systems>

COPYRIGHT AND LICENSE

This software is copyright (c) 2004 by Ricardo SIGNES.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.