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

TIPS AND TRICKS

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

SEE ALSO

191       ·   article for RJBS Advent 2009
192           <http://advent.rjbs.manxome.org/2009/2009-12-09.html>
193
194       ·   Inline::Files does something that is at first look similar,
195
196           but it works with source filters, and contains the warning:
197
198             It is possible that this module may overwrite the source code in files that
199             use it. To protect yourself against this possibility, you are strongly
200             advised to use the -backup option described in "Safety first".
201
202           Enough said.
203

AUTHOR

205       Ricardo SIGNES <rjbs@cpan.org>
206

CONTRIBUTORS

208       ·   Christian Walde <walde.christian@googlemail.com>
209
210       ·   Dan Kogai <dankogai+github@gmail.com>
211
212       ·   David Golden <dagolden@cpan.org>
213
214       ·   David Steinbrunner <dsteinbrunner@pobox.com>
215
216       ·   Karen Etheridge <ether@cpan.org>
217
218       ·   Kenichi Ishigaki <ishigaki@cpan.org>
219
220       ·   kentfredric <kentfredric+gravitar@gmail.com>
221
222       ·   Tatsuhiko Miyagawa <miyagawa@bulknews.net>
223

225       This software is copyright (c) 2008 by Ricardo SIGNES.
226
227       This is free software; you can redistribute it and/or modify it under
228       the same terms as the Perl 5 programming language system itself.
229
230
231
232perl v5.28.1                      2017-07-07                  Data::Section(3)
Impressum