git.maemo.org Git - dh-make-perl/blob - dev/i386/libpod-simple-perl/libpod-simple-perl-3.07/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