File Coverage

blib/lib/Perl6/Pod/Directive/use.pm
Criterion Covered Total %
statement 18 51 35.2
branch 0 14 0.0
condition 0 5 0.0
subroutine 6 8 75.0
pod 1 2 50.0
total 25 80 31.2


line stmt bran cond sub pod time code
1             package Perl6::Pod::Directive::use;
2              
3             =pod
4              
5             =head1 NAME
6              
7             Perl6::Pod::Directive::use - handle =use directive
8              
9             =head1 SYNOPSIS
10              
11             Load the corresponding Perldoc module:
12              
13             =use Test::Tag
14             =for Tag
15             text data
16              
17             Define own formatting code:
18            
19             =use Perldoc::TT
20             =config TT<> :allow
21             head1 Overview of the M class
22              
23              
24             =head1 DESCRIPTION
25              
26             Perldoc provides a mechanism by which you can extend the syntax, semantics, or content of your documentation: the =use directive.
27              
28             Specifying a =use causes a Perldoc processor to load the corresponding Perldoc module at that point, or to throw an exception if it cannot.
29              
30             Such modules can specify additional content that should be included in the document. Alternatively, they can register classes that handle new types of block directives or formatting codes.
31              
32             Note that a module loaded via a =use statement can affect the content or the interpretation of subsequent blocks, but not the initial parsing of those blocks. Any new block types must still conform to the general syntax described in this document. Typically, a module will change the way that renderers parse the contents of specific blocks.
33              
34             A =use directive may be specified with either a module name or a URI:
35              
36             =use MODULE_NAME OPTIONAL CONFIG DATA
37             = OPTIONAL EXTRA CONFIG DATA
38            
39             =use URI
40              
41             If a URI is given, the specified file is treated as a source of Pod to be included in the document. Any Pod blocks are parsed out of the contents of the =use'd file, and added to the main file's Pod representation at that point.
42              
43             If a module name is specified with any prefix except pod:, or without a prefix at all, then the corresponding .pm file (or another language's equivalent code module) is searched for in the appropriate module library path. If found, the code module require'd into the Pod parser (usually to add a class implementing a particular Pod extension). If no such code module is found, a suitable .pod file is searched for instead, the contents parsed as Pod, and the resulting block objects inserted into the main file's representation
44              
45             Any options that are specified after the module name:
46              
47             =use Perldoc::Plugin::Image :Jpeg prefix=>'http://dev.perl.org'
48              
49             are passed to the internal require that loads the corresponding module.
50              
51             Collectively these alternatives allow you to create standard documentation inserts or stylesheets, to include Pod extracted from other code files, or to specify new types of documentation blocks and formatting codes:
52              
53             =over
54              
55             =item * To create a standard Pod insertion or stylesheet, create a .pod file and install it in your documentation path. Load it with either:
56              
57             =use Pod::Insertion::Name
58              
59             or:
60              
61             =use pod:Pod::Insertion::Name
62              
63             or:
64              
65             =use file:/full/path/spec/Pod/Insertion/Name.pod
66              
67             or even:
68              
69             =use http://www.website.com/Pod/Insertion/Name.pod
70              
71             =item * To insert the Pod from a .pm file (for example, to have your class documentation include documentation from a base class):
72              
73             =use pod:Some::Other::Module
74              
75             =item * To implement a new Pod block type or formatting code, create a .pm file and load it with either:
76              
77             =use New::Perldoc::Subclass
78              
79             or (more explicitly):
80              
81             =use perl6:New::Perldoc::Subclass
82              
83             =item * To create a module that inserts Pod and also require's a parser extension, install a .pod file that contains a nested =use that imports the necessary plug-in code. Then load the Pod file as above.
84              
85             A typical example would be a Perldoc extension that also needs to specify some preconfiguration:
86              
87             =use Hybrid::Content::Plus::Extension
88              
89             Then, in the file some_perl_doc_dir/Hybrid/Content/Plus/Extension.pod:
90              
91             =begin code :allow
92             =comment This file sets some config and also enables the Graph block
93              
94             =config Graph :formatted< B >
95              
96             =use perl6:Perldoc::Plugin::Graph-(*)-cpan:MEGAGIGA
97             =end code
98              
99             Note that =use is a fundamental Perldoc directive, like =begin or =encoding, so there is no paragraph or delimited form of =use.
100              
101             =back
102              
103             =head1 NOTES
104              
105             Perl6::Pod handle exended syntax:
106              
107             =use MODULE_NAME FORMAT_CODE<> OPTIONAL CONFIG DATA
108             = OPTIONAL EXTRA CONFIG DATA
109              
110             =use MODULE_NAME BLOCK_NAME OPTIONAL CONFIG DATA
111             = OPTIONAL EXTRA CONFIG DATA
112              
113             Fo example:
114              
115             =comment Overwrite default class for standart formatting code
116             =use Perldoc::TT B<>
117              
118             =comment Define custom BlockNames
119             =use Perldoc::TT Alias1
120             =use Perldoc::TT Alias2
121              
122             Perl6::Pod also handle ${PERL6POD} variable in package namespace. It used for evalute Pod chunk for
123             loaded Module.
124              
125             For package contains variable $PERL6POD:
126              
127             package UserDefined::Lib;
128             use strict;
129             use warnings;
130             our $PERL6POD = <
131             =begin pod
132             =use UserDefined::Module
133             =use UserDefined::Image
134             =end pod
135             POD
136             1;
137              
138             We can evalute Pod in the Pod file:
139              
140             =begin pod
141             =comment Evalute $PERL6POD
142             =use UserDefined::Lib
143             =comment Now will use =Image block
144             =Image http://example.com/image.png
145             =end pod
146              
147              
148             =cut
149              
150 3     3   13 use warnings;
  3         5  
  3         84  
151 3     3   13 use strict;
  3         6  
  3         58  
152 3     3   17 use Perl6::Pod::Block;
  3         5  
  3         68  
153 3     3   15 use base 'Perl6::Pod::Block';
  3         6  
  3         1257  
154             our $VERSION = '0.01';
155              
156             sub new {
157 0     0 1   my ( $class, %args ) = @_;
158 0           my $self = $class->SUPER::new(%args, parent_context=>1);
159             }
160              
161             sub start {
162 0     0 0   my $self = shift;
163 0           my ( $parser, $attr ) = @_;
164 0           $self->delete_element->skip_content;
165             #handle
166             #=use Module::Name block_name :config_attr
167 0           my $opt = $self->{_pod_options};
168 0           my ( $class, @params ) = split( /\s+/, $opt );
169 0           my $prefix;
170             #extract prefix
171 0 0         if ( $class =~ /^(\w+)\:([^:][\w\:]+)$/ ) {
172             #if perl
173 0           ( $prefix, $class ) = ($1,$2);
174             }
175             #now determine name
176 0           my $name;
177 0 0 0       if ( $params[0] and $params[0] !~ /^:/) {
178 0           $name = shift @params
179             }
180 0 0         unless ( $name ) { #get name from class
181 0           ( $name ) = reverse split( /::/, $class);
182             }
183              
184 0           $self->{_pod_options} = join " ", @params;
185              
186             #try to load class
187             # eval "use $class";
188             #check non loaded mods
189              
190             #check non loaded mods
191 0           my ( $main, $module ) = $class =~ m/(.*\:\:)?(\S+)$/;
192 0   0       $main ||= 'main::';
193 0           $module .= '::';
194 3     3   17 no strict 'refs';
  3         6  
  3         474  
195 0 0         unless ( exists $$main{$module} ) {
196 0           eval "use $class";
197 0 0         if ($@) {
198 0           warn "Error register class :$class with $@ ";
199 0           return "Error register class :$class with $@ ";
200 0           next;
201             }
202             }
203             #special handles for =use UserDefined::Lib
204             #use $PERL6POD for include
205 0 0         unless ( UNIVERSAL::isa( $class, 'Perl6::Pod::Block' ) ) {
206 0           my $perl6pod = ${ "${class}::PERL6POD" };
  0            
207 0 0         return unless defined ($perl6pod);
208             #check if exists special variable
209 0           $parser->_parse_chunk(\$perl6pod);
210 0           return;
211             }
212 3     3   13 use strict 'refs';
  3         6  
  3         286  
213              
214 0           $parser->current_context->use->{$name} = $class;
215             #store class options for loaded mods
216 0           $parser->current_context->class_opts->{$name} = $self->{_pod_options};
217             }
218              
219             1;
220             __END__