—

              
package Valiant::HTML::SafeString;
use warnings;
use strict;
use Exporter 'import';
use HTML::Escape ();
use Scalar::Util (); 
use Carp;
use overload 
  bool => sub { shift->to_bool }, 
  '""' => sub { shift->to_string },
  '+' => sub {
    my ($self, $other, $reverse) = @_;
    croak "Can only join two safe string objects" unless (ref($other) eq ref($self));
   
    return $reverse
        ? raw("${other}${self}")
        : raw("${self}${other}");
  },
  fallback => 1;
our @EXPORT_OK = qw(raw flattened_raw safe flattened_safe is_safe escape_html safe_concat concat);
our %EXPORT_TAGS = (all => \@EXPORT_OK, core => ['raw', 'safe', 'escape_html', 'safe_concat']);
sub _make_safe {
  my $string_to_make_safe = shift;
  return bless(\$string_to_make_safe, 'Valiant::HTML::SafeString');
}
sub escape_html {
  my $string = shift;
  return HTML::Escape::escape_html($string);
}
sub raw {
  if(scalar(@_) == 1) {
    return is_safe($_[0]) ? $_[0] : _make_safe($_[0])
  } else {
    return map { is_safe($_) ? $_ : _make_safe($_) } @_;
  }
}
sub flattened_raw {
  my $string = join '', map { is_safe($_) ? $_->to_string : $_ } @_;
  return _make_safe $string;
}
sub is_safe {
  my $string_to_test = shift;
  return 0 unless defined($string_to_test); # must be defined
  return 0 unless Scalar::Util::blessed($string_to_test); # must be a blessed object
  return 1 if $string_to_test->isa('Valiant::HTML::SafeString'); # must be a blessed object of the right class
  return 0;
}
sub safe {
  if(scalar(@_) == 1) {
    return is_safe($_[0]) ? $_[0] : _make_safe(escape_html($_[0]))
  } else {
    return map { is_safe($_) ? $_ : _make_safe(escape_html($_)) } @_;
  }
}
sub safe_concat { return flattened_safe(@_) }
sub flattened_safe {
  my $string = join '', map { is_safe($_) ? $_->to_string : escape_html($_) } grep { defined($_) } @_;
  return _make_safe $string;
}
sub new {
  my $class = shift;
  return flattened_safe(@_);
}
sub concat { return flattened_safe(@_) }
sub to_string { return ${$_[0]} }
sub to_bool { return ${$_[0]} ? 1 : 0 }
sub append {
  my ($self, @rest) = @_;
  my $string = join '', map { is_safe($_) ? $_->to_string : escape_html($_) } grep { defined($_) } @rest;
  ${$self} .= $string;
}
1;
HideShow 97 lines of Pod
=head1 NAME
Valiant::HTML::SafeString - String rendering safety
=head1 SYNOPSIS
  use Valiant::HTML::SafeString 'safe', 'escape';
=head1 DESCRIPTION
Protecting your templates from the various types of character injection attacks is
a prime concern for anyone working with the HTML user interface.  This class provides
some methods and exports to make this job easier.
=head1 EXPORTABLE FUNCTIONS
The following functions can be exported by this library
=head2 safe
Given a string or array, returns such marked as 'safe' by using C<html_escape> on the string and
then encapsulating it inside an instance of L<Valiant::HTML::SafeString>. You can safely pass arguments
to this since if the string is already marked safe we just return it unaltered.
=head2 flattened_safe
Same as C<safe> but always returns a string even if you pass an array of strings (they are all
joined together).
=head2 raw
Given a string or array of strings, return each marked as safe (by encapsulating it inside an
instance of L<Valiant::HTML::SafeString>.  This will just mark strings as safe without doing any
escaping first (for that see C<safe>) so be careful with this.
=head2 flattened_raw
Same as C<raw> but always returns a string even if you pass an array of strings (they are all
joined together).
=head2 is_safe
Given a string return a boolean indicating if its marked safe or not.  Since C<safe> and C<raw> never
double the escapulations / escaping, you probably never need this but saw no reason to not expose it.
=head2 escape_html
A wrapper on L<HTML::Escape> just to make your life a bit easier
=head1 CLASS METHODS
This package exposes the folllowing class methods
=head2 new
    my $safe_string = Valiant::HTML::SafeString->new(@strings);
Given a string, or array of strings, returns a single string that has been C<html_escape>'d as needed
and encapulated in an instance.  Its safe to pass arguments to this without testing since if a string
is already marked safe we don't do any extra escaping (although you will get a new instance).
=head1 INSTANCE METHODS
Instances of L<Valiant::HTML::SafeString> expose the following public methods
=head2 concat
Returns a new safe string which appends a list of strings to the old one, making those new strings
'safe' as needed.  Basically this will escape any strings not marked safe already and then joins them
altogether in a single safe string.
=head2 to_string
Returns the raw string, suitable for display.
=head2 to_bool
Returns a boolean indicating if the string is empty or not.
=head1 OVERLOADING
String context calles C<to_string>; Boolean context returns true unless the string is empty.
=head1 SEE ALSO
  
L<Valiant>, L<Valiant::HTML::FormBuilder>
=head1 AUTHOR
  
See L<Valiant>
=head1 COPYRIGHT & LICENSE
  
See L<Valiant>
=cut