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