1Data::Section(3)      User Contributed Perl Documentation     Data::Section(3)
2
3
4

NAME

6       Data::Section - read multiple hunks of data out of your DATA section
7

VERSION

9       version 0.101620
10

SYNOPSIS

12         package Letter::Resignation;
13         use Data::Section -setup;
14
15         sub quit {
16           my ($class, $angry, %arg) = @_;
17
18           my $template = $self->section_data(
19             ($angry ? "angry_" : "professional_") . "letter"
20           );
21
22           return fill_in($$template, \%arg);
23         }
24
25         __DATA__
26         __[ angry_letter ]__
27         Dear jerks,
28
29           I quit!
30
31         --
32         {{ $name }}
33         __[ professional_letter ]__
34         Dear {{ $boss }},
35
36           I quit, jerks!
37
38
39         --
40         {{ $name }}
41

DESCRIPTION

43       Data::Section provides an easy way to access multiple named chunks of
44       line-oriented data in your module's DATA section.  It was written to
45       allow modules to store their own templates, but probably has other
46       uses.
47

WARNING

49       You will need to use "__DATA__" sections and not "__END__" sections.
50       Yes, it matters.  Who knew!
51

EXPORTS

53       To get the methods exported by Data::Section, you must import like
54       this:
55
56         use Data::Section -setup;
57
58       Optional arguments may be given to Data::Section like this:
59
60         use Data::Section -setup => { ... };
61
62       Valid arguments are:
63
64         inherit      - if true, allow packages to inherit the data of the packages
65                        from which they inherit; default: true
66
67         header_re    - if given, changes the regex used to find section headers
68                        in the data section; it should leave the section name in $1
69
70         default_name - if given, allows the first section to has no header and set
71                        its name
72
73       Three methods are exported by Data::Section:
74
75   section_data
76         my $string_ref = $pkg->section_data($name);
77
78       This method returns a reference to a string containing the data from
79       the name section, either in the invocant's "DATA" section or in that of
80       one of its ancestors.  (The ancestor must also derive from the class
81       that imported Data::Section.)
82
83       By default, named sections are delimited by lines that look like this:
84
85         __[ name ]__
86
87       You can use as many underscores as you want, and the space around the
88       name is optional.  This pattern can be configured with the "header_re"
89       option (see above).
90
91       When a line containing only "__END__" is reached, all processing of
92       sections ends.
93
94   section_data_names
95         my @names = $pkg->section_data_names;
96
97       This returns a list of all the names that will be recognized by the
98       "section_data" method.
99
100   merged_section_data
101         my $data = $pkg->merged_section_data;
102
103       This method returns a hashref containing all the data extracted from
104       the package data for all the classes from which the invocant inherits
105       -- as long as those classes also inherit from the package into which
106       Data::Section was imported.
107
108       In other words, given this inheritence tree:
109
110         A
111          \
112           B   C
113            \ /
114             D
115
116       ...if Data::Section was imported by A, then when D's
117       "merged_section_data" is invoked, C's data section will not be
118       considered.  (This prevents the read position of C's data handle from
119       being altered unexpectedly.)
120
121       The keys in the returned hashref are the section names, and the values
122       are references to the strings extracted from the data sections.
123
124   merged_section_data_names
125         my @names = $pkg->merged_section_data_names;
126
127       This returns a list of all the names that will be recognized by the
128       "merged_section_data" method.
129
130   local_section_data
131         my $data = $pkg->local_section_data;
132
133       This method returns a hashref containing all the data extracted from
134       the package on which the method was invoked.  If called on an object,
135       it will operate on the package into which the object was blessed.
136
137       This method needs to be used carefull, because it's weird.  It returns
138       only the data for the package on which it was invoked.  If the package
139       on which it was invoked has no data sections, it returns an empty
140       hashref.
141
142   local_section_data_names
143         my @names = $pkg->local_section_data_names;
144
145       This returns a list of all the names that will be recognized by the
146       "local_section_data" method.
147

TIPS AND TRICKS

149   MooseX::Declare and namespace::autoclean
150       The namespace::autoclean library automatically cleans foreign routines
151       from a class, including those imported by Data::Section.
152
153       MooseX::Declare does the same thing, and can also cause your "__DATA__"
154       section to appear outside your class's package.
155
156       These are easy to address.  The Sub::Exporter::ForMethods library
157       provides an installer that will cause installed methods to appear to
158       come from the class and avoid autocleaning.  Using an explicit
159       "package" statement will keep the data section in the correct package.
160
161          package Foo;
162
163          use MooseX::Declare;
164          class Foo {
165
166            # Utility to tell Sub::Exporter modules to export methods.
167            use Sub::Exporter::ForMethods qw( method_installer );
168
169            # method_installer returns a sub.
170            use Data::Section { installer => method_installer }, -setup;
171
172            method my_method {
173               my $content_ref = $self->section_data('SectionA');
174
175               print $$content_ref;
176            }
177          }
178
179          __DATA__
180          __[ SectionA ]__
181          Hello, world.
182

SEE ALSO

184       Inline::Files does something that is at first look similar, but it
185       works with source filters, and contains the warning:
186
187         It is possible that this module may overwrite the source code in files that
188         use it. To protect yourself against this possibility, you are strongly
189         advised to use the -backup option described in "Safety first".
190
191       Enough said.
192

AUTHOR

194         Ricardo SIGNES <rjbs@cpan.org>
195

197       This software is copyright (c) 2010 by Ricardo SIGNES.
198
199       This is free software; you can redistribute it and/or modify it under
200       the same terms as the Perl 5 programming language system itself.
201
202
203
204perl v5.12.1                      2010-06-11                  Data::Section(3)
Impressum