3 package Pod::Simple::LinkSection;
4 # Based somewhat dimly on Array::Autojoin
5 use vars qw($VERSION );
9 use Pod::Simple::BlackBox;
10 use vars qw($VERSION );
13 use overload( # So it'll stringify nice
14 '""' => \&Pod::Simple::BlackBox::stringify_lol,
15 'bool' => \&Pod::Simple::BlackBox::stringify_lol,
16 # '.=' => \&tack_on, # grudgingly support
18 'fallback' => 1, # turn on cleverness
22 $_[0] = ['', {}, "$_[0]" ];
23 return $_[0][2] .= $_[1];
27 goto &Pod::Simple::BlackBox::stringify_lol;
30 goto &Pod::Simple::BlackBox::stringify_lol;
35 $class = ref($class) || $class;
38 if (!ref($_[0] || '')) { # most common case: one bare string
39 return bless ['', {}, $_[0] ], $class;
40 } elsif( ref($_[0] || '') eq 'ARRAY') {
41 $new = [ @{ $_[0] } ];
43 Carp::croak( "$class new() doesn't know to clone $new" );
46 $new = [ '', {}, @_ ];
49 # By now it's a treelet: [ 'foo', {}, ... ]
50 foreach my $x (@$new) {
51 if(ref($x || '') eq 'ARRAY') {
52 $x = $class->new($x); # recurse
53 } elsif(ref($x || '') eq 'HASH') {
59 return bless $new, $class;
62 # Not much in this class is likely to be link-section specific --
63 # but it just so happens that link-sections are about the only treelets
64 # that are exposed to the user.
70 # TODO: let it be an option whether a given subclass even wants little treelets?
77 Pod::Simple::LinkSection -- represent "section" attributes of L codes
85 This class is not of interest to general users.
87 Pod::Simple uses this class for representing the value of the
88 "section" attribute of "L" start-element events. Most applications
89 can just use the normal stringification of objects of this class;
90 they stringify to just the text content of the section,
92 C<< LZ<><Stuff/foo> >>, and "bar" for
93 C<< LZ<><Stuff/bIZ<><ar>> >>.
95 However, anyone particularly interested in getting the full value of
96 the treelet, can just traverse the content of the treeleet
97 @$treelet_object. To wit:
100 % perl -MData::Dumper -e
101 "use base qw(Pod::Simple::Methody);
102 sub start_L { print Dumper($_[1]{'section'} ) }
103 __PACKAGE__->new->parse_string_document('=head1 L<Foo/bI<ar>baz>>')
114 ], 'Pod::Simple::LinkSection' ),
116 ], 'Pod::Simple::LinkSection' );
118 But stringify it and you get just the text content:
120 % perl -MData::Dumper -e
121 "use base qw(Pod::Simple::Methody);
122 sub start_L { print Dumper( '' . $_[1]{'section'} ) }
123 __PACKAGE__->new->parse_string_document('=head1 L<Foo/bI<ar>baz>>')
135 Questions or discussion about POD and Pod::Simple should be sent to the
136 pod-people@perl.org mail list. Send an empty email to
137 pod-people-subscribe@perl.org to subscribe.
139 This module is managed in an open GitHub repository,
140 L<http://github.com/theory/pod-simple/>. Feel free to fork and contribute, or
141 to clone L<git://github.com/theory/pod-simple.git> and send patches!
143 Patches against Pod::Simple are welcome. Please send bug reports to
144 <bug-pod-simple@rt.cpan.org>.
146 =head1 COPYRIGHT AND DISCLAIMERS
148 Copyright (c) 2004 Sean M. Burke. All rights reserved.
150 This library is free software; you can redistribute it and/or modify it
151 under the same terms as Perl itself.
153 This program is distributed in the hope that it will be useful, but
154 without any warranty; without even the implied warranty of
155 merchantability or fitness for a particular purpose.
159 Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.
160 But don't bother him, he's retired.
162 Pod::Simple is maintained by:
166 =item * Allison Randal C<allison@perl.org>
168 =item * Hans Dieter Pearcey C<hdp@cpan.org>
170 =item * David E. Wheeler C<dwheeler@cpan.org>