/ 
SQL-OrderBy-0.06
River stage zero No dependents
/ SQL::OrderBy

NAME

SQL::OrderBy - Transform an SQL ORDER BY clause.

SYNOPSIS

use SQL::OrderBy;

# Array context
my @order = SQL::OrderBy::toggle_resort(
    selected => 'artist',
    order_by => [ qw(name artist album) ],
);
# ('artist asc', 'name asc', 'album asc')

# Scalar context
print scalar SQL::OrderBy::toggle_resort(
    selected => 'time',
    order_by => scalar SQL::OrderBy::toggle_resort(
        selected => 'artist',
        order_by => scalar SQL::OrderBy::toggle_resort(
            selected => 'artist',
            order_by => 'name, artist, album'
        )
    )
);
# 'time asc, artist desc, name asc, album asc'

ABSTRACT

Resort and toggle (ascending/descending) table columns given an SQL ORDER BY clause.

DESCRIPTION

This package simply transforms an SQL ORDER BY clause by moving or adding column names and toggling their ascending/descending state.

Note that this is intentionally naive code, in that no database integrity checking is done.

FUNCTIONS

toggle_resort()

toggle_resort(
    order_by => $order_clause_or_list,
    selected => $column_name,
)

This function takes two arguments provided as named parameters: an SQL "ORDER BY" clause as either a string or array reference and a column name.

The selected column name is moved or added to the beginning of the clause with its sort direction exposed. If this column is the first column of the list, it's sort direction is flipped between ascending (asc) and descending (desc).

Note that the state of the sort is maintained, since the selected column name is the only one that is fondled.

In a scalar context, this function returns the clause as a (CSV) string. In an array context, this function returns a list of column names with their respective sort directions.

This implements an essential feature for GUI environments, where the user interacts with a table by sorting and resorting with a mouse and "toggle button column headings" during an interactive search refinement session.

* If you leave off the selected argument, this function will simply return the clause with sort directions for each column name. That is, no "toggling" or moving is done.

* Currently, this function is not exported by default.

DEPENDENCIES

None.

TODO

Add functions for different kinds of resorting.

Add functions for handling different module statement objects.

HISTORY

0.01 Mon Feb 3 14:11:20 2003 - original version; created by h2xs 1.22 with options -X -n SQL::OrderBy

0.02 Mon Feb 3 2003 - Fixed/enhanced documentation.

0.03 Mon Feb 3 2003 - Ack! My synopsis!

0.04 Fri Feb 21 2003 - Renamed the resort() function. - Enhanced documentation.

0.05 Fri Feb 21 2003 - Made toggle_resort() accept an arrayref or string. - Added scalar/array context awareness. - Fixed/enhanced documentation.

0.06 Fri Feb 21 2003 - Ugh. Fixed my documentation again.

AUTHOR

Gene Boggs, <cpan@ology.net>

COPYRIGHT AND LICENSE

Copyright 2003 by Gene Boggs

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