Commit | Line | Data |
351625bd |
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 | |