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