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 use vars qw($VERSION );
   6 $VERSION = '3.26';
   7
   8 use strict;
   9 use Pod::Simple::BlackBox;
  10 use vars qw($VERSION );
  11 $VERSION = '3.26';
  12
  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
  17
  18   'fallback' => 1,         # turn on cleverness
  19 );
  20
  21 sub tack_on {
  22   $_[0] = ['', {}, "$_[0]" ];
  23   return $_[0][2] .= $_[1];
  24 }
  25
  26 sub as_string {
  27   goto &Pod::Simple::BlackBox::stringify_lol;
  28 }
  29 sub stringify {
  30   goto &Pod::Simple::BlackBox::stringify_lol;
  31 }
  32
  33 sub 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
  66 1;
  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
  77 Pod::Simple::LinkSection -- represent "section" attributes of L codes
  78
  79 =head1 SYNOPSIS
  80
  81  # a long story
  82
  83 =head1 DESCRIPTION
  84
  85 This class is not of interest to general users.
  86
  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,
  91 such as "foo" for
  92 C<< LZ<><Stuff/foo> >>, and "bar" for
  93 C<< LZ<><Stuff/bIZ<><ar>> >>.
  94
  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:
  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     "
 105 Output:
 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
 118 But 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     "
 125 Output:
 126   $VAR1 = 'barbaz';
 127
 128
 129 =head1 SEE ALSO
 130
 131 L<Pod::Simple>
 132
 133 =head1 SUPPORT
 134
 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.
 138
 139 This module is managed in an open GitHub repository,
 140 L<https://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!
 142
 143 Patches against Pod::Simple are welcome. Please send bug reports to
 144 <bug-pod-simple@rt.cpan.org>.
 145
 146 =head1 COPYRIGHT AND DISCLAIMERS
 147
 148 Copyright (c) 2004 Sean M. Burke.
 149
 150 This library is free software; you can redistribute it and/or modify it
 151 under the same terms as Perl itself.
 152
 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.
 156
 157 =head1 AUTHOR
 158
 159 Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.
 160 But don't bother him, he's retired.
 161
 162 Pod::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