package Template::Plugin::Handy;

use warnings;
use strict;
use base qw( Template::Plugin::VMethods );
use Carp;
use Data::Dump;
use JSON::XS;

our $VERSION = '0.003';

our @SCALAR_OPS = our @LIST_OPS = our @HASH_OPS
    = qw( as_json dump_stderr dump_data );
push( @SCALAR_OPS, qw( increment decrement ) );
push( @LIST_OPS,   qw( sort_by ) );
push( @HASH_OPS,   qw( sort_by ) );

=head1 NAME

Template::Plugin::Handy - handy vmethods for Template Toolkit


 [% USE Handy;


Handy virtual methods I always use in my Template Toolkit files,
especially for debugging.
=head1 METHODS

Only new or overridden method are documented here.


# package object
my $JSON = JSON::XS->new;

# mysql serial fields are rendered with Math::BigInt objects in RDBO.
# monkeypatch per JSON::XS docs
sub Math::BigInt::TO_JSON {
    my ($self) = @_;
    return $self . '';

# same with URI objets
sub URI::TO_JSON {
    my ($uri) = @_;
    return $uri . '';

=head2 dump_data

Replacement for the Dumper plugin. You can call this method on any variable
to see its Data::Dump representation in HTML-safe manner.

 [% myvar.dump_data %]

# virt method replacements for Dumper plugin
sub dump_data {
    my $s = shift;
    my $d = Data::Dump::dump($s);
    $d =~ s/&/&/g;
    $d =~ s/</&lt;/g;
    $d =~ s/>/&gt;/g;
    $d =~ s,\n,<br/>\n,g;
    return "<pre>$d</pre>";

=head2 dump_stderr

Like dump_data but prints to STDERR instead of returning HTML-escaped string.
Returns undef.


sub dump_stderr {
    my $s = shift;
    print STDERR Data::Dump::dump($s);

=head2 as_json

Encode the variable as a JSON string. Wrapper around the JSON->encode method.
The string will be encoded as UTF-8, and the special JSON flags for converted_blessed
and allow_blessed are C<true> by default.


sub as_json {
    my $v = shift;
    if (@_) {
    my $j = $JSON->encode($v);
    if (@_) {
    return $j;

=head2 increment( I<n> )

Increment a scalar number by one.
Aliased as a scalar vmethod as 'inc'.


sub increment {

=head2 decrement( I<n> )

Decrement a scalar number by one.
Aliased as a scalar vmethod as 'dec'.


sub decrement {

=head2 sort_by( I<method_name> )

Sort an array or hash ref of objects according to I<method_name>. The
sort assumes a C<cmp> comparison and the return value of I<method_name>
is run through lc() first.

Returns a new sorted arrayref.


sub sort_by {
    my $stuff  = shift;
    my $method = shift;
    if ( ref $stuff eq 'HASH' ) {
        return [
            sort {
                lc( $stuff->{$a}->$method ) cmp lc( $stuff->{$b}->$method )
                } keys %$stuff
    elsif ( ref $stuff eq 'ARRAY' ) {
        return [ sort { lc( $a->$method ) cmp lc( $b->$method ) } @$stuff ];
    elsif ( ref $stuff ) {

        # might be a single blessed object
        return $stuff;
    else {
        croak "sort_by only works with ARRAY or HASH references";




=head1 AUTHOR

Peter Karman, C<< <> >>

=head1 BUGS

Please report any bugs or feature requests to
C<>, or through the web interface at
L<>.  I will be notified, and then you'll automatically be
notified of progress on your bug as I make changes.


The Minnesota Supercomputing Institute C<< >>
sponsored the development of this software.


Copyright 2008 by the Regents of the University of Minnesota.

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