1 package HTML::String::Value;
9 '""' => '_hsv_escaped_string',
11 'bool' => '_hsv_is_true',
17 if (ref($_[0])) { my $c = shift; return $c->_hsv_unescaped_string->new(@_) }
18 my ($class, @raw_parts) = @_;
20 my $opts = (ref($raw_parts[-1]) eq 'HASH') ? pop(@raw_parts) : {};
23 if (ref($_) eq 'ARRAY') {
25 } elsif ($_->$_isa(__PACKAGE__)) {
32 my $self = bless { parts => \@parts, %$opts }, $class;
39 (my $meth = our $AUTOLOAD) =~ s/.*:://;
40 die "No such method ${meth} on ${invocant}"
41 unless ref($invocant);
42 return $invocant->_hsv_unescaped_string->$meth(@_);
45 sub _hsv_escaped_string {
48 if ($self->{ignore}{scalar caller}) {
49 return $self->_hsv_unescaped_string;
52 return join '', map +(
64 sub _hsv_unescaped_string {
67 return join '', map $_->[0], @{$self->{parts}};
71 my ($self, $str, $prefix) = @_;
73 return $self unless $str;
75 my @parts = @{$self->{parts}};
78 $str->$_isa(__PACKAGE__)
84 unshift @parts, @new_parts;
86 push @parts, @new_parts;
89 return ref($self)->new(@parts, { ignore => $self->{ignore} });
94 return 1 if grep $_, map $_->[0], @{$self->{parts}};
100 eval { $self->_hsv_unescaped_string->isa(@_) }
101 or $self->SUPER::isa(@_)
108 eval { $self->_hsv_unescaped_string->can(@_) }
109 or $self->SUPER::can(@_)
123 HTML::String::Value - A scalar hiding as a string on behalf of L<HTML::String>
127 Usually, you'd create this with L<HTML::String>'s L<HTML::String/html> export
130 my $html = HTML::String::Value->new($do_not_escape_this);
132 my $html = HTML::String::Value->new([ $do_not_escape_this, 0 ]);
134 my $html = HTML::String::Value->new([ $do_escape_this, 1 ]);
136 my $html = HTML::String::Value->new($already_an_html_string_value);
138 my $html = HTML::String::Value->new(@an_array_of_any_of_the_above);
140 my $html = HTML::String::Value->new(
141 @parts, { ignore => { package_name => 1 } }
148 my $html = HTML::String::Value->new(@parts, \%options?);
150 Each entry in @parts consists of one of:
152 'some text that will not be escaped'
154 [ 'some text that will not be escaped', 0 ]
156 [ 'text that you DO want to be scaped', 1 ]
158 $existing_html_string_value
160 Currently, the %options hashref contains only:
163 ignore => { 'Package::One' => 1, 'Package::Two' => 1, ... }
166 which tells this value object to ignore whether escaping has been requested
167 for any particular chunk and instead to provide the unescaped version.
169 When called on an existing object, does the equivalent of
171 $self->_hsv_unescaped_string->new(@args);
173 to fit in with the "pretending to be a class name" behaviour provided by
176 =head2 _hsv_escaped_string
178 $html->_hsv_escaped_string
180 Returns a concatenation of all parts of this value with those marked for
181 escaping escaped, unless the calling package has been specified in the
182 C<ignore> option to L</new>.
184 If the calling package has been marked as ignoring escaping, returns the
185 result of L</_hsv_unescaped_string>.
187 You probably shouldn't be calling this directly.
189 =head2 _hsv_unescaped_string
191 $html->_hsv_unescaped_string
193 Returns a concatenation of all parts of this value with no escaping performed.
195 You probably shouldn't be calling this directly.
199 $html->_hsv_dot($other_string, $reversed)
201 Returns a new value object consisting of the two values' parts concatenated
202 together (in reverse if C<$reversed> is true).
204 Unlike L</new>, this method defaults to escaping a bare string provided.
206 You probably shouldn't be calling this directly.
212 Returns true if any of this value's parts are true.
214 You probably shouldn't be calling this directly.
218 $html->method_name(@args)
220 This calls the equivalent of
222 $html->_hsv_unescaped_string->method_name(@args)
224 to allow for class method calls even when the class name has ended up being
225 turned into a value object.
231 This method returns true if either the value or the unescaped string are
232 isa the supplied C<$name> in order to allow for class method calls even when
233 the class name has ended up being turned into a value object.
239 This method returns a coderef if either the value or the unescaped string
240 provides this method; methods on the unescaped string are preferred to allow
241 for class method calls even when the class name has ended up being
242 turned into a value object.
248 This method always returns C<''>. Since we register ourselves with
249 L<UNIVERSAL::ref>, this means that
253 will also return C<''>, which means that modules loaded after this one will
254 see a value object as being a plain scalar unless they're explicitly checking
255 the defined-ness of the return value of C<ref>, which probably means that they
256 wanted to spot people cheating like we're trying to.
258 If you have trouble with things trying to treat a value object as something
259 other than a string, try loading L<UNIVERSAL::ref> earlier.
263 Overridden to do nothing so that L</AUTOLOAD> doesn't trap it.
265 =head1 OPERATOR OVERLOADS
267 =head2 stringification
269 Stringification is overloaded to call L</_hsv_escaped_string>
273 Concatentation is overloaded to call L</_hsv_dot>
277 Boolification is overloaded to call L</_hsv_is_true>
281 See L<HTML::String> for authors.
283 =head1 COPYRIGHT AND LICENSE
285 See L<HTML::String> for the copyright and license.