1package Pod::Simple::LinkSection; 2 # Based somewhat dimly on Array::Autojoin 3 4use strict; 5use warnings; 6use Pod::Simple::BlackBox; 7our $VERSION = '3.45'; 8 9use overload( # So it'll stringify nice 10 '""' => \&Pod::Simple::BlackBox::stringify_lol, 11 'bool' => \&Pod::Simple::BlackBox::stringify_lol, 12 # '.=' => \&tack_on, # grudgingly support 13 14 'fallback' => 1, # turn on cleverness 15); 16 17sub tack_on { 18 $_[0] = ['', {}, "$_[0]" ]; 19 return $_[0][2] .= $_[1]; 20} 21 22sub as_string { 23 goto &Pod::Simple::BlackBox::stringify_lol; 24} 25sub stringify { 26 goto &Pod::Simple::BlackBox::stringify_lol; 27} 28 29sub new { 30 my $class = shift; 31 $class = ref($class) || $class; 32 my $new; 33 if(@_ == 1) { 34 if (!ref($_[0] || '')) { # most common case: one bare string 35 return bless ['', {}, $_[0] ], $class; 36 } elsif( ref($_[0] || '') eq 'ARRAY') { 37 $new = [ @{ $_[0] } ]; 38 } else { 39 Carp::croak( "$class new() doesn't know to clone $new" ); 40 } 41 } else { # misc stuff 42 $new = [ '', {}, @_ ]; 43 } 44 45 # By now it's a treelet: [ 'foo', {}, ... ] 46 foreach my $x (@$new) { 47 if(ref($x || '') eq 'ARRAY') { 48 $x = $class->new($x); # recurse 49 } elsif(ref($x || '') eq 'HASH') { 50 $x = { %$x }; 51 } 52 # otherwise leave it. 53 } 54 55 return bless $new, $class; 56} 57 58# Not much in this class is likely to be link-section specific -- 59# but it just so happens that link-sections are about the only treelets 60# that are exposed to the user. 61 621; 63 64__END__ 65 66# TODO: let it be an option whether a given subclass even wants little treelets? 67 68 69__END__ 70 71=head1 NAME 72 73Pod::Simple::LinkSection -- represent "section" attributes of L codes 74 75=head1 SYNOPSIS 76 77 # a long story 78 79=head1 DESCRIPTION 80 81This class is not of interest to general users. 82 83Pod::Simple uses this class for representing the value of the 84"section" attribute of "L" start-element events. Most applications 85can just use the normal stringification of objects of this class; 86they stringify to just the text content of the section, 87such as "foo" for 88C<< LZ<><Stuff/foo> >>, and "bar" for 89C<< LZ<><Stuff/bIZ<><ar>> >>. 90 91However, anyone particularly interested in getting the full value of 92the treelet, can just traverse the content of the treeleet 93@$treelet_object. To wit: 94 95 96 % perl -MData::Dumper -e 97 "use base qw(Pod::Simple::Methody); 98 sub start_L { print Dumper($_[1]{'section'} ) } 99 __PACKAGE__->new->parse_string_document('=head1 L<Foo/bI<ar>baz>>') 100 " 101Output: 102 $VAR1 = bless( [ 103 '', 104 {}, 105 'b', 106 bless( [ 107 'I', 108 {}, 109 'ar' 110 ], 'Pod::Simple::LinkSection' ), 111 'baz' 112 ], 'Pod::Simple::LinkSection' ); 113 114But stringify it and you get just the text content: 115 116 % perl -MData::Dumper -e 117 "use base qw(Pod::Simple::Methody); 118 sub start_L { print Dumper( '' . $_[1]{'section'} ) } 119 __PACKAGE__->new->parse_string_document('=head1 L<Foo/bI<ar>baz>>') 120 " 121Output: 122 $VAR1 = 'barbaz'; 123 124 125=head1 SEE ALSO 126 127L<Pod::Simple> 128 129=head1 SUPPORT 130 131Questions or discussion about POD and Pod::Simple should be sent to the 132pod-people@perl.org mail list. Send an empty email to 133pod-people-subscribe@perl.org to subscribe. 134 135This module is managed in an open GitHub repository, 136L<https://github.com/perl-pod/pod-simple/>. Feel free to fork and contribute, or 137to clone L<https://github.com/perl-pod/pod-simple.git> and send patches! 138 139Patches against Pod::Simple are welcome. Please send bug reports to 140<bug-pod-simple@rt.cpan.org>. 141 142=head1 COPYRIGHT AND DISCLAIMERS 143 144Copyright (c) 2004 Sean M. Burke. 145 146This library is free software; you can redistribute it and/or modify it 147under the same terms as Perl itself. 148 149This program is distributed in the hope that it will be useful, but 150without any warranty; without even the implied warranty of 151merchantability or fitness for a particular purpose. 152 153=head1 AUTHOR 154 155Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. 156But don't bother him, he's retired. 157 158Pod::Simple is maintained by: 159 160=over 161 162=item * Allison Randal C<allison@perl.org> 163 164=item * Hans Dieter Pearcey C<hdp@cpan.org> 165 166=item * David E. Wheeler C<dwheeler@cpan.org> 167 168=back 169 170=cut 171