1 package HTML::String::Value;
6 use Scalar::Util qw(blessed);
10 '""' => '_hsv_escaped_string',
12 'bool' => '_hsv_is_true',
20 return $c->_hsv_unescaped_string->new(@_);
22 my ($class, @raw_parts) = @_;
24 my $opts = (ref($raw_parts[-1]) eq 'HASH') ? pop(@raw_parts) : {};
27 if (ref($_) eq 'ARRAY') {
29 } elsif ($_->$_isa(__PACKAGE__)) {
36 my $self = bless { parts => \@parts, %$opts }, $class;
43 (my $meth = our $AUTOLOAD) =~ s/.*:://;
44 die "No such method ${meth} on ${invocant}"
45 unless ref($invocant);
46 return $invocant->_hsv_unescaped_string->$meth(@_);
49 sub _hsv_escaped_string {
52 if ($self->{ignore}{scalar caller}) {
53 return $self->_hsv_unescaped_string;
56 return join '', map +(
69 sub _hsv_unescaped_string {
72 return join '', map $_->[0], @{$self->{parts}};
76 my ($self, $str, $prefix) = @_;
78 return $self unless defined $str && length $str;
80 my @parts = @{$self->{parts}};
83 $str->$_isa(__PACKAGE__)
89 unshift @parts, @new_parts;
91 push @parts, @new_parts;
94 return bless({ %$self, parts => \@parts }, blessed($self));
99 return 1 if grep $_, map $_->[0], @{$self->{parts}};
102 # we need to local $@ here because some modules (cough, TT, cough)
103 # will do a 'die $@ if $@' without realising that it wasn't their eval
111 eval { blessed($self) and $self->_hsv_unescaped_string->isa(@_) }
113 or $self->SUPER::isa(@_)
122 eval { blessed($self) and $self->_hsv_unescaped_string->can(@_) }
124 or $self->SUPER::can(@_)
138 HTML::String::Value - A scalar hiding as a string on behalf of L<HTML::String>
142 Usually, you'd create this with L<HTML::String>'s L<HTML::String/html> export
145 my $html = HTML::String::Value->new($do_not_escape_this);
147 my $html = HTML::String::Value->new([ $do_not_escape_this, 0 ]);
149 my $html = HTML::String::Value->new([ $do_escape_this, 1 ]);
151 my $html = HTML::String::Value->new($already_an_html_string_value);
153 my $html = HTML::String::Value->new(@an_array_of_any_of_the_above);
155 my $html = HTML::String::Value->new(
156 @parts, { ignore => { package_name => 1 } }
163 my $html = HTML::String::Value->new(@parts, \%options?);
165 Each entry in @parts consists of one of:
167 'some text that will not be escaped'
169 [ 'some text that will not be escaped', 0 ]
171 [ 'text that you DO want to be escaped', 1 ]
173 $existing_html_string_value
175 Currently, the %options hashref contains only:
178 ignore => { 'Package::One' => 1, 'Package::Two' => 1, ... }
181 which tells this value object to ignore whether escaping has been requested
182 for any particular chunk and instead to provide the unescaped version.
184 When called on an existing object, does the equivalent of
186 $self->_hsv_unescaped_string->new(@args);
188 to fit in with the "pretending to be a class name" behaviour provided by
191 =head2 _hsv_escaped_string
193 $html->_hsv_escaped_string
195 Returns a concatenation of all parts of this value with those marked for
196 escaping escaped, unless the calling package has been specified in the
197 C<ignore> option to L</new>.
199 If the calling package has been marked as ignoring escaping, returns the
200 result of L</_hsv_unescaped_string>.
202 You probably shouldn't be calling this directly.
204 =head2 _hsv_unescaped_string
206 $html->_hsv_unescaped_string
208 Returns a concatenation of all parts of this value with no escaping performed.
210 You probably shouldn't be calling this directly.
214 $html->_hsv_dot($other_string, $reversed)
216 Returns a new value object consisting of the two values' parts concatenated
217 together (in reverse if C<$reversed> is true).
219 Unlike L</new>, this method defaults to escaping a bare string provided.
221 You probably shouldn't be calling this directly.
227 Returns true if any of this value's parts are true.
229 You probably shouldn't be calling this directly.
233 $html->method_name(@args)
235 This calls the equivalent of
237 $html->_hsv_unescaped_string->method_name(@args)
239 to allow for class method calls even when the class name has ended up being
240 turned into a value object.
246 This method returns true if either the value or the unescaped string are
247 isa the supplied C<$name> in order to allow for class method calls even when
248 the class name has ended up being turned into a value object.
254 This method returns a coderef if either the value or the unescaped string
255 provides this method; methods on the unescaped string are preferred to allow
256 for class method calls even when the class name has ended up being
257 turned into a value object.
263 This method always returns C<''>. Since we register ourselves with
264 L<UNIVERSAL::ref>, this means that
268 will also return C<''>, which means that modules loaded after this one will
269 see a value object as being a plain scalar unless they're explicitly checking
270 the defined-ness of the return value of C<ref>, which probably means that they
271 wanted to spot people cheating like we're trying to.
273 If you have trouble with things trying to treat a value object as something
274 other than a string, try loading L<UNIVERSAL::ref> earlier.
278 Overridden to do nothing so that L</AUTOLOAD> doesn't trap it.
280 =head1 OPERATOR OVERLOADS
282 =head2 stringification
284 Stringification is overloaded to call L</_hsv_escaped_string>
288 Concatentation is overloaded to call L</_hsv_dot>
292 Boolification is overloaded to call L</_hsv_is_true>
296 See L<HTML::String> for authors.
298 =head1 COPYRIGHT AND LICENSE
300 See L<HTML::String> for the copyright and license.