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 +(
65 sub _hsv_unescaped_string {
68 return join '', map $_->[0], @{$self->{parts}};
72 my ($self, $str, $prefix) = @_;
74 return $self unless $str;
76 my @parts = @{$self->{parts}};
79 $str->$_isa(__PACKAGE__)
85 unshift @parts, @new_parts;
87 push @parts, @new_parts;
90 return ref($self)->new(@parts, { ignore => $self->{ignore} });
95 return 1 if grep $_, map $_->[0], @{$self->{parts}};
101 eval { $self->_hsv_unescaped_string->isa(@_) }
102 or $self->SUPER::isa(@_)
109 eval { $self->_hsv_unescaped_string->can(@_) }
110 or $self->SUPER::can(@_)
124 HTML::String::Value - A scalar hiding as a string on behalf of L<HTML::String>
128 Usually, you'd create this with L<HTML::String>'s L<HTML::String/html> export
131 my $html = HTML::String::Value->new($do_not_escape_this);
133 my $html = HTML::String::Value->new([ $do_not_escape_this, 0 ]);
135 my $html = HTML::String::Value->new([ $do_escape_this, 1 ]);
137 my $html = HTML::String::Value->new($already_an_html_string_value);
139 my $html = HTML::String::Value->new(@an_array_of_any_of_the_above);
141 my $html = HTML::String::Value->new(
142 @parts, { ignore => { package_name => 1 } }
149 my $html = HTML::String::Value->new(@parts, \%options?);
151 Each entry in @parts consists of one of:
153 'some text that will not be escaped'
155 [ 'some text that will not be escaped', 0 ]
157 [ 'text that you DO want to be escaped', 1 ]
159 $existing_html_string_value
161 Currently, the %options hashref contains only:
164 ignore => { 'Package::One' => 1, 'Package::Two' => 1, ... }
167 which tells this value object to ignore whether escaping has been requested
168 for any particular chunk and instead to provide the unescaped version.
170 When called on an existing object, does the equivalent of
172 $self->_hsv_unescaped_string->new(@args);
174 to fit in with the "pretending to be a class name" behaviour provided by
177 =head2 _hsv_escaped_string
179 $html->_hsv_escaped_string
181 Returns a concatenation of all parts of this value with those marked for
182 escaping escaped, unless the calling package has been specified in the
183 C<ignore> option to L</new>.
185 If the calling package has been marked as ignoring escaping, returns the
186 result of L</_hsv_unescaped_string>.
188 You probably shouldn't be calling this directly.
190 =head2 _hsv_unescaped_string
192 $html->_hsv_unescaped_string
194 Returns a concatenation of all parts of this value with no escaping performed.
196 You probably shouldn't be calling this directly.
200 $html->_hsv_dot($other_string, $reversed)
202 Returns a new value object consisting of the two values' parts concatenated
203 together (in reverse if C<$reversed> is true).
205 Unlike L</new>, this method defaults to escaping a bare string provided.
207 You probably shouldn't be calling this directly.
213 Returns true if any of this value's parts are true.
215 You probably shouldn't be calling this directly.
219 $html->method_name(@args)
221 This calls the equivalent of
223 $html->_hsv_unescaped_string->method_name(@args)
225 to allow for class method calls even when the class name has ended up being
226 turned into a value object.
232 This method returns true if either the value or the unescaped string are
233 isa the supplied C<$name> in order to allow for class method calls even when
234 the class name has ended up being turned into a value object.
240 This method returns a coderef if either the value or the unescaped string
241 provides this method; methods on the unescaped string are preferred to allow
242 for class method calls even when the class name has ended up being
243 turned into a value object.
249 This method always returns C<''>. Since we register ourselves with
250 L<UNIVERSAL::ref>, this means that
254 will also return C<''>, which means that modules loaded after this one will
255 see a value object as being a plain scalar unless they're explicitly checking
256 the defined-ness of the return value of C<ref>, which probably means that they
257 wanted to spot people cheating like we're trying to.
259 If you have trouble with things trying to treat a value object as something
260 other than a string, try loading L<UNIVERSAL::ref> earlier.
264 Overridden to do nothing so that L</AUTOLOAD> doesn't trap it.
266 =head1 OPERATOR OVERLOADS
268 =head2 stringification
270 Stringification is overloaded to call L</_hsv_escaped_string>
274 Concatentation is overloaded to call L</_hsv_dot>
278 Boolification is overloaded to call L</_hsv_is_true>
282 See L<HTML::String> for authors.
284 =head1 COPYRIGHT AND LICENSE
286 See L<HTML::String> for the copyright and license.