Ricardo SIGNES > Querylet-0.324 > Querylet::Query

Download:
Querylet-0.324.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.324   Source   Latest Release: Querylet-0.401

NAME ^

Querylet::Query - renders and performs queries for Querylet

VERSION ^

version 0.324

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.

METHODS ^

Querylet::Query->new

This creates and returns a new Querylet::Query.

$q->set_dbh($dbh)

This method sets the database handle to be used for running the 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.

$q->bind(@parameters)

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

$q->bind_more(@parameters)

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

$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.

$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.

$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.

$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.

$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.

$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.

$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.

$q->header( $column )

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

$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.

$q->option($option_name)

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

$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.

$q->input_type($type)

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

$q->input($parameter)

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

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.)

$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.

$q->write_type($type)

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

$q->output_type($type)

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

$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.

$q->write

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

$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.

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($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

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".

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@cpan.org>

BUGS ^

Please report any bugs or feature requests to bug-querylet@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT ^

Copyright 2004 Ricardo SIGNES, All Rights Reserved.

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

syntax highlighting: