[Summary view] [Print] [Text view]

   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