Move Pod::Simple from ext/ to cpan/
[perl.git] / cpan / Pod-Simple / lib / Pod / Simple / LinkSection.pm
1
2 require 5;
3 package Pod::Simple::LinkSection;
4   # Based somewhat dimly on Array::Autojoin
5
6 use strict;
7 use Pod::Simple::BlackBox;
8
9 use 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
17 sub tack_on {
18   $_[0] = ['', {}, "$_[0]" ];
19   return $_[0][2] .= $_[1];
20 }
21
22 sub as_string {
23   goto &Pod::Simple::BlackBox::stringify_lol;
24 }
25 sub stringify {
26   goto &Pod::Simple::BlackBox::stringify_lol;
27 }
28
29 sub 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
62 1;
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
73 Pod::Simple::LinkSection -- represent "section" attributes of L codes
74
75 =head1 SYNOPSIS
76
77  # a long story
78
79 =head1 DESCRIPTION
80
81 This class is not of interest to general users.
82
83 Pod::Simple uses this class for representing the value of the
84 "section" attribute of "L" start-element events.  Most applications
85 can just use the normal stringification of objects of this class;
86 they stringify to just the text content of the section,
87 such as "foo" for
88 C<< LZ<><Stuff/foo> >>, and "bar" for 
89 C<< LZ<><Stuff/bIZ<><ar>> >>.
90
91 However, anyone particularly interested in getting the full value of
92 the 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     "
101 Output:
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   
114 But 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     "
121 Output:
122   $VAR1 = 'barbaz';
123
124
125 =head1 SEE ALSO
126
127 L<Pod::Simple>
128
129 =head1 COPYRIGHT AND DISCLAIMERS
130
131 Copyright (c) 2002 Sean M. Burke.  All rights reserved.
132
133 This library is free software; you can redistribute it and/or modify it
134 under the same terms as Perl itself.
135
136 This program is distributed in the hope that it will be useful, but
137 without any warranty; without even the implied warranty of
138 merchantability or fitness for a particular purpose.
139
140 =head1 AUTHOR
141
142 Sean M. Burke C<sburke@cpan.org>
143
144 =cut
145