documentationify

[scpubgit/HTML-String.git] / lib / HTML / String / Overload.pm

package HTML::String::Overload;

use strictures 1;
use HTML::String::Value;
use B::Hooks::EndOfScope;
use overload ();

sub import {
    my ($class, @opts) = @_;
    overload::constant q => sub {
        HTML::String::Value->new($_[1], @opts);
    };
    on_scope_end { __PACKAGE__->unimport };
}

sub unimport {
    overload::remove_constant('q');
}

1;

__END__

=head1 NAME

HTML::String::Overload - Use constant overloading with L<HTML::String>

=head1 SYNOPSIS

  use HTML::String::Overload;
  
  my $html = '<h1>'; # marked as HTML
  
  no HTML::String::Overload;

  my $text = '<h1>'; # not touched
  
  my $html = do {
    use HTML::String::Overload;
  
    '<h1>'; # marked as HTML
  };
  
  my $text = '<h1>'; # not touched

=head1 DESCRIPTION

This module installs a constant overload for strings - see
L<overload/Overloading constants> in overload.pm's docs for how that works.

On import, we both set up the overload, and use L<B::Hooks::EndOfScope> to
register a callback that will remove it again at the end of the block; you
can remove it earlier by unimporting the module using C<no>.

=head1 CAVEATS

Due to a perl bug (L<https://rt.perl.org/rt3/Ticket/Display.html?id=49594>),
you can't use backslash escapes in a string to be marked as HTML, so

  use HTML::String::Overload;
  
  my $html = "<h1>\n<div>foo</div>\n</h1>";

will not be marked as HTML - instead you need to write

  my $html = '<h1>'."\n".'<div>foo</div>'."\n".'</h1>';

which is annoying, so consider just using L<HTML::String> and doing

  my $html = html("<h1>\n<div>foo</div>\n</h1>");

in that case.

The import method we provide does actually take extra options for constructing
your L<HTML::String::Value> objects but I'm not yet convinced that's a correct
public API, so use that feature at your own risk (the only example of this is
in L<HTML::String::TT::Directive>, which is definitely not user serviceable).

=head1 AUTHORS

See L<HTML::String> for authors.

=head1 COPYRIGHT AND LICENSE

See L<HTML::String> for the copyright and license.

=cut